Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

EclipseLink/Development/Indigo/Multi-Tenancy

< EclipseLink‎ | Development‎ | Indigo
Revision as of 13:29, 14 March 2011 by Guy.pelletier.oracle.com (Talk | contribs) (Eclipselink-orm.xml)

Enhancement request: bug 337323

Multi-Tenancy

The goal of this feature is to allow multiple application tenants to share the same schema using tenant identifying column(s). It is for shared 'striped' database data.

Requirements

  1. Support configuration of shared multi-tenant entity types using EclipseLink specific annotations and/or eclispelink-orm.xml with the XML overriding the annotation.
    • Augment database queries to limit query results to the tenant identifier values provided as property values
    • Ensure all INSERT, UPDATE, DELETE operations populate and limit their effect to the defined tenant identifiers
  2. Support accessing shared data at either the EntityManagerFactory or EntityManager
    • When using EMF the underlying cache must be unique to the provided tenant identifiers
  3. Support the tenant identifier columns being:
    • un-mapped (see examples below)
    • mapped (see examples below)
  4. Support schema generation including the specified tenant identifier column(s). Default type will be based on any mapping if available otherwise it will be assumed to be a string and override with the column's definition

Metadata Configuration

With this new feature developers will be able to enable shared tenant table(s) usage at the entity level using one or more columns associated with persistence unit or context property values that must be provided. The tenant identifier column is completely application definable. The user can pick any property or column name they wish or let Eclipselink use defaults. Also there is no limit on the number of tenant identifier columns an application can configure. For this release we will support only the SINGLE_TABLE multitenant type. The multitenant type SINGLE_TABLE states that the table(s) (@Table and @SecondaryTable) for the given entity is shared amongst tenants. (see the annotation and xml definitions below)

@Entity
@Table(name=“EMP”)
@Multitenant(
  type = SINGLE_TABLE,
  tenantDiscriminators = @TenantDiscriminator(name=“tenant-id”, columnName=“TENANT_ID”)
)
public class Employee {
    ...
}
EMP_ID VERSION F_NAME L_NAME GENDER TENANT_ID
1 1 John Doe M 1
2 3 Jane Doe F 2

The following new EclipseLink metadata will be added.

Annotations

The new multitenant annotation metadata is used in conjunction with the @Table. Since we can not add the new annotations to the existing JPA @Table, the new annotations are used on their own.

@Target({TYPE}) 
@Retention(RUNTIME)
public @interface Multitenant {
    /**
     * (Optional) Specify the multi-tenant strategy to use.
     */
    MultitenantType type() default MultitenantType.SINGLE_TABLE;
 
    /**
     * (Optional) One or more <code>TenantDiscriminator</code> annotations
     * when the SINGLE_TABLE type is used.
     */
    TenantDiscriminator[] tenantDiscriminators() default {};
}
 
@Target({TYPE}) 
@Retention(RUNTIME)
public @interface TenantDiscriminator {
    /**
     * (Optional) The name of the context property to apply to the 
     * tenant dsicriminator column.
     */
    String name() default "eclipselink.tenant-id";
 
    /**
     * (Optional) The name of column to be used for the discriminator.
     */
    String columnName() default "TENANT_ID";
 
    /**
     * (Optional) The type of object/column to use as a class discriminator.
     * Defaults to {@link DiscriminatorType#STRING DiscriminatorType.STRING}.
     */
    DiscriminatorType type() default DiscriminatorType.STRING;
 
    /**
     * (Optional) The SQL fragment that is used when generating the DDL
     * for the discriminator column.
     * <p> Defaults to the provider-generated SQL to create a column
     * of the specified discriminator type.
     */
    String columnDefinition() default "";
 
    /**
     * (Optional) The column length for String-based discriminator types.
     * Ignored for other discriminator types.
     */
    int length() default 31;
 
    /**
     * (Optional) The name of the table that contains the column.
     * If absent the column is assumed to be in the primary table.
     */
    String table() default "";
 
    /**
     * Specifies that the tenant discriminator column is part of the primary 
     * key of the tables.
     */
    boolean primaryKey() default false; 
}
 
public enum MultitenantType {
    /**
     * Specifies that table(s) the entity maps to includes rows for multiple tenants. 
     * The tenant discriminator column(s) are used with application context values to
     * limit what a persistence context can access.
     */
    SINGLE_TABLE, 
 
    /**
     * Specifies that different tables are used for each tenant. The table scan be uniquely
     * identified by name, schema/tablespace.
     */
    TABLE_PER_TENANT 
}

Eclipselink-orm.xml

The multitenant metadata in XML will be available within the table complex element.

  <xsd:complexType name="table">
    <xsd:annotation>
      <xsd:documentation>
      ...
      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      ...
      <xsd:element name="multitenant" type="orm:multitenant" minOccurs="0"/>
    </xsd:sequence>
    ...
  </xsd:complexType>
 
<!-- **************************************************** -->
 
<xsd:complexType name="multitenant">
  <xsd:annotation>
    <xsd:documentation>
      ...
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
    <xsd:element name="tenant-discriminator" type="orm:tenant-discriminator" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="type" type="orm:multitenant-type"/>
</xsd:complexType>
 
<!-- **************************************************** -->
 
<xsd:complexType name="tenant-discriminator">
  <xsd:annotation>
    <xsd:documentation>
      ...
    </xsd:documentation>
  </xsd:annotation>
  <xsd:attribute name="name" type="xsd:string"/>
  <xsd:attribute name="column-name" type="xsd:string"/>
  <xsd:attribute name="type" type="orm:discriminator-type"/>
  <xsd:attribute name="column-definition" type="xsd:string"/>
  <xsd:attribute name="table" type="xsd:string"/>
  <xsd:attribute name="length" type="xsd:int"/>
  <xsd:attribute name="primary-key" type="xsd:boolean"/>
</xsd:complexType>
 
<!-- **************************************************** -->
 
<xsd:simpleType name="multitenant-type">
  <xsd:annotation>
    <xsd:documentation>
      ...
    </xsd:documentation>
  </xsd:annotation>
  <xsd:restriction base="xsd:token">
    <xsd:enumeration value="SINGLE_TABLE"/>
    <xsd:enumeration value="TABLE_PER_TENANT"/>
  </xsd:restriction>
</xsd:simpleType>

Minimal Configuration

All parts of the Multitenant metadata are defaulted (see annotation definition above), therefore the minimal configuration is:

@Entity
@Table(name="EMP")
@Multitenant
public Employee() {
  ...
}
<entity class="model.Employee">
  <table name="EMP">
    <multitenant/>
  </table>
  ...
</entity>

Accessibility

The new metadata will available at the following levels:

  • @Entity
  • table
  • @MappedSuperclass
  • entity-mappings
  • persistence-unit-defaults

When specified at the MappedSuperclass level, the tenant metadata will apply to all sub-entities of that class unless they specify their own tenant column metadata. Within an inheritance hierarchy, tenant column metadata can only be applied at the root level of the inheritance hierarchy. A log warning will be issued otherwise.

In the eclipselink-orm.xml, it is possible to specify a default tenant column metadata through the persistence unit metadata defaults.

<xsd:complexType name="persistence-unit-defaults">
  ...
    <xsd:sequence>
     ...
       <xsd:element name="tenant-column" type="orm:tenant-column" minOccurs="0" maxOccurs="unbounded"/>
     ...
    </xsd:sequence>
</xsd:complexType>

When this default value is specified, it will be applied to all entities of the persistence unit minus those that specify their own tenant column metadata. Alternatively, users may specify tenant column metadata at the entity-mappings level as well which would override a persistence unit default and apply itself to all entities of the given mapping file (unless they individual entities have specified their own metadata). This follows similar JPA XML metadata overriding rules.

<xsd:element name="entity-mappings">
  ...
    <xsd:sequence>
     ...
       <xsd:element name="tenant-column" type="orm:tenant-column" minOccurs="0" maxOccurs="unbounded"/>
     ...
    </xsd:sequence>
</xsd:complexType>

Any entity not marked with tenant column metadata and with no persistence unit default will not populate a tenant column in the database (will not be striped).

Mapped vs. Unmapped

When a tenant column is mapped, its associated attribute should be marked as read only. If it is not, a log warning is issued and EclipseLink forces the mapping to be read only. NOTE: this is not the case in a mapped id case which can't be set to read only. On persist, the value of the mapped tenant column mapping is populated from its associated session property.

Both mapped and unmapped properties are used to form the additional criteria when issuing a select query.

Unmapped tenant columns will require EclipseLink to populate the row with the tenant columns associated session property value. See Core section below.

Mapped Tenant Column Part of Entity Identifier

When mapping a tenant column as part of the Entity identifier, this opens a couple different scenarios/expectations. Given the following model:

@Entity
@Table(name="PLAYER")
@TenantColumn(name="tenant.id", columnName="TENANT_ID")
public Player() {
  @Id
  public int id;
 
  @Id
  @Basic
  @Column(name="TENANT_ID")
  public int tenantId;
 
  @OneToOne
  public Address address;
}
 
@Entity
@Table(name="ADDRESS")
@TenantColumn(name="tenant.id", columnName="TENANT_ID")
public Address() {
  @Id
  public int id;
 
  @Id
  @Basic
  @Column(name="TENANT_ID")
  public int tenantId;
}

How should this be reflected on the database? Two scenarios for the PLAYER table given the ADDRESS table:

ADDRESS
------------------
| ID | TENANT_ID |
------------------

Scenario 1:

PLAYER
----------------------------------------------------
| ID | TENANT_ID |  ADDRESS_ID | ADDRESS_TENANT_ID |
----------------------------------------------------

Scenario 2:

PLAYER
--------------------------------
| ID | TENANT_ID |  ADDRESS_ID |
--------------------------------

Scenario 1 could be handled today quite easily and transparently. However, scenario 2 is likely preferred (certainly by DBA's) but does open up a number of other questions and issues.

Metadata Processing Warnings and Exceptions

  • When tenant column metadata is applied to subclasses of an entity hierarchy (JOINED or SINGLE_TABLE) a log warning will be issued
    • NOTE: Tenant column metadata can be provided in a TABLE_PER_CLASS inheritance hierarchy.
  • When multiple properties map the same column.
  • Duplicate tenant column will log a warning message, e.g.
    • @TenantColumn(columnName="TENANT")
    • @TenantColumn(name="eclipselink.tenant-id", columnName="TENANT")
  • A mapped tenant column that who's attribute is not marked read only will log a warning (that it is being forced to read only)

Defaults will always apply even when there are multiple tenant columns and no exception above has been raise. This allows users to map several columns for the same property. E.g. The code below would default the property name to "eclipselink.tenant-id" and states it should be writing the TENANT column for both the EMPLOYEE and SALARY table.

@Entity
@Table(name="EMPLOYEE")
@SecondaryTable(name="SALARY")
@TenantColumns({
  @TenantColumn(columnName="TENANT")
  @TenantColumn(columnName="TENANT", table="SALARY")
})
public Employee() {
  ...
}

Examples

Annotation examples

/** Single tenant column **/
 
@Entity
@Table(name="CUSTOMER")
@TenantColumn(name="multi-tenant.id", columnName="TENANT")
public Customer() {
  ...
}
 
/** Multiple tenant columns using multiple tables **/
 
@Entity
@Table(name="EMPLOYEE")
@SecondaryTable(name="RESPONSIBILITIES")
@TenantColumns({
  @TenantColumn(name="employee-tenant.id", columnName="TENANT_ID", length=20)
  @TenantColumn(name="employee-tenant.code", columnName="TENANT_CODE", discriminatorType=STRING, table="RESPONSIBILITIES")
})
public Employee() {
  ...
}
 
/** Tenant column mapped as part of the primary key on the database **/
 
@Entity
@Table(name="ADDRESS")
@TenantColumn(name="tenant.id", columnName="TENANT", primaryKey=true)
public Address() {
  ...
}
 
/** Mapped Tenant column **/
 
@Entity
@Table(name="Player")
@TenantColumn(name="tenant.age", columnName="AGE")
public Player() {
  ...
 
  @Basic
  @Column(name="AGE")
  @ReadOnly
  public int age;
}

XML examples

<!-- Single tenant column -->
 
<entity class="model.Customer">
  <table name="CUSTOMER" />
  <tenant-column name="multi-tenant.id" column-name="TENANT"/>
  ...
</entity>
 
<!-- Multiple tenant columns using multiple tables -->
 
<entity class="model.Employee">
  <table name="EMPLOYEE" />
  <secondary-table name="RESPONSIBILITIES"/>
  <tenant-column name="employee-tenant.id" column-name="TENANT_ID" length="20"/>
  <tenant-column name="employee-tenant.id" column-name="TENANT_CODE" discriminatorType="STRING" table="RESPONSIBILITIES"/>
  ...
</entity>
 
<!-- Tenant column mapped as part of the primary key on the database -->
 
<entity class="model.Address">
  <table name="ADDRESS" />
  <tenant-column name="multi-tenant.id" column-name="TENANT" primary-key="true"/>
  ...
</entity>
 
<!-- Mapped Tenant column -->
 
<entity class="model.Player">
  <table name="PLAYER" />
  <tenant-column name="tenant.age" column-name="AGE"/>
  ...
  <attributes>
    <basic name="age" read-only="true">
      <column name="AGE"/>
    </basic>
    ...
  </attributes>
  ...
</entity>

Property configuration and caching scope

At runtime the properties can be specified via a persistence unit definition or passed to a create entity manager factory call.

The properties may be included within a peristence unit definition in the persistence.xml file.

The order of precendence for tenant id properties is as follows:

  • EntityManager
  • EntityManagerFactory
  • Application context (when in a Java EE container)
<persistence-unit name="multi-tenant">
  ...
  <properties>
    <property name="tenant.id" value="707"/>
    ...
  </properties>
</persistence-unit>

Or alternatively (and most likely preferred) in code as follows:

HashMap properties = new HashMap();
properties.put("tenant.id", "707");
...     
EntityManager em = Persistence.createEntityManagerFactory("multi-tenant", properties).createEntityManager();

Entity Manager Factory

At this level, users will be required to provide a unique session name through the "eclipselink.session-name" property to ensure a unique server session (and cache) is provided for each tenant. This allows for user defined properties (without any prefixing). In further iterations we will look to augment the session name automatically for the user based on their tenant property values (or something thereof).

HashMap properties = new HashMap();
properties.put("tenant.id", "707");
properties.put("eclipselink.session-name", "multi-tenant-707");
...     
EntityManager em = Persistence.createEntityManagerFactory("multi-tenant", properties).createEntityManager();
Shared Entity Manager Factory

When using a shared entity manager factory, no L2 cache 'striping' will be performed. All tenans will be contained in the cache (unless isolation is turned on).

Entity Manager

At this level, users will be required to specify the caching strategies as the same server session can be employed for each tenant. Users may decide to us an isolation level here etc to ensure no 'shared' tenant information exists in the L2 cache. These settings are set when creating the entity manager factory.

Swapping tenant id during a live EntityManager is not allowed (results

HashMap properties = new HashMap();
properties.put("tenant.id", "707");
properties.put("eclipselink.cache.shared.Employee", "false");
properties.put("eclipselink.cache.size.Address", "10");
properties.put("eclipselink.cache.type.Contract", "NONE");
...     
EntityManager em = Persistence.createEntityManagerFactory("multi-tenant", properties).createEntityManager();
...

Core

The tenant column(s) will be initialized during the pre-initialization of each descriptor of the persistence unit.

Those columns will then be applied in two places.

  1. We will leverage the current additional join expression from the DescriptorQueryManager to filter tenants. This is similar to the Additional Criteria feature. During postInitialization of the descriptor query manager after we have appended the additional criteria (if there is some), we will append the tenant column(s) and their value(s) to the additional join expression.
  2. For inserts, we will append the tenant column(s) and value(s) when building the row representation of an object. This is done in the following methods from ObjectBuilder (Note: this is similar to the handling of the discriminator column within an inheritance hierarchy)
    1. buildRow
    2. buildRowForShallowInsert
    3. buildRowForUpdate
    4. buildRowWithChangeSet
    5. buildTemplateInsertRow
    • NOTE: When the tenant column is mapped, it need not be added to the row. Only its value should be populated if it has not already been done.

The tenant column(s) are assumed to exist on the primary table. If using secondary tables the tenant column metadata must specify the table if it is not on the primary.

Tenant column(s) are not expected for the following tables (which refer back to their related entity through a primary key association):

  1. @CollectionTable
  2. @JoinTable
  3. JOINED Inheritance hierarchy tables
  4. SINGLE_TABLE Inheritance hierarchy

NOTE: This assumes id generation is shared across persistence units (see future section below). Otherwise, in a multi-tenant environment, the tenant id becomes part of the primary key and all tables must then have a tenant id (which becomes another join column on the relation tables).

Core/Runtime Exceptions

  • An exception will be thrown when a named tenant property can not be found.

Querying

The tenant column and value will be supported through the following entity manager operations:

  • persist
  • find
  • refresh

And the following queries:

  • named queries

NOTE: EclipseLink will not modify, therefore, support multi-tenancy through named native queries. When using these types of queries within a multi-tenant environment, the user will need to be aware and handle any multi-tenancy issues themselves directly in their native query. To all intent and purpose, named native queries should be avoided in a multi-tenant environment.

Support for update all and delete all queries should be included.

DDL generation

DDL generation will need to support the generation of tenant columns (for all necessary tables). The DDL generation of columns is based off the descriptor's columns. During pre-initialization we therefore need to ensure that our tenant columns are built and added to this list (if they are NOT mapped columns). This should be done after the descriptor table initialization (including inheritance hierarchies) has been preformed. Mapped tenant columns are added automatically and we should avoid adding them more than once.

if (hasTenantFields()) {
  for (String property : tenantFields.keySet()) {
    for (DatabaseField tenantField : tenantFields.get(property)) {
      getFields().add(buildField(tenantField));
    }
  }
}

Open/Future items

  1. How can an admin user access data from multiple tenants?
  2. Tenant column when part of the entity identifier
    1. Incorporate sequence generators
  3. Augment the session name (or something of the sort) for the user removing the dependency of providing a unique session name.

Back to the top