Difference between revisions of "EclipseLink/Examples/JPA/Multitenant/Tutorial"

Revision as of 18:37, 2 October 2011

EclipseLInk Multi-Tenant Tutorial

This tutorial will walk a developer through the steps necessary to take a simple domain model mapped with JPA and make it multitenant enabled with both EclipseLInk managed additional criteria as well as Oracle Virtual Private Database (VPD) usage.

Overview

1. Setup and configure environment
   1. Run basic tests
2. Configure for multi-tenancy using EclipseLink to apply additional tenant criteria
   1. Run multi-tenant tests
3. Configure for multi-tenancy using EclipseLink and Oracle VPD
   1. Run multi-tenant VPD tests

Software Requirements

• EclipseLink 2.3.1 - build 20110910 or later
  • nightly build - installer
• Example application (SVN)
• Oracle Database
  • Must support Oracle VPD
  • Database user must have proper priviledges

Application Domain

In the tutorial the domain being used is that of a sports league. The web application allows interested users to view information about various leagues with their Division(s), Team(s), and Player(s).

Tutorial Steps

NOTE: Please follow the steps carefully.

This tutorial provides a sample application that is ready to run and includes JUnit tests which create the schema, populate the sample data, and run example persistence operations to verify proper functionality. At each stage of the tutorial a different set of tests will be run.

Setup

After downloading the tutorial source (zip file) you must perform the following steps:

1.1. Unzip the tutorial

The zip file can be unzipped into any folder.

= 1.2. Open the tutorial projects in Eclipse

Using the Eclipse project explorer's import existing projects you opne the project named org.eclipse.persistence.example.jpa.vpd.

1.3. Configure the Project

Configure the project's classpath and dependent libraries. Make sure all libraries configured in the project exist and the project compiles successfully.

As you can see this project, which runs in Java SE, only requires:

• EclipseLink library
• Java Persistence (JPA) 2.0
• JDBC driver

1.4. Run Tests

In order to validate that the project and environment are properly configured you will need to run the Example Initial Tests from the main run menu:

Phase 1: @Multitenant

In the first phase of this tutorial we will convert this simple application from being a single tenant allowing use of all data to a multitenant version where each user can only see their own tasks.

1.1 Modify Task Class

The only real change required in this phase of the tutorial is to enable multi-tenancy on the entity class Task. You will need to add the @Multitenant and @TenantDiscriminatorColumn annotations so the class looks like:

@Entity
@Multitenant
@TenantDiscriminatorColumn(name = "USER_ID", contextProperty = "example.user-id")
@NamedQuery(name = "Task.findByDescription", query = "SELECT t FROM Task t WHERE t.description = :DESC")
public class Task {

The @Multitenant annotation indicates that entity data from multiple tenants will be stored in the same table using the SINGLE_TABLE strategy (default). This means that EclipseLink must augment all generated SQL when querying the database and it must populate the table's columns which are used to identify the tenant. Since we don't want to use the dfeault column name we are specifying the column and the context property name used to identify the tenant using the @TenantDiscriminatorColumn.

1.2. Run Tests

In this phase you will need to run the "Example Multitenant Tests" run configuration. This will run a set of JUnit tests which verify the configuration and exercise the functionality. This run configuration is available under the main run menu as:

1.3. Observe Results

In addition to all of the tests passing you will want to observe the changes in the application's behaviour based on your changes to the Task class.

[EL Fine]: SELECT ID, USER_ID, DESCRIPTION, STATUS, VERSION, PARENT_ID FROM TASK WHERE ((DESCRIPTION = ?) AND (USER_ID = ?))
	bind => [ORDER Pizza, bsmith]
[EL Fine]: UPDATE TASK SET STATUS = ?, VERSION = ? WHERE ((ID = ?) AND (VERSION = ?))
	bind => [COMPLETED, 2, 1, 1]

Note that the SQL is augmented form the initial tests so that the SELECT's include a comparison for the USER_ID.

Phase 2: @Multitenant(VPD)

In this stage of the tutorial you are going to switch from using EclipseLink's additional criteria being added to all queries on @Multitenant types to the database looking after the additional criteria. This approach is specific to the Oracle database and allows all users of the database to leverage the same logic filtering.

2.1. Setup Database

In order to use Oracle VPD the user 'mttorial will need to have permission. This requires the user to have specific permissions or to have the DBA role. For simplicity in this tutorial you will simply grant the user the DBA role.

2.2. Modify Task Class

@Entity
@Multitenant(MultitenantType.VPD)
@TenantDiscriminatorColumn(name = "USER_ID", contextProperty = "example.user-id")
@NamedQuery(name = "Task.findByDescription", query = "SELECT t FROM Task t WHERE t.description = :DESC")
public class Task {

2.3. Run Tests

In this phase you will need to run the EclipseLink Multitenant(VPD) tests run configuration.

2.4. Observer Results

[EL Fine]: CALL DBMS_SESSION.SET_IDENTIFIER(?)
	bind => [bsmith]
[EL Fine]: SELECT ID, USER_ID, DESCRIPTION, STATUS, VERSION, PARENT_ID FROM TASK WHERE (DESCRIPTION = ?)
	bind => [ORDER Pizza]
[EL Fine]: UPDATE TASK SET STATUS = ?, VERSION = ? WHERE ((ID = ?) AND (VERSION = ?))
	bind => [COMPLETED, 2, 1, 1]
[EL Fine]: CALL DBMS_SESSION.CLEAR_IDENTIFIER()