Multitenancy Guide

To persist the tenantId in database, we have to set the eclipselink.tenant-id property in persistence.xml file. To automatize the propagation of the tenantId to eclipselink we need to add this property automatically when the application is added. Then, we will use the method :

// This property will propagate the tenantId to eclipselink
// This value will be added to entities tables
String tenantIdProperty = "eclipselink.tenant-id";
String tenantIdValue = tenantId;
persistenceUnitManager.setProperty(tenantIdProperty, tenantIdValue);

Entities must be configured as multitenant to enable adding tenant-id in the database. For that, we have to add @Multitenant annotation in each class but we need to do that automatically (when multitenant service is activated). A solution is to use a Session Customizer (cf http://wiki.eclipse.org/Customizing_the_EclipseLink_Application_(ELUG)). It is a simple class with only one method (customize) and take one parameter (Session session). In this method, we will set all entity classes as multitenant as follows :

public void customize(Session session) throws Exception {
  Map<Class, ClassDescriptor> descs = session.getDescriptors();
  // For each entity class ...
  for(Map.Entry<Class, ClassDescriptor> desc : descs.entrySet()){
    // Create a multitenant policy (Single table)
    SingleTableMultitenantPolicy policy = new SingleTableMultitenantPolicy(desc.getValue());
    // Tell that column descriminator is TENANT_ID (it will be added in the database)
    policy.addTenantDiscriminatorField("eclipselink.tenant-id", new DatabaseField("TENANT_ID"));
    // Add this policy in class derscriptor
    desc.getValue().setMultitenantPolicy(policy);
  }
}

Then, during the deployment of the application, an eclipselink property is set to use this session customizer :

// This property will configure entities as multitenant
// It is the equivalent of @Multitenant
String sessionCustomizerProperty = "eclipselink.session.customizer";
String sessionCustomizerClass = "org.ow2.easybeans.persistence.eclipselink.MultitenantEntitiesSessionCustomizer";
persistenceUnitManager.setProperty(sessionCustomizerProperty, sessionCustomizerClass);

Because tenants share the same database and the same tables, it is important to ensure that a tenant does not drop an create tables. For that, verify if the drop-and-create-tables eclipselink property is not set. Otherwise, change this property to create-tables only :

// If eclipselink was enabled to drop and create tables
// change this property to only create tables
String createTablesProperty = "eclipselink.ddl-generation";
String dropAndCreateTablesValue = "drop-and-create-tables";
String createTablesValue = "create-tables";
Map<String, String> properties = persistenceUnitManager.getProperty(createTablesProperty);
for (Map.Entry<String, String> property : properties.entrySet()){
  if (property.getValue().equals(dropAndCreateTablesValue)) {
    logger.warn("This tenant was enabled to drop and create tables. Eclipselink property is changed to only create tables");
    persistenceUnitManager.setProperty(createTablesProperty, createTablesValue, property.getKey());
  }
}

During the deployment, a name is prefixed the syntax : T<id>/name when T<id> is the application's tenant-id. The naming strategy is set by:

newNamingStrategies.add(ejb3Service.getNamingStrategy(prefix, oldNamingStrategy));

Example: MyInitializerBean will be T1/MyInitializerBean. In addition, as for versioning service, a virtual JNDI binding is made. It will remove the prefix and rebind the old name to the same object. Then, we will have 2 names (MyInitializeBean and T1/MyInitializerBean) linked to the same object.

To customize JNDI names bound by the application by adding the tenant-id as prefix, an interceptor is set.

This interceptor (org.ow2.jonas.lib.tenant.interceptor.jndi.JNDITenantIdInterceptor) is an implementation of org.ow2.carol.jndi.intercept.ContextInterceptor and is registered in Carol Interceptor Manager when Multitenant service is activated. Then, all JNDI calls are intercepted.

// Add tenantId JNDI interceptor
jndiTenantIdInterceptor = new JNDITenantIdInterceptor(JNDI_SEPARATOR);
SingletonInterceptorManager.getInterceptorManager().registerContextInterceptor(jndiTenantIdInterceptor);

Two operations are made by this interceptor :

To customize MBeans, a JMX interceptor is set to add a tenant-id property to the MBean ObjectName.

This interceptor (org.ow2.jonas.lib.tenant.interceptor.jmx.JMXTenantIdInterceptor) implements org.ow2.jonas.jmx.Interceptor and is added to the InvocationHandler ( org.ow2.jonas.jmx.internal.interceptor.InvocationHandlerImpl) by multitenant service :

// Add tenantId JMX interceptor
jmxTenantIdInterceptor = new JMXTenantIdInterceptor(tenantIdAttributeName, allowToAccessPlatformMBeans);
jmxService.addInterceptor(jmxTenantIdInterceptor);

and will be called before querying the MBeanServer.

In order to create a "proxified" MBeanServer, a new class org.ow2.jonas.services.bootstrap.mbeanbuilder.JOnASMBeanServerBuilder which extends javax.management.MBeanServerBuilder is used and set as a system property :

// MBeanServerBuilder
System.setProperty("javax.management.builder.initial", "org.ow2.jonas.services.bootstrap.mbeanbuilder.JOnASMBeanServerBuilder");

Then, the first MBeanServer created in the platform is a proxy with a default interceptor. This default interceptor is always the last called and will call the MBeanServer method originally invoked (before interception).

// Create real MBeanServer with outerProxy
MBeanServer origin = super.newMBeanServer(defaultDomain, outerProxy, delegate);

// Create handler for MBeanServer proxy and add
// the default interceptor
InvocationHandlerImpl invocationHandler = new InvocationHandlerImpl();
invocationHandler.addInterceptor(new MBeanServerDelegateInterceptor(origin));

// Create the MBeanServer proxy
MBeanServer proxy = (MBeanServer) Proxy.newProxyInstance(origin.getClass().getClassLoader(),
                                                         new Class<?>[]{MBeanServer.class},
                                                         invocationHandler);

It is possible to add as many interceptors that it is desired and they will be called one by one.

Using a customized MBeanServerBuilder can be problematic. In fact, as described in JONAS-867, if the system property com.sun.management.jmxremote is set before JOnAS startup, this has the effect of creating some MBeans and then initialize the MBeanServer. However, the system property javax.management.builder.initial which is set when JOnAS starts and define the class which is used to build the platform MBeanServer, this one is present in org.ow2.jonas.services.bootstrap.mbeanbuilder.JOnASMBeanServerBuilder and is not known by the classloader at this step. If the system property com.sun.management.jmxremote is not set, this error should not appear.

This profile is define by the super-admin role :

<role name="super-admin" description="Role allowing access to all tenants" />

and will be assigned to a unique user in the platform :

<user name="superAdmin" password="admin" roles="superAdmin"/>

This user will have a full access to all MBeans when connecting on a administration tool such as JConsole.

For each tenant, a specific role is defined according to the pattern TenantId[T<id>] :

<role name="TenantId[T1]" description="Role allowing access to tenant T1 information" />

and will be assigned to a unique user in the group of user belonging to the tenant.

<user name="admin@client" password="admin" roles="TenantId[T1]"/>

This user will have access to MBeans which contain the property tenant-id=T1.