------------------
                            User Documentation
                            ------------------
                            ------------------
                            ------------------

Table of Contents

 * {{{manual.html#Preface}Preface}} 

   ** {{{manual.html#What}What is Slice?}}
  
   ** {{{manual.html#Why}Why Slice?}}

   ** {{{manual.html#Distribution}Distribution Policy}} 
   
   ** {{{manual.html#Collocation}Collocation Constraint}}
   
  []
      
  * {{{manual.html#Getting}Getting Started with Slice}}
  
    ** {{{manual.html#Download}Download Slice}}
    
    ** {{{manual.html#Configure}Configure Persistence Unit}}
    
    ** {{{manual.html#Implement}Implement Distribution Policy}}
    
  []
  
  
{Preface}

* {What} is Slice?

 Slice is an extension of OpenJPA to work with 
 {{{http://en.wikipedia.org/wiki/Partition_(database)}horizontally-partitioned}}, 
 distributed databases.
 
 JPA has been established as a industry-standard specification for persistence of Java 
 objects to relational database. OpenJPA is a mature, production-ready 
 implementation of Java Persistence API (JPA) available as top level Apache 
 Open Source Project.
 OpenJPA also supports numerous extended features over JPA specification and
 its well-crafted architecture allows a sophisticated plug-in framework for new features.

 Slice is one such plugged-in extension to enable JPA-based applications to work with distributed databases.

* {Why} Slice?

 Support for distributed databases are imminent as 
 an increasing number of enterprise applications are using horizontally-partitioned, distributed 
 databases for various reasons such as to counter massive data growth, to support multiple external
 clients on a hosted platform and in many other scenarios that require data partitioning.

 The standard JPA application has to address serious technical challenges if it tries to directly 
 interact with a set of physical databases. 
 Slice encapsulates this complexity of interaction with a set of databases via the abstraction of
 a virtual, distributed database which internally manages multiple physical databases. This
 database virtualization makes OpenJPA's object management kernel and the user application
 to work in the same way as in case of a single physical database. Via this notion of 
 database virtualization, Slice effectively provides the user application an object-oriented view 
 over a distributed set of databases. 

* {Distribution} Policy 

 Slice, of course, needs help from the user application. The user application needs to 
 specify a distribution policy for newly persistent instances. 
 The user application can develop their own distribution policies that can distribute
 instances based on their attributes (e.g. all PurchaseOrder instances are distributed based
 on their date of purchase or Customers by the first letter of their last name).  
 For existing instances that are loaded from the databases into memory as a result of query or
 finding by primary key, Slice tracks their
 origin and commits any updates to the appropriate database.

* {Collocation} Constraint

 However, Slice can not establish or query any cross-database relationship. This limitation leads
 to <collocation constraint> i.e. closure of any object graph must be stored in the same database. 
 Currently, distribution policy implementation has to satisfy this collocation constraint. 
 
 For example, if Person A is related to Address B, then instance A and B must reside in the same database.
 Of course, another Person C and its Address D can reside in a different database.
 
 It is possible for Slice to grow smarter and determine the closure of a root object by traversal of 
 cascaded relationships, but it is not there yet.
     

{Getting} Started with Slice

    Follow the steps to enable your OpenJPA application for distributed 
    databases with Slice:

       [[1]] {{{manual.html#Configure}Configure persistence unit}}
       
       [[2]] {{{manual.html#Slice}Configure Slices}}
  
       [[3]] {{{manual.html#implements}Implement Distribution Policy}}
  
       [[4]] {{{manual.html#Run}Run your application}}

    []
    
     [[1]] {Configure} Persistence Unit
  
         Add the following in <<<META-INF/persistence.xml>>>:
                
--------------------------------------+
         <property name="openjpa.BrokerFactory" value="slice"/>
---------------------------------------+ 
 
     [[2]] Configure the {Slice}s:

         Each Slice has a unique URL
         
--------------------------------------+
         <property name="slice.One.ConnectionURL" value="jdbc:mysql://localhost/slice1"/>
         <property name="slice.Two.ConnectionURL" value="jdbc:mysql://localhost/slice2"/>
---------------------------------------+
         will configure two slices named <<<One>>> and <<<Two>>> with corresponding database
         URL. Other properties of each slice can be configured separately, for example

--------------------------------------+
         <property name="slice.One.ConnectionUserName" value="user1"/>
         <property name="slice.Two.ConnectionUserName" value="user2"/>
---------------------------------------+

         But, if you do not configure some property of a specific slice,
         then the default value of a property is taken from corresponding 
         <<<openjpa>>> property. For example, if you specify three slices
         <<<One>>>, <<<Two>>> and <<<Three>>> where <<<One>>> and <<<Two>>>
         will be using same JDBC driver, but a different one for <<<Three>>>,
                   then the configuration will be: 
                   
--------------------------------------+
         <property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
         <property name="slice.Three.ConnectionDriverName" value="com.another.Driver"/>
---------------------------------------+
 
     [[3]] Specify a Java class that {implements} DistributionPolicy

--------------------------------------
          <property name="slice.DistributionPolicy" value="org.acme.foo.MyDistro"/>
----------------------------------------
     
           {{{apidocs/org/apache/openjpa/slice/DistributionPolicy.html} 
           org.apache.openjpa.slice.DistributionPolicy}}
           is a simple interface with a single method. The interface is described as 

-------------------------------------------------------
    /**
     * 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 a 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);
-------------------------------------------------------
      
      

     [[4]] {Run} your application

           That is it. 
  
           Run your application as usual and Slice will persist and access the instances in 
           in the distributed database environment as configured in 
           <<<META-INF/persistence.xml>>>.