23 Multitenant

Multitenancy allows multiple tenants to have physically or logically separated data in a system.

Separated Data Sources
Shared Table
Primary Key and Caching
Achieve JPA-Managed over Application-Managed Multitenancy

Separated Data Sources

Each tenant has its own persistence unit mapped to a separated data source. For example,

Tenant_1                       Tenant_2
-----------------------------------------------------
PU1: Database Schema_1         PU2: Database Schema_2

META-INF/Persistence.xml:

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
		version="2.2">

	<persistence-unit name="tenant_1" transaction-type="RESOURCE_LOCAL">
		<non-jta-datasource>jndiDataSourceName_schema_1</non-jta-datasource>
	</persistence-unit>

	<persistence-unit name="tenant_2" transaction-type="RESOURCE_LOCAL">
		<non-jta-datasource>jndiDataSourceName_schema_2</non-jta-datasource>
	</persistence-unit>
</persistence>

Create EntityManagerFactory and EntityManager for a tenant:

	// tenant_1
	EntityManagerFactory emf = Persistence.createEntityManagerFactory("tenant_1");
	EntityManager em = emf.createEntityManager();
	
	// tenant_2
	EntityManagerFactory emf2 = Persistence.createEntityManagerFactory("tenant_2");
	EntityManager em2 = emf2.createEntityManager();

Adding a new tenant requires adding a persistence unit in META-INF/persistence.xml.

Shared Table

All tenants share tables using discriminator columns. Tenant discriminator columns are not necessarily mapped to entity attributes, but they will be automatically added in SQL DDL and DML statements if needed.

If a mapped superclass or entity class is configured as multitenant-enabled in an XML mapping file, its subclass entities will inherit the configuration as multitenant-enabled entities unless they are overridden.

For example, class hierarchy:

               AbstractEntityBase
          ------------------------------------------
           |          |          |                 |
         User        Role      Permission       Employee
                                                /      \
                                    FullTimeEmployee  PartTimeEmployee

orm.xml

<mapped-superclass class="com.cmobilecom.jpa.example.managed_classes.AbstractEntityBase">
	<multitenant>
		<discriminator-column name="tenant_id" type="java.lang.Long" 
			value-mapping-property="tenant.id"
			tenant-entity="com.cmobilecom.jpa.example.managed_classes.TenantImpl"
			attribute="tenant"/>
	</multitenant>
</mapped-superclass>

<entity class="com.cmobilecom.jpa.example.managed_classes.User">
	<multitenant enabled="false"/>
</entity>
	
<entity class="com.cmobilecom.jpa.example.managed_classes.Role">
	<multitenant>
		
		<discriminator-column nullable="true"/>
	</multitenant>
</entity>	
	
<entity class="com.cmobilecom.jpa.example.managed_classes.Permission">
	<multitenant enabled="false"/>
</entity>

The class hierarchy is configured as multitenant-enabled except the User and Permission entities.

The <multitenant> element defines multitenant configuration of a managed type hierarchy:

name: database column name.
type (optional): database column java type (fully qualified class name). Optional if attribute is specified.
length (optional): length for string type. Optional if attribute is specified that references tenant entity.
nullable: true or false(default). A null value means that the corresponding entity does not belong to any tenant.
value-mapping-property: the property name of the EntityManager, EntityManagerFactory or META-INF/persistence.xml whose value is mapped to the discriminator column value.
tenant-entity (optional): tenant entity class (fully qualified class name) that has a simple identifier type such as java.lang.Long, java.lang.String, etc.
attribute (optional): the name of the attribute that returns tenant-related information.
- If tenant-entity is specified and the attribute returns a type that is assignable from tenant entity type, the attribute will be mapped to a Foreign Key (ManyToOne) and the discriminator column is the foreign key column.
- Otherwise, the attribute will be a basic attribute and mapped to the discriminator column. In this case, the attribute type must be the same as the java type of the discriminator column.
- If the attribute is transient, it will be mapped as Basic or ManyToOne according to its return type. Its access type (PROPERTY or FIELD) is the same as the access type of its declaring MappedSuperclass or Entity class.
- If the attribute is not specified, tenant information will not be fetched. e.g., search scope is within one tenant data.
- Required for application-managed multitenancy.

Refer to Cmobilecom-JPA ORM Extension Schema for detail.

Separated Persistence Units

Define a persistence-unit for each tenant in META-INF/persistence.xml and specifies the tenant discriminator column values. For example,

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
		version="2.2">

	<persistence-unit name="tenant_1" transaction-type="RESOURCE_LOCAL">
		<non-jta-datasource>jndiDataSourceName</non-jta-datasource>
	
		<properties>
			<property name="tenant.id" value="100"/>
		</properties>		
	</persistence-unit>

	<persistence-unit name="tenant_2" transaction-type="RESOURCE_LOCAL">
		<non-jta-datasource>jndiDataSourceName</non-jta-datasource>
	
		<properties>
			<property name="tenant.id" value="101"/>
		</properties>		
	</persistence-unit>
</persistence>

Create EntityManagerFactory and EntityManager for a tenant:

	// tenant_1
	EntityManagerFactory emf = Persistence.createEntityManagerFactory("tenant_1");
	EntityManager em = emf.createEntityManager();
	
	// tenant_2
	EntityManagerFactory emf2 = Persistence.createEntityManagerFactory("tenant_2");
	EntityManager em2 = emf2.createEntityManager();

Separated EntityManagerFactory(s)

All tenants share the same persistence-unit in META-INF/persistence.xml, but a separated EntityManagerFactory is created for each tenant. Tenant discriminator column values must be passed in a property map when creating a EntityManagerFactory for a tenant. For example,

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
		version="2.2">

	<persistence-unit name="all_tenants" transaction-type="RESOURCE_LOCAL">
		<non-jta-datasource>jndiDataSourceName</non-jta-datasource>
	</persistence-unit>
	
</persistence>

Create EntityManagerFactory and EntityManager for a tenant:

	// tenant_1
	Map<String, Object> tenant1_properties = new HashMap<>();
	tenant1_properties.put("tenant.id", 100);
	EntityManagerFactory emf = Persistence.createEntityManagerFactory("all_tenants", tenant1_properties);
	EntityManager em = emf.createEntityManager();
	
	// tenant_2
	Map<String, Object> tenant2_properties = new HashMap<>();
	tenant2_properties.put("tenant.id", 101);
	EntityManagerFactory emf2 = Persistence.createEntityManagerFactory("all_tenants", tenant2_properties);
	EntityManager em2 = emf2.createEntityManager();

Tenant discriminator column values set in an EntityManagerFactory must not be changed.

Separated EntityManager(s)

All tenants share the same persistence-unit in META-INF/persistence.xml and the same EntityManagerFactory, but a separated EntityManager is created for each tenant. Tenant discriminator column values must be passed when creating a EntityManager for a tenant. For example,

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
		version="2.2">

	<persistence-unit name="all_tenants" transaction-type="RESOURCE_LOCAL">
		<non-jta-datasource>jndiDataSourceName</non-jta-datasource>
	</persistence-unit>
	
</persistence>

Create one EntityManagerFactory shared by all tenants, and create one EntityManager for each tenant:

	EntityManagerFactory emf = Persistence.createEntityManagerFactory("all_tenants");
	
	// tenant_1
	Map<String, Object> tenant1_properties = new HashMap<>();
	tenant1_properties.put("tenant.id", 100);
	EntityManager em = emf.createEntityManager(tenant1_properties);
	
	// tenant_2
	Map<String, Object> tenant2_properties = new HashMap<>();
	tenant2_properties.put("tenant.id", 101);
	EntityManager em = emf.createEntityManager(tenant2_properties);

Tenant discriminator column values set in an EntityManager must not be changed. An EntityManager for one tenant must not be reused for a different tenant because

Two entities with a same identifier but from different tenants can not coexist in one persistence context.
Lazy initialization relies on the EntityManager for the same tenant.

Application Managed Multitenancy

When an EntityManager is to manage data of all tenants in shared-table multitenant strategy, one option is to define a new persistence unit with the same metamodel except that:

Add multitenant (discriminator) attribute as a regular attribute(ManyToOne or basic).
Remove multitenant configuration: none of entities are multitenant enabled.
If an independent entity type does not have id generator or derived id, add multitenant attribute as an id attribute. Define IdClass or EmbeddedId classes for composite primary key.

The advantage of this approach is that all entities from different tenants have unique identifiers. The disadvantage is that another persistence unit with minor difference has to be created, and its metamodel has to be built at runtime which will incurs CPU and memory overhead.

The other option is application-managed multitenancy. When all multitenant-enabled entity types(except dependent entities) have id generators to ensure that no two entities from different tenants have the same identifier in a persistence context, this option will be better since it uses the same persistence unit and will not build a new metamodel.

Define multitenant attribute in multitenant configuration and set the property Constants.MULTITENANT_APP_MANAGED to true in EntityManager to enable application-managed multitenancy. The property can also be set in EntityManagerFactory or persistence.xml if appropriate, and shared by all EntityManagers. The property must not be changed once set.

When the attribute of multitenant configuration is specified, the attribute will be managed as a regular entity attribute by Cmobilecom-JPA and be a part of metamodel.

Application-managed multitenancy(the property value is set to true): the managed data scope is data of all tenants. All multitenant-enabled entity types must have multitenant attribute defined. The multitenant attribute can be used in query restriction, and its value must be set for entity insertion if not nullable. However, its value must not be changed after entity is persisted since entities can not be transferred from one tenant to another. The multitenant attribute will always be fetched regardless of query EntityGraph hint. The multitenant.valueMappingProperty will not be used to get discriminator column value, and discriminator column will not be added to insertion or query restriction automatically.
For application-managed multitenancy, PersistenceException will be thrown if a multitenant-enabled entity type does not have unique entity identifiers among all tenants, or if its multitenant attribute is not defined. To enforce this when building metamodel, set property "com.cmobilecom.jpa.multitenant.appManaged.supported" to true in persistence.xml or when creating EntityManagerFactory. The property name is defined as Constants.MULTITENANT_APP_MANAGED_SUPPORTED.
JPA-managed multitenancy(the property value is not specified or false): the managed data scope is data of one tenant (tenant can be null if nullable). The multitenant.valueMappingProperty will be used to get discriminator column value, and discriminator column will be added to insertion and query restriction automatically. Unless the query hint Constants.MULTITENANT_FETCH_TENANT_ATTR is set to be true, the multitenant attribute will not be fetched in query even if it is defined.

For example,

<entity-mappings
		xmlns="http://xmlns.jcp.org/xml/ns/persistence/orm"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence/orm cmobilecom-jpa-orm_1_0.xsd"
		version="2.2">
	
	<mapped-superclass class="com.cmobilecom.jpa.example.managed_classes.AbstractEntityBase" >
		<multitenant>
			<discriminator-column name="tenant_id" type="java.lang.Long"
					value-mapping-property="tenant.id"
					tenant-entity="com.cmobilecom.jpa.example.managed_classes.TenantImpl"
					attribute="tenant"/>
		</multitenant>
	</mapped-superclass>
	
</entity-mappings>

Managed classes:

@MappedSuperclass
abstract public class AbstractEntityBase {
	@Transient
	private Tenant tenant;
	
	public Tenant getTenant() {
		return this.tenant;
	}
	
	public void setTenant(Tenant tenant) {
		this.tenant = tenant;
	}
	
	...
}

public interface Tenant {
	public Long getId();
	
	public String getName();
}

@Entity
public class Employee extends AbstractEntityBase {
	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	private String id;
	
	@Column(nullable=false, length=20)
	private String name;
}

@Entity
public class TenantImpl implements Tenant {
	@Id
	private Long id;
	
	@Column(nullable=false, length=30)
	private String name;

	// getters and setters
}

The classes above may be separated in different modules. The attribute "tenant" is defined as transient, but it will be managed as a regular attribute.

Example code for application-managed multitenancy:

	EntityManager em = emf.createEntityManager();
	em.setProperty(Constants.MULTITENANT_APP_MANAGED, true);
	
	// persist an entity of Tenant 1
	Employee employeeA = new Employee();
	employeeA.setName("John A");
	employeeA.setTenant(em.getReference(TenantImpl.class, 1L));
	em.persist(employeeA);
	
	// persist an entity of Tenant 2
	Employee employeeB = new Employee();
	employeeB.setName("John B");
	employeeB.setTenant(em.getReference(TenantImpl.class, 2L));
	em.persist(employeeB);
	
	// query entities from all tenants
	TypedQuery<Employee> query = em.createQuery(
		"select e from Employee e where e.name like 'John%'", Employee.class);
	List<Employee> employees = query.getResultList();
	
	// query entities from one tenant
	TypedQuery<Employee> query = em.createQuery(
		"select e from Employee e where e.tenant.id=1 and e.name like 'John%'", Employee.class);
	List<Employee> employees = query.getResultList();

Retrieved employees will have tenant attribute values fetched. e.g.,

	id      name        tenant
	------------------------------
	1       John A      Tenant 1
	2       John B      Tenant 2

Unique Entity Identifier

If entity shared-table multitenancy is managed by application, entities of different tenants are allowed to be added into persistent context of an EntityManager. To tell Cmobilecom-JPA about entity identifier uniqueness among all tenants, configure one of the followings:

Define entity id generator.
Define tenant attribute that is a member of entity identifier(IdClass or EmbeddedId).
Set "entityIdUnique" attribute(to be true) of multitenant element in orm.xml

Primary Key and Caching

If an entity type is multitenant enabled, but it does not have unique entity identifiers among all tenants, its tenant discriminator column must be a primary key column. Tenant discriminator column must be in all unique keys of primary and secondary tables. Schema generation will generate primary and unique keys, adding tenant discriminator column in the keys if necessary.

For separated-dataSource multitenancy or shared-table multitenancy with tenant discriminator column values specified in META-INF/persistence.xml or EntityManagerFactory, entities will be normally cached in 2nd-level cache according to caching configuration and hints since each tenant has its own cache.

For shared-table multitenancy with a shared EntityManagerFactory, the 2nd-level cache is shared among all tenants. If an entity type is multitenant enabled, but it does not have unique entity identifiers among all tenants, entities of the entity type will not be cached.

Achieve JPA-Managed over Application-Managed Multitenancy

JPA-managed multitenancy provides tenant-related transparency over entity persistence, update and query. If an EntityManager is application managed and used for managing entities of all tenants, properties/hints can be used to achieve JPA-managed multitenancy. For example,

	EntityManager em = emf.createEntityManager();
	em.setProperty(Constants.MULTITENANT_APP_MANAGED, true);

	// tenant 1
	Map<String, Object> tenant1Hints = new HashMap<>();
	// hints: multitenant JPA managed
	tenant1Hints.put("tenant.id", 1L);
	tenant1Hints.put(Constants.MULTITENANT_APP_MANAGED, false);
	tenant1Hints.put(Constants.MULTITENANT_FETCH_TENANT_ATTR, true);
	// hints for persist/merge
	Tenant tenant1 = em.getReference(TenantImpl.class, 1L)
	tenant1Hints.put(Constants.MULTITENANT_TENANT, tenant1);
	tenant1Hints.put(Constants.MULTITENANT_TENANT_SKIP_MANAGED, true);

	// persist an entity of Tenant 1
	Employee employeeA = new Employee();
	employeeA.setName("John A");

	ExtendedEntityManager extendedEntityManager = em.unwrap(ExtendedEntityManager.class);
	extendedEntityManager.persist(employeeA, tenant1Hints);

	...

	// persist an entity of Tenant 1
	employeeA.setName("John A Jr.");
	extendedEntityManager.merge(employeeA, tenant1Hints);

	// query entities of Tenant 1
	TypedQuery<Employee> query = em.createQuery("select e from Employee e", Employee.class);
	for (String hint : tenant1Hints.keySet())
		query.setHint(hint, tenant1Hints.get(hint));

	List<Employee> resultList = query.getResultList();

The same EntityManager can manage entities of different tenants using different tenant hints, and entities of different tenants can be persisted or updated in one same transaction. Make sure that entities have unique identifiers among all tenants.

← Validation→ License InstallationFrames / No Frames