EclipseLink/Examples/JPA/Multitenant/Tutorial

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. Unzip the tutorial

2. Open the tutorial projects in Eclipse

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

4. Verify correct application behaviour.

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

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.

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.