labs-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ppod...@apache.org
Subject svn commit: r606758 - in /labs/fluid/slice/src/site: ./ apt/ apt/configuration.apt apt/download.apt apt/faq.apt apt/index.apt apt/manual.apt
Date Tue, 25 Dec 2007 06:14:47 GMT
Author: ppoddar
Date: Mon Dec 24 22:14:45 2007
New Revision: 606758

URL: http://svn.apache.org/viewvc?rev=606758&view=rev
Log:
add apt files

Added:
    labs/fluid/slice/src/site/
    labs/fluid/slice/src/site/apt/
    labs/fluid/slice/src/site/apt/configuration.apt
    labs/fluid/slice/src/site/apt/download.apt
    labs/fluid/slice/src/site/apt/faq.apt
    labs/fluid/slice/src/site/apt/index.apt
    labs/fluid/slice/src/site/apt/manual.apt

Added: labs/fluid/slice/src/site/apt/configuration.apt
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/apt/configuration.apt?rev=606758&view=auto
==============================================================================
--- labs/fluid/slice/src/site/apt/configuration.apt (added)
+++ labs/fluid/slice/src/site/apt/configuration.apt Mon Dec 24 22:14:45 2007
@@ -0,0 +1,10 @@
+Configuration
+
+The source code is maintained in Subversion repository.
+
++--------------------------------------------------------- 
+  svn co https://svn.apache.org/repos/asf/labs/fluid/slice slice
++---------------------------------------------------------  
+  
+  will fetch the repository content to your local machine, in <<<slice>>>
subdirectory
+  relative to the current directory.

Added: labs/fluid/slice/src/site/apt/download.apt
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/apt/download.apt?rev=606758&view=auto
==============================================================================
--- labs/fluid/slice/src/site/apt/download.apt (added)
+++ labs/fluid/slice/src/site/apt/download.apt Mon Dec 24 22:14:45 2007
@@ -0,0 +1,46 @@
+Download Instruction 
+
+ Slice is available as a single jar.
+
+*----------+---------------------------------------------------------------*
+|  Version |                                 Download                              
+*----------+---------------------------------------------------------------*
+|  0.1.0   | {{{http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.1.0-SNAPSHOT.jar}openjpa-slice-0.1.0-SNAPSHOT.jar}}
|
+*----------+---------------------------------------------------------------*
+|  0.2.0   | {{{http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.2.0-SNAPSHOT.jar}openjpa-slice-0.2.0-SNAPSHOT.jar}}
|
+*----------+---------------------------------------------------------------*
+
+* Get the source code
+
+ Source code is maintained in Apache SubVersion repository
+ 
++--------------------------------------------------------- 
+  svn co https://svn.apache.org/repos/asf/labs/fluid/slice slice
++---------------------------------------------------------  
+  
+  will fetch the repository content to your local machine, in <<<slice>>>
+  subdirectory relative to the current directory.
+  
+* Build from source
+
+  To build the project and run the tests, you need 
+  {{{http://maven.apache.org/}Maven 2.0.x}}. 
+    
++---------------------------------------------------------  
+  $ mvn package
++---------------------------------------------------------
+
+  will compile the source code, run the tests
+  and create a <openjpa-slice-0.1.0-SNAPSHOT.jar>. 
+  
+  <<NOTE>>: 
+  The tests currently assume that two MySQL databases named 
+  <<<slice1>>> and <<<slice2>>> are available in <<<localhost>>>.

+  
+  If you are
+  using a different database, then 
+     
+     [[a]] edit <<<src/test/resources/META-INF/persistence.xml>>> accordingly
+     
+     [[b]] add \<dependency\> in <<<pom.xml>>> for the database driver
being
+     used.
\ No newline at end of file

Added: labs/fluid/slice/src/site/apt/faq.apt
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/apt/faq.apt?rev=606758&view=auto
==============================================================================
--- labs/fluid/slice/src/site/apt/faq.apt (added)
+++ labs/fluid/slice/src/site/apt/faq.apt Mon Dec 24 22:14:45 2007
@@ -0,0 +1,9 @@
+Frequently Asked Question
+
+ How do I start?
+ 
+ Can related instances be distributed across multiple databases?
+ 
+ Can I use database sequence?
+ 
+ Can I provide hints to query a specific database?
\ No newline at end of file

Added: labs/fluid/slice/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/apt/index.apt?rev=606758&view=auto
==============================================================================
--- labs/fluid/slice/src/site/apt/index.apt (added)
+++ labs/fluid/slice/src/site/apt/index.apt Mon Dec 24 22:14:45 2007
@@ -0,0 +1,39 @@
+Introduction to Slice
+
++-------------------------------------------------------------------------
+ Slice extends {{{http://openjpa.apache.org}OpenJPA}} to work with horizontally-partitioned,
distributed databases.
++-------------------------------------------------------------------------
+
+[images/slice_small]        
+
+ Slice abstracts horizontally-partitioned, distributed databases as a single 
+ virtual database for OpenJPA so that the user application can use all OpenJPA 
+ features without the technical challenges of handling multiple databases.
+ {{{http://en.wikipedia.org/wiki/Partition_(database)}Horizontal partitioning}}
+ refers to partitioning of the rows of a table across many databases. 
+ We refer these underlying databases as <Slice> in this context.
+ 
+ The salient features of Slice are: 
+   
+   [[1.]] configured as a plug-in to OpenJPA runtime
+   
+   [[2.]] no change to the application or to the persistent domain model 
+
+   [[3.]] application decides the distribution of newly persistent instances
+   across multiple databases
+   
+   [[4.]] each slice can be configured independently, thereby opening up the
+   possibility where data is distributed across heterogeneous databases. 
+   
+ The <current> limitations are
+ 
+   [[1.]] no relationships across databases; hence the closure of 
+   an object graph must be collocated in the same database
+   
+   [[2.]] no two-phase commit protocol across multiple databases when local
+   transaction is local. If OpenJPA is configured for a JTA transaction, then 
+   the underlying slices participate in global transaction.
+
+   [[3.]] no sorting of query result across multiple databases. 
+   
+   
\ No newline at end of file

Added: labs/fluid/slice/src/site/apt/manual.apt
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/apt/manual.apt?rev=606758&view=auto
==============================================================================
--- labs/fluid/slice/src/site/apt/manual.apt (added)
+++ labs/fluid/slice/src/site/apt/manual.apt Mon Dec 24 22:14:45 2007
@@ -0,0 +1,182 @@
+                            ------------------
+                            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>>>.
+
+
+
+
+ 
+
+     
+
+ 
\ 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