View source for EclipseLink/DesignDocs/Multi-Tenancy/TablePerTenant

<div style="float:right;width:300px">
__TOC__
</div>

This feature will be a continuation of the multitenant feature that currently offers a SINGLE_TABLE or VPD type, see [http://wiki.eclipse.org/EclipseLink/Development/Indigo/Multi-Tenancy Multitenant]

Bug: [https://bugs.eclipse.org/bugs/show_bug.cgi?id=376603 376603]

== Table per tenant ==

The goal of this feature is to allow multiple tenants of an application to isolate their data within individual table(s). These tables can be stored within the same schema using a prefix or suffix naming pattern or can be stored in separate schemas. Table per tenant entities can be mixed with other multitenant type entities within the same persistence unit.

=== JPA Tenant Scope ===

This feature is intended to address the situation where a single application instance with a shared EntityManagerFactory for a persistence unit is responsible for handling requests from multiple tenants. In the case where separate EntityManagerFactory instances are used for each tenant (required when using extensions per tenant) then the developer can alternatively choose to specify tenant specific schema and table names within an eclipselink-orm.xml configuration file which is used based on the MetadataSource feature.

=== Requirements ===

# Support configuration of table per tenant entity types using EclipseLink specific annotations and/or eclipselink-orm.xml with the XML overriding the annotation.
# Ensure all READ, INSERT, UPDATE, DELETE operations populate and limit their effect to the defined table per tenant table(s)
# Tenants by default will share the same server session (tenant identifier must be updated/set per entity manager)
## Id generation is assumed to be unique across all table per tenants. @See Future Section.
# Tenant tables can be isolated by schema or a uniqe name (with a prefix or suffix on the table names).

Not supported:
# Schema generation will not be supported since it requires knowledge of all the tenants (schema's) and further to that, access provision must be set once the tables are created if using schema level table per tenant.

== Metadata ==

This document will focus only on the TABLE_PER_TENANT multi-tenant type. The type will enable individual tenant table(s) usage at the entity level using a tenant context property that must be provided by the user on each entity manager after a transaction has started.

* The TABLE_PER_TENANT states that the table(s) (Table and SecondaryTable) for the given entity are individual tenant tables based on the tenant context.
** Relationships within that entity that use a join or collection table are also assumed to exist within the table per tenant context.
* A TABLE_PER_TENANT type is used in conjunction with:
** A tenant table discriminator that specifies the type of discriminator (schema or name with prefix or suffix)
** A tenant id to identify the user (configured by the user per EM or at the EMF if isolating table per tenant per persistence unit) 
* Multi-tenant metadata can only be applied at the root level of the inheritance hierarchy when using a SINGLE_TABLE or JOINED inheritance strategy. A log warning will be issued otherwise. 
** It is possible to specify multi-tenant metadata within a TABLE_PER_CLASS inheritance hierarchy.

==== Short example ====

<source lang="java">
@Entity
@Table(name=“EMP”)
@Multitenant(TABLE_PER_TENANT)
@TenantTableDiscriminator(type=SCHEMA, contextProperty="eclipselink.tenant-id")
public class Employee {
    ...
}

<entity class="Employee">
  <multitenant type="TABLE_PER_TENANT">
    <tenant-table-discriminator type="SCHEMA" context-property="eclipselink.tenant-id"/>
  </multitenant>
  <table name="EMP">
  ...
</entity>

</source>

tenant1.EMP

{|{{BMTableStyle}} 
|-{{BMTHStyle}} 
! EMP_ID
! VERSION
! F_NAME
! L_NAME
! GENDER
|- 
| 1 
| 1
| John
| Doe
| M
|}

tenant2.EMP

{|{{BMTableStyle}} 
|-{{BMTHStyle}} 
! EMP_ID
! VERSION
! F_NAME
! L_NAME
! GENDER
|- 
| 2 
| 3
| Jane
| Doe
| F
|}

=== Annotations ===

The following new EclipseLink metadata will be added.

The new type will be added to the possible value list for the existing @Multitenant annotation. See [http://wiki.eclipse.org/EclipseLink/Development/Indigo/Multi-Tenancy Multinancy] for more configuration documentations of this annotation. 

This means we will extend the MultitenantType enum to include TABLE_PER_TENANT and add a new TenantTableDiscriminator annotation and TenantTableDiscriminatorType enum.

<source lang="java">
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 the DB will handle the tenant filtering on all SELECT,
     * UPDATE and DELETE queries. Using this type assumes that the platform
     * used with your persistence unit does indeed support VPD.
     * 
     * @since 2.3.1
     */
    VPD

    /** 
     * Specifies that different tables are used for each tenant and used in 
     * conjunction with the tenant table discriminator which describes how the 
     * tables are uniquely identified, that is, using a suffix/prefix or a 
     * separate schema.
     * 
     * @since 2.4
     */
    TABLE_PER_TENANT
}

@Target({TYPE}) 
@Retention(RUNTIME)
public @interface TenantTableDiscriminator {
    /**
     * (Optional) The name of the context property to apply to as 
     * tenant table discriminator. Default is "eclipselink.tenant-id"
     */
    String contextProperty() default PersistenceUnitProperties.MULTITENANT_PROPERTY_DEFAULT;
    
    /**
     * (Optional) The type of tenant table discriminator to use with the tables
     * of the persistence unit.
     * Defaults to {@link TenantTableDiscriminatorType#SUFFIX TenantTableDiscriminatorType.SUFFIX}.
     */
    TenantTableDiscriminatorType type() default TenantTableDiscriminatorType.SUFFIX;
}

public enum TenantTableDiscriminatorType {
    /**
     * Apply the tenant table discriminator as a schema to all multitenant tables.
     * NOTE: this strategy requires appropriate database provisioning.
     */
    SCHEMA, 
    
    /**
     * Apply the tenant table discriminator as a suffix to all multitenant tables. This
     * is the default strategy.
     */
    SUFFIX, 
    
    /**
     * Apply the tenant table discriminator as a prefix to all multitenant tables.
     */
    PREFIX
}
</source>

=== XML ===

The multitenant-type XML element will be expanded to include the new type and a new tenant table discriminator complex type (with associated simple type enum equivalent) will be added. The new table tenant discriminator will be available from the existing multitenant complex type, within a choice with the existing tenant discriminator column element.

<source lang="XML">
<xsd:simpleType name="multitenant-type">
  <xsd:restriction base="xsd:token">
    <xsd:enumeration value="SINGLE_TABLE"/>
    <xsd:enumeration value="VPD"/>
    <xsd:enumeration value="TABLE_PER_TENANT"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:complexType name="tenant-table-discriminator">
  <xsd:attribute name="type" type="orm:tenant-table-discriminator-type"/>
</xsd:complexType>

<xsd:simpleType name="tenant-table-discriminator-type">
  <xsd:restriction base="xsd:token">
    <xsd:enumeration value="SCHEMA"/>
    <xsd:enumeration value="SUFFIX"/>
    <xsd:enumeration value="PREFIX"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:complexType name="multitenant">
  <xsd:sequence>
    <xsd:choice>
      <xsd:element name="tenant-discriminator-column" type="orm:tenant-discriminator-column" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="tenant-table-discriminator" type="orm:tenant-table-discriminator" minOccurs="0"/>
    </xsd:choice>
  </xsd:sequence>
  <xsd:attribute name="type" type="orm:multitenant-type"/>
  <xsd:attribute name="include-criteria" type="xsd:boolean"/>
</xsd:complexType>

</source>

=== Processing ===
The new annotations and xml will plug into the existing metadata processing architecture.

* eclipselink_orm_2_4.xsd
** schema updated with new xml elements
*org.eclipse.persistence.internal.jpa.metadata.multitenant.TenantTableDiscriminatorMetadata
** Handle the new TenantTableDiscriminator annotation and xml elements
* org.eclipse.persistence.internal.jpa.metadata.xml.XMLEntityMappingsMappingProject
** The MOXy mapping file modified to map the XML to the TenantTableDiscriminatorMetadata class.
* org.eclipse.persistence.internal.jpa.metadata.multitenant.MultitenantMetadata
** Modified to process the new TENANT_PER_TABLE multitenant type and tenant table discriminator metadata.
* org.eclipse.persistence.internal.jpa.metadata.MetadataLogger
** Expanded for any warning or defaulting log messaages.

=== Warnings and Exceptions ===

Relationships from a non table per tenant entity to a table per tenant entity will not be allowed. Relationships can only emanate from the table per tenant entity.

NOTE: See future section. We could likely support this using the same cloning strategy we are using with table per tenant descriptors. See the core section below where we discuss the cloning of descriptors. Those entities that refer to table per tenant entities could essentially have their descriptors (and mappings) cloned and modified to refer to the table per tenant descriptor clones.

== Properties ==

The table per tenant context property is specified by the user and we will re-use default MULTITENANT_PROPERTY_DEFAULT = "eclipselink.tenant-id".

=== Configuration and caching ===

The caching strategy remains the same as currently implemented for the other multitenant types. By default, tenants will share the entity manager factory. 

If this is not the desired behavior, the following existing properties can set in the persistence unit definition:
* PersistenceUnitProperties.MULTITENANT_SHARED_EMF = "eclipselink.multitenant.tenants-share-emf"
* PersistenceUnitProperties.SESSION_NAME = "eclipselink.session-name"

Note: when not sharing the EMF, a unique session name must be provided and that persistence unit will be isolated to that tenant with full caching capabilities. There is currently no automatic augmentation of the session name since there is no way to be able to determine the tenant id property since the name of the property can be configured by the user (and there can be multiples etc.). A deploy time there is no way to know before processing the metadata which of course is done after the session have been created.

In a shared entity manager factory approach, a tenant id must be provided on each entity manager after a transaction has begun. Setting the tenant id must be the first operation on the entity manager and the tenant id must not be changed during the lifespan of that entity manager.

By default, tenants will not share the cache, meaning table per tenant entities will have an ISOLATED setting. To allow these entities to share the cache, the following property can be set to true: 

* PersistenceUnitProperties.MULTITENANT_SHARED_CACHE = "eclipselink.multitenant.tenants-share-cache"

When the cache is shared, table per tenant entities will have a PROTECTED setting.

=== Examples ===

<source lang="java">
// Shared EMF
EntityManager em = createEntityManager(MULTI_TENANT_PU);
em.getTransaction().begin();
em.setProperty(EntityManagerProperties.MULTITENANT_PROPERTY_DEFAULT, "gpelleti");

// Non shared EMF
HashMap properties = new HashMap();
properties.put(PersistenceUnitProperties.MULTITENANT_SHARED_EMF, "false");
properties.put(PersistenceUnitProperties.SESSION_NAME, "non-shared-emf-for-gpelleti");
properties.put(PersistenceUnitProperties.MULTITENANT_PROPERTY_DEFAULT, "gpelleti");
...     
EntityManager em = Persistence.createEntityManagerFactory("multi-tenant-pu", properties).createEntityManager();
</source>

In the persistence unit definition (non shared-emf)

<source lang="xml">
<persistence-unit name="multi-tenant-pu">
  ...
  <properties>
    <property name="eclipselink.multitenant.tenants-share-emf" value="false"/>
    <property name="eclipselink.session-name" value="non-shared-emf-for-gpelleti"/>
    <property name="eclipselink.tenant-id" value="gpelleti"/>
    ...
  </properties>
</persistence-unit>
</source>

== Core ==

=== Implementation ===

A table per tenant policy will be created which will implement the existing MultitenantPolicy. This policy will be responsible for the initialization of table per tenant descriptors and the table name translations.
* org.eclipse.persistence.descriptors.TablePerMultitenantPolicy

The meat of a schema table per tenant strategy will be achieved through database level settings and access provisions. The table per tenant property will correlate directly with EclipseLink's descriptor table qualifier (which is added to all tables relating to that descriptor, table and secondary table). 

The policy will also be responsible for applying this table qualifier setting to all mappings of the descriptor that use a relation table (Many to many, one to one etc.). When those mappings are created, there is no notion of a table qualifier/schema at that point. Since the table per tenant entity is the owner of the relationship it is only fair to assume that its relation table must also have the same qualifier. It is entirely possible though (with unique id's across all tenants for table per tenant entities) to not have this restriction/assumption in place however. See future section. 

Under the same assumption, element collection tables should also have the table per tenant identifier as well, but again not necessary when unique id's are employed across all tenants.

In the case of a prefix or suffix solution, instead of setting a table qualifier as described above, all table names from the cloned descriptor and its mappings will need to be updated to the new table name employing the table per tenant property. This name translation will be done by the policy.

ClassDescriptor:
* Will need its clone method expanded to include any missing parts not already included in that method.

Project:
* When using a table per tenant entities within a shared EMF, the project will be cloned per client session. This allows us to clone the jpql parse cache and allow its usage for that session. Otherwise, we would need to disable it. The cloned jpql cache will be created with the same max size as the parents.

ServerSession:
* Will contain the metadata processor produced class descriptor.
* These descriptors are available from the existing descriptor maps and list and will also be paired out to their own list (for ease of manipulation)
* Unless the table per tenant property is set at the EMF level, table per tenant descriptors will never be initialized. Instead the table per tenant descriptors will cloned for each client session, updated with the table per tenant context property and those cloned descriptor are then initialized and used for the lifespan of that client session.
* When the table per tenant is provided at the EMF level, the server session descriptors are fully initialized and never cloned per client session. Normal initializing operations will occur in this case. Setting a table per tenant at the EM level here is not allowed and an exception will be thrown.

=== Exceptions ===

An exception will be raised, 
* when a table per tenant is not set (database exception in tis case, i.e. invalid table name etc.)

== Querying ==

Full querying should be available to the user through the following entity manager operations:

* persist
* find
* refresh

And the following queries:
* named queries
* update all
* delete all

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 (schemas and table names) themselves directly in their native query. For all intents and purposes, named native queries should be avoided in a multi-tenant environment.

== DDL generation ==

DDL generation will not be supported. Since we a table for all tenants plus the access provisions, there is no way for use to know this information before hand.

== Open/Future items ==

* A flag or setting to indicate per mapping if its associated table is isolated per tenant or not. This opens up caching issues though, in that, we could never use the level 2 cache and would always have to force the table per tenant entities to an isolated session if the ids are not unique across tenants?? Some unknowns here.
* Allow for relationships from non table per tenant entities to table per tenant entities. Would need to do more descriptor cloning per entity manager (client session) but this is possible.
* Add tenant table discriminator to entity mappings and persistence unit defaults of eclipselink_orm_2_4.xsd
* Specifying a catalog of schema in the table discriminator