User Manual

  [[1]] {{{basics.html}Preface}}
  
  	[[1.1]] {{Configure a persistence unit}}
    
    [[1.2]] {{Implement a DistributionPolicy}}
  
  [[2]] {{{user_guide.html}User Guide}}
    
    [[2.1]] {{{generate_type.html}Configure OpenJPA for distributed persistence}}
      
      [[2.2.1]] {{{generate_type.html#Basics}Distributing objects}}
      
      [[2.2.1]] {{{generate_type.html#Adding}Adding Property to SDO Types for persistence}}
      
     [[2.4.2]] {{{persist_type.html#Querying}Querying SDO DataObjects}}
     
     [[2.4.3]] {{{persist_type.html#Updating}Updating SDO DataObjects}}
    
     [[2.4.4]] {{{persist_type.html#Finding}Finding SDO DataObjects}}
     
     [[2.4.5]] {{{persist_type.html#Deleting}Deleting SDO DataObjects}}
    
  [[3]] Examples
  
    [[3.1]] Basic persistence operations with a single DataObject
    
    [[3.2]] Basic persistence operations with a graph of DataObjects
    
     * Getting started with Slice
 
  <<Step 1>>: {Configure a persistence unit} in <<<META-INF/persistence.xml>>> with
  following configuration
  
+---------------------------------------------------------  
  <property name="openjpa.BrokerFactory"    value="slice"/>
  <property name="openjpa.ConnectionURL"    value="jdbc:mysql://host1/db1|jdbc:mysql://host2/db2|jdbc:mysql://host3/db3"/>
  <property name="slice.DistributionPolicy" value="your.company.app.MyDistributionPolicy"/>
+---------------------------------------------------------
  
  Specify <<<slice>> as the value for <<<openjpa.BrokerFactory>>>. <<<slice>>>
  is the registered alias for a class that implements BrokerFactory  and 
  available in <<<openjpa-slice-0.1.0.jar>>>.
  
  Specify multiple database URLs in <<<openjpa.ConnectionURL>>> property. 
  Separate each URL with <<<|>>> character.
  
  Finally, specify name of Java class that will implement your distribution
  policy.
  
  <<Step 2>>: {Implement a DistributionPolicy}
  
  <<<org.apache.openjpa.slice.DistributionPolicy>>> is a simple interface
  that you must implement. This interface has one single method:
  
+-------------------------------------------------------
    /**
     * Gets the index of the database where a given instance will be stored.
     *  
     * @param pc The newly persistent or to-be-merged object. 
     * @param urls the list of Connection URLs in the same order as specified 
     * in the configuration.
     * 
     * @return an index in the given list. It is an error to return a value 
     * that is out of bound of the given array.
     */
     int distribute(Object pc, String[] urls); 
+-------------------------------------------------------

   <<Important>>: The most important thing to remember in implementing a 
   DistributionStrategy is that the closure of 
   a graph must be stored in the same database. For example, if Person A has 
   Address B then Person A and Address B must reside in the same database. 
   
   You can see several examplar DistributionPolicy in the samples package.

   <<Step 3>>: That is it.
   
   Now either write or use any of your existing OpenJPA application without any
   change. New instances will be stored in specific databases as dictated by
   your DistributionPolicy implementation. 
   
   Note that the policy is consulted only when new instances are persisted.
   Slice remembers the database for the instances that are realized by find() or
   result of query. If such instances are updated, Slice will update the record
   in appropriate database.