Slice Documentation

The existing application or the persistent domain model requires no change to upgrade from a single database to a distributed database environment.

User application decides how the newly persistent instances be distributed across multiple database slices. The data distribution policy across the slices may be based on the attribute of the data itself. For example, all Customer whose first name begins with character 'A' to 'M' will be stored in one database while names beginning with 'N' to 'Z' will be stored in another slice. It is also common to find data distribution policies based on temporal attributes.

Slice tracks the original database for existing instances. When an application issues a query, the instances may be loaded from from different database slices. This tracking is important as update to any instance gets committed to the appropriate database.

Each slice can be configured independently with its own JDBC driver. Hence data can be distributed across heterogeneous databases.

All database operations such as query, commit or flush operates in parallel across the database slices.

The database slices participate in a global transaction provided each slice is configured with a XA-complaint JDBC driver, even when the persistence unit is configured for RESOURCE_LOCAL transaction.

No relationship can exist across database slices. In O-R mapping paradigm, this translates to the limitation that the closure of an object graph must be collocated in the same database. For example, consider a domain model where Person relates to Adress. Person X refers to Address A while Person Y refers to Address B. Collocation Constraint means that both X and A must be stored in the same database slice. Similarly Y and B must be stored in a single slice.

Slice, however, helps to maintain collocation constraint automatically. The instances in the closure set of any newly persistent instance reachable via cascaded relationship is stored in the same slice. The user-defined distribution policy requires to supply the slice for the root instance only.

If a query specified ORDER BY clause, then the results from individual database slices are sorted but the result is not sorted across multiple slices.

The basic configuration property is

 
         <property name="openjpa.BrokerFactory" value="slice"/>
       

This configuration activates a specialized factory class aliased as slice to create object management kernel that can work against multiple databases.

The next task is to configuration each database slice. Each slice is assigned a logical name. For example, the following configuration will register two slices with logical name One and Two.

 
        <property name="slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/>
        <property name="slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/>
       

Any OpenJPA specific property can be configured per slice basis. For example, the following configuration will use two different JDBC drivers for slice One and Two.

 
        <property name="slice.One.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
        <property name="slice.Two.ConnectionDriverName" value="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"/>
       

Any property if unspecified for a particular slice will be defaulted by corresponding OpenJPA property. For example, consider following three slices

 
         <property name="slice.One.ConnectionURL"          value="jdbc:mysql:localhost//slice1"/>
         <property name="slice.Two.ConnectionURL"          value="jdbc:mysql:localhost//slice2"/>
         <property name="slice.Three.ConnectionURL"        value="jdbc:oracle:localhost//slice3"/>

         <property name="openjpa.ConnectionDriverName"     value="com.mysql.jdbc.Driver"/>
         <property name="slice.Three.ConnectionDriverName" value="oracle.jdbc.Driver"/>
        

In this example, Three will use slice-specific oracle.jdbc.Driver driver while slice One and Two will use the driver com.mysql.jdbc.Driver as specified by openjpa.ConnectionDriverName property value.

Slice needs to determine which slice will persist a new instance. The application can only decide this policy (for example, all PurchaseOrders before April 30 goes to slice One, all the rest goes to slice Two). This is why the application has to implement org.apache.openjpa.slice.DistributionPolicy and specify the implementation class in configuration

 
          <property name="slice.DistributionPolicy" value="com.acme.foo.MyOptimialDistributionPolicy"/>
        

The interface org.apache.openjpa.slice.DistributionPolicy is simple with a single method. The complete listing of the documented interface follows:

 
        
public interface DistributionPolicy {
    /**
     * Gets the name of the slice where a given instance will be stored.
     *  
     * @param pc The newly persistent or to-be-merged object. 
     * @param slices name of the configured slices.
     * @param context opaque context for future use.
     * 
     * @return identifier of the slice. This name must match one of the
     * configured slice names. 
     * @see DistributedConfiguration#getSliceNames()
     */
    String distribute(Object pc, Set<String> slices, Object context);
}

       

While implementing a distribution policy the most important thing to remember is collocation constraint. Because Slice can not establish or query any cross-database relationship, all the related instances must be stored in the same database slice. Slice can determine the closure of a root object by traversal of cascaded relationships. Hence user-defined policy has to only decide the database for the root instance that is the explicit argument to EntityManager.persist() call. Slice will ensure that all other related instances that gets persisted by cascade is assigned to the same database slice as that of the root instance. However, the user-defined distribution policy must return the same slice identifier for the instances that are logically related but not cascaded for persist.