labs-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ppod...@apache.org
Subject svn commit: r605682 - /labs/fluid/src/site/apt/single_doc.apt
Date Wed, 19 Dec 2007 20:23:51 GMT
Author: ppoddar
Date: Wed Dec 19 12:23:50 2007
New Revision: 605682

URL: http://svn.apache.org/viewvc?rev=605682&view=rev
Log:
Commit

Added:
    labs/fluid/src/site/apt/single_doc.apt

Added: labs/fluid/src/site/apt/single_doc.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/single_doc.apt?rev=605682&view=auto
==============================================================================
--- labs/fluid/src/site/apt/single_doc.apt (added)
+++ labs/fluid/src/site/apt/single_doc.apt Wed Dec 19 12:23:50 2007
@@ -0,0 +1,166 @@
+                            ------------------
+                            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 horizontally-partitioned, distributed databases.
+ 
+ OpenJPA provides a mature and robust implementation of Java Persistence API (JPA) that 
+ has emerged as the industry-standard specification for persistence of Java objects to relational
database. 
+ 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#Download}Download Slice}}
+  
+       [[2]] {{{manual.html#Configure}Configure persistence unit}}
+  
+       [[3]] {{{manual.html#Implement}Implement Distribution Policy}}
+  
+       [[4]] {{{manual.html#Run}Run your application}}
+
+    []
+    
+    * {Download} Slice
+
+         Slice is available for download as a single Java archive. 
+         Detailed instructions to access the source code, test cases and build from the
+         source are available in the {{{download.html}download}} page.
+
+    * {Configure} Persistence Unit
+  
+            [[a]] Add the following in <<<META-INF/persistence.xml>>> to

+            activate and configure Slice:
+    
++--------------------------------------+
+   <property name="openjpa.BrokerFactory" value="slice"/>
++---------------------------------------+ 
+ 
+            [[b]] Specify ConnectionURL for multiple database URLs concatenated with | character.
+
++--------------------------------------+
+   <property name="openjpa.ConnectionURL" value="slice"/>
++---------------------------------------+
+ 
+            [[c]] Specify a Java class that implements DistributionPolicy
+
++--------------------------------------
+   <property name="slice.DistributionPolicy" value="org.acme.foo.MyDistro"/>
++----------------------------------------
+    []     
+         
+
+    * {Implement} Distribution Policy
+
+            {{{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 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); 
++-------------------------------------------------------
+      
+      
+
+    * {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>>>.
+
+
+
+
+ 
+
+     
+
+ 
\ No newline at end of file



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@labs.apache.org
For additional commands, e-mail: commits-help@labs.apache.org


Mime
View raw message