labs-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ppod...@apache.org
Subject svn commit: r605683 - /labs/fluid/src/site/apt/
Date Wed, 19 Dec 2007 20:24:11 GMT
Author: ppoddar
Date: Wed Dec 19 12:24:09 2007
New Revision: 605683

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

Added:
    labs/fluid/src/site/apt/flyer.apt
    labs/fluid/src/site/apt/index.apt
      - copied, changed from r591693, labs/fluid/src/site/apt/welcome.apt
    labs/fluid/src/site/apt/manual.apt
      - copied unchanged from r605682, labs/fluid/src/site/apt/single_doc.apt
    labs/fluid/src/site/apt/user_manual_index.apt
      - copied, changed from r591693, labs/fluid/src/site/apt/manual.apt
Removed:
    labs/fluid/src/site/apt/convert_type.apt
    labs/fluid/src/site/apt/enhance_type.apt
    labs/fluid/src/site/apt/generate_type.apt
    labs/fluid/src/site/apt/persist_type.apt
    labs/fluid/src/site/apt/single_doc.apt
    labs/fluid/src/site/apt/welcome.apt
Modified:
    labs/fluid/src/site/apt/configuration.apt
    labs/fluid/src/site/apt/design.apt
    labs/fluid/src/site/apt/download.apt
    labs/fluid/src/site/apt/faq.apt
    labs/fluid/src/site/apt/intro.apt
    labs/fluid/src/site/apt/user_guide.apt

Modified: labs/fluid/src/site/apt/configuration.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/configuration.apt?rev=605683&r1=605682&r2=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/configuration.apt (original)
+++ labs/fluid/src/site/apt/configuration.apt Wed Dec 19 12:24:09 2007
@@ -3,8 +3,8 @@
 The source code is maintained in Subversion repository.
 
 +--------------------------------------------------------- 
-  svn co https://svn.apache.org/repos/asf/labs/fluid fluid
+  svn co https://svn.apache.org/repos/asf/labs/fluid/slice slice
 +---------------------------------------------------------  
   
-  will fetch the repository content to your local machine, in fluid subdirectory
+  will fetch the repository content to your local machine, in <<<slice>>>
subdirectory
   relative to the current directory.

Modified: labs/fluid/src/site/apt/design.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/design.apt?rev=605683&r1=605682&r2=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/design.apt (original)
+++ labs/fluid/src/site/apt/design.apt Wed Dec 19 12:24:09 2007
@@ -1,47 +1,31 @@
 Design
 
- The main aim of designing persistence service for Service Data Objects is
- to leverage the features of OpenJPA. OpenJPA solves the <complex> problem of
- mapping a set of domain objects (expressed as POJO) to a set of relational
- database tables. The basic input to OpenJPA is a set of strongly-typed, 
- compiled Java classes that represent the persistent domain model and 
- information on how these objects be mapped to relational database tables. The 
- mapping information can be specified as Annotations in the Java source code or
- in a XML mapping file or combination of both.
+ The main aim of Slice is to support any OpenJPA application for distributed
+ databases without any modification to the application. 
  
- Service Data Objects, on the other hand, are <not> strongly-typed. They are
- often termed as <loosly-typed> but we will refer them as <relaxed type>. 
- 
- Fluid design approaches the problem by mapping SDO Types to 
- strongly-typed Java classes. This mapping is essentially isomorphic i.e.
- commonj.sdo.Type maps to java.lang.Class, commonj.sdo.Property maps to
- java.lang.Field. Any name in SDO space is mapped to identical name Java space.
- 
- Once the Java class if available, OpenJPA can 
- work with these Java classes as usual. The only extension at runtime
- is an extension of EntityManager that adapts the semantics of JPA API
- by accepting DataObjects as arguments to persistence operation methods
- (thankfully JPA API accepts java.lang.Object). The only
- complexity involved in conversion is maintaining consitent closure and
- not falling into infinite loops for DataObject graphs that has loops.
- Currently conversion of
- DataObject instances to Java instances is done via reflection. 
- It is feasible to simplify this conversion at runtime by generating code in
- the generated Java classes.
- 
- On the query side, JPQL is the query language as defined by JPA. However, 
- the result of JPQL query <commonly> is a list of Objects. So another
- conversion operates to populate DataObjects from the Java instances before
- returning the results to the caller. 
- 
- 
- Few other bits involve
- 
- [[1]] A new SDOMetaDataFactory that handles the mapping between SDO Types 
- and Java Classes.
- 
- [[2]] A ProductDerivation that configures SDOEntityManagerFactory and 
- SDOMetaDataFactory
-  
+ OpenJPA interacts with
+ the underlying (not necessarily relational) database via StoreManager interface.
+ Slice design approaches the problem of distributed persistence by developing a 
+ specialized StoreManager called DistributedStoreManager. This DistributedStoreManager
+ is responsible for fanning out database operations to the set of databases instead of
+ a single one as in case of standard JDBCStoreManager.
+ 
+ DistributedStoreManager requires to identify one the databases when it stores
+ a newly persistent instance. This decision is left to the user application 
+ via DistributionPolicy interface. 
+ 
+ When DistributedStoreManager loads any existing instance from the database 
+ into memory, the instance is tagged with the database identifier so that any
+ subsequent update can be applied to the original database record.
+ 
+ However, when the instance is detached from its persistence context and may
+ be serialized to another remote process, the database identifier tag is
+ no more remembered. While the application subsequently merges the detached
+ instance in a possibly different persistence context, DistributedStoreManager
+ will again invoke DistributionPolicy to determine the original physical datastore.
+ 
+ The major limitation of the current model is the closure of any object graph
+ must reside in the same database. There is no facility to perform a query that
+ requires evaluation across multiple databases.  
      
   

Modified: labs/fluid/src/site/apt/download.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/download.apt?rev=605683&r1=605682&r2=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/download.apt (original)
+++ labs/fluid/src/site/apt/download.apt Wed Dec 19 12:24:09 2007
@@ -1,46 +1,44 @@
-Download 
+Download Instruction 
 
- Fluid is available as a single jar.
+ Slice is available as a single jar.
 
 *----------+---------------------------------------------------------------*
 |  Version |                                                               
 *----------+---------------------------------------------------------------*
-|  0.1.0   | {{{http://svn.apache.org/repos/asf/labs/fluid/sdo-persistence-0.1.0-SNAPSHOT.jar}sdo-persistence-0.1.0-SNAPSHOT.jar}}
|
+|  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/sdo-persistence-0.2.0-SNAPSHOT.jar}sdo-persistence-0.2.0-SNAPSHOT.jar}}
|
-*-------------------------------------|-----------------------------------*
 
-* Build from Source Code
+* Get the source code
 
- Source code is maintained in SubVersion repository
+ Source code is maintained in Apache SubVersion repository
  
 +--------------------------------------------------------- 
-  svn co https://svn.apache.org/repos/asf/labs/fluid fluid
+  svn co https://svn.apache.org/repos/asf/labs/fluid/slice slice
 +---------------------------------------------------------  
   
-  will fetch the repository content to your local machine, in fluid subdirectory
-  relative to the current directory.
+  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 sdo-persistence-<<<\<VERSION\>>>>.jar. 
+  and create a <openjpa-slice-0.1.0-SNAPSHOT.jar>. 
   
-+----------------------------------------------------------
- $ mvn install
-+----------------------------------------------------------
-
-  will add the target jar to Maven repository.
-  
- 
-  
-   
-
- 
-   
- 
+  <<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

Modified: labs/fluid/src/site/apt/faq.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/faq.apt?rev=605683&r1=605682&r2=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/faq.apt (original)
+++ labs/fluid/src/site/apt/faq.apt Wed Dec 19 12:24:09 2007
@@ -1 +1,9 @@
-Frequently Asked Question
\ No newline at end of file
+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/src/site/apt/flyer.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/flyer.apt?rev=605683&view=auto
==============================================================================
--- labs/fluid/src/site/apt/flyer.apt (added)
+++ labs/fluid/src/site/apt/flyer.apt Wed Dec 19 12:24:09 2007
@@ -0,0 +1,8 @@
+Slice
+
+ Slice extends OpenJPA to work with horizontally-partitioned, distributed
+ database environment.
+ 
+                   
+                  
+         
\ No newline at end of file

Copied: labs/fluid/src/site/apt/index.apt (from r591693, labs/fluid/src/site/apt/welcome.apt)
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/index.apt?p2=labs/fluid/src/site/apt/index.apt&p1=labs/fluid/src/site/apt/welcome.apt&r1=591693&r2=605683&rev=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/welcome.apt (original)
+++ labs/fluid/src/site/apt/index.apt Wed Dec 19 12:24:09 2007
@@ -1,7 +1,18 @@
-				
- Fluid - under the aegis of {{{http://labs.apache.org}Apache Lab}} - explores 
- how to extend {{{http://openjpa.apache.org}OpenJPA}} to support application 
- domain model expressed in 
- {{{http://incubator.apache.org/tuscany/sdo-overview.html}Service Data Objects}}.
+Introduction
+			
+ Slice extends {{{http://openjpa.apache.org}OpenJPA}} to work with distributed databases.
 
-[images/Fluid.png] Persistence Service For Service Data Objects
\ No newline at end of file
+ OpenJPA is a mature and stable implementation of JPA API for persistence operations on Java
objects.
+ An application can store and access objects using OpenJPA from a relational database.
+ Slice is built as an extension of OpenJPA such that the objects can be distributed across
+ a set of physical databases instead of a single one without any change to the application.
 
+
+ Of course, Slice needs a bit of help from the application developer. When a new
+ object instance is inserted in the database, the application must select one of
+ the physical databases for the instance to be persisted. For subsequent access
+ and update, Slice will remember the original database of any instance.  
+
+ 
+
+
+[images/slice.png] JPA Persistence Service For Distributed Databases
\ No newline at end of file

Modified: labs/fluid/src/site/apt/intro.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/intro.apt?rev=605683&r1=605682&r2=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/intro.apt (original)
+++ labs/fluid/src/site/apt/intro.apt Wed Dec 19 12:24:09 2007
@@ -1,69 +1,56 @@
-Introduction to Fluid
+Introduction to Slice
 
-* What is {Fluid}?
+* What is Slice?
  
-  Fluid provides persistence service for Service Data Objects (SDO) using Java 
-  Persistence Architecture (JPA). 
-  
-  Fluid is based on 
-  {{{http://openjpa.apache.org}OpenJPA}} -- 
-  open source implementation of JPA by 
-  {{{http://www.apache.org}Apache Software Foundation}}.
-  
-  Fluid is being developed under the aegis of 
-  {{{http://labs.apache.org/}Apache Labs}}.
-  
-  Fluid is {{{download.html}available}} as a single Java archieve. 
-  
-  
-* How JPA {relates} to SDO? 
-  
-  Java Persistence API is a mature standard for persistence service of Java
-  objects. The persistent Java object is often referred as Pure Old Java Object
-  or POJO because to no special requirement (inheriting a super class or 
-  implementing a interface) has been introduced on the persistent domain objects
-  to use persistence services of JPA.
-   
-  Service Data Objects is a specification to define loosely-typed 
-  data structures. Service Data Objects gains more significance as data
-  representation for Service Component Architecture.
-  
-  Service Data Objects specification currently 
-  mentions of a Data Access Service but does not specify
-  any further details.    
-  
-  Fluid explores how data specified in a loosely-typed system (as in SDO) can
-  be operated with JPA which is based on data represented in a strongly-type 
-  system. 
-  
-  SDO relates to JPA <naturally>. Many important features of 
-  Service Data Objects such as  navigational access, 
-  detached mode operations via Change Summary are quite akin to usage patterns
-  where JPA excels as a persistence service. So, Fluid was motivated to explore 
-  this <naturalness> assumption.
+ Slice is a plug-in for {{{http://openjpa.apache.org}OpenJPA}} to work with 
+ horizontally-partitioned, distributed databases. 
+ 
+ OpenJPA is a mature and stable implementation of JPA API for persistence 
+ operations on Java objects. An OpenJPA application can store and access objects  
+ using a relational database. Slice is built as an extension of OpenJPA 
+ such that the objects can be distributed across {more than one} physical 
+ database without any change to the application.  
+ 
+  Slice works with set of database instances that are horizontally-partitioned 
+ i.e. they have identical schema but the records are distributed across the
+ table in multiple databases following some particular criteria. For example, 
+ Customer names starting from 'A' to 'N' resides in database 1 while names 
+ starting 'O' to 'Z' are in a second database.  
+ 
+  Of course, Slice needs a bit of help from the application to know how the new 
+ instances are to be distributed among multiple databases. For access
+ and update of existing instances, however, Slice remembers the original 
+ database for any instance. 
+ 
+ 
+ 
+* Why Slice?
+ 
+   All the data may not reside in a single relational database. 
+   Sometimes there is too much data. Sometimes 
+   a deployment architecture is distributed.
+   Sometimes a hosted platform needs each client company's data be partitioned 
+   into separate database instance. 
+   
+   Whatever be the reasons, multiple relational databases obviously complicates 
+   the development of your application. Slice is designed to encapsulate this 
+   complexity while offering the benefits of OpenJPA. 
+   Slice effectively creates a unified object-oriented view of multiple 
+   databases via OpenJPA.
+ 
+* How to get started with Slice?
+    
+ Slice is available for {{{download.html}download}} as a single Java archive. 
   
-  Also from practical considerations, object persistence (be it strongly- or 
-  loosly-typed) against a relational database is a 
-  {{{http://nedbatchelder.com/blog/200606.html}<hard>}} problem. 
-  OpenJPA 
-  is a mature 
-  solution to this complex O-R mapping problem (also other few JPA 
-  implementaions such as {{{http://www.hibernate.org}Hibernate}}, 
-  {{{http://www.oracle.com/technology/products/ias/toplink/index.html}TopLink}}). 
-  Hence, instead of reinventing  a
-  <costly> wheel, SDO should use JPA for persistence service. 
+ The {{{user_manual_index.html}user manual}} describes how to use Slice in your 
+ application with examples. 
   
    
 * {Resources}
 
    * JPA Specification
    
-   * SDO Specification
-   
-   * SCA Specification
-   
    * OpenJPA
-   
-   * Tuscany
-   
-   * Tuscany SDO
\ No newline at end of file
+     
+  
+   
\ No newline at end of file

Modified: labs/fluid/src/site/apt/user_guide.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/user_guide.apt?rev=605683&r1=605682&r2=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/user_guide.apt (original)
+++ labs/fluid/src/site/apt/user_guide.apt Wed Dec 19 12:24:09 2007
@@ -1,20 +1,16 @@
 User Guide
 
- The basic steps to active OpenJPA to process SDO DataObjects are
+ The basic steps to active OpenJPA for distributed database are
  
-   [[1]] Define SDO Types in XML Schema files 
+   [[1]] Configure META-INF/persistence.xml for distributed databases
    
-   [[2]] Generate Java Source code corresponding to SDO Types
+   [[2]] Implement a Java class for DistributionPolicy
    
-   [[3]] Configure OpenJPA to enable support for SDO
+   [[3]] Run your OpenJPA application
    
-   [[4]] User application creates SDO DataObjects/Graphs using SDO API
-   
-   [[5]] These SDO DataObjects can be stored or updated using JPA API
-   
-   [[6]] User application can also query via JPQL to receive DataObjects
-   from a relational database.
- 
+   [[4]] The instances will be stored and accessed from the set of physical
+   databases as designated in openjpa.ConnectionURL property
+    
  
  {{{generate_type.html}Following}} pages describes these steps in further details.
  

Copied: labs/fluid/src/site/apt/user_manual_index.apt (from r591693, labs/fluid/src/site/apt/manual.apt)
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/user_manual_index.apt?p2=labs/fluid/src/site/apt/user_manual_index.apt&p1=labs/fluid/src/site/apt/manual.apt&r1=591693&r2=605683&rev=605683&view=diff
==============================================================================
--- labs/fluid/src/site/apt/manual.apt (original)
+++ labs/fluid/src/site/apt/user_manual_index.apt Wed Dec 19 12:24:09 2007
@@ -1,33 +1,19 @@
-User Documentation
+User Manual
 
-  [[1]] {{{intro.html}Introduction}}
+  [[1]] {{{basics.html}Preface}}
   
-  	[[1.1]] {{{intro.html#relates}SDO and JPA}}
+  	[[1.1]] {{Configure a persistence unit}}
     
-    [[1.2]] {{{intro.html#Resources}Resources}}
+    [[1.2]] {{Implement a DistributionPolicy}}
   
   [[2]] {{{user_guide.html}User Guide}}
     
-    [[2.1]] {{{generate_type.html}Decorating SDO Type for persistence}}
+    [[2.1]] {{{generate_type.html}Configure OpenJPA for distributed persistence}}
       
-      [[2.2.1]] {{{generate_type.html#Basics}Basics of SDO Types}}
+      [[2.2.1]] {{{generate_type.html#Basics}Distributing objects}}
       
       [[2.2.1]] {{{generate_type.html#Adding}Adding Property to SDO Types for persistence}}
       
-        [[2.2.1.1]] {{{generate_type.html#Identity}Adding Identity Property}}
-        
-        [[2.2.1.2]] {{{generate_type.html#Version}Adding Version Property}}
-        
-    [[2.2]] {{{convert_type.html}Mapping SDO Types to Java source code}}
-    
-    [[2.3]] {{{enhance_type.html}Enhancing Java source code for persistence}}
-    
-    [[2.4]] {{{persist_type.html}Persistence operations with SDO DataObjects}}
-    
-     [[2.4.0]] {{{persist_type.html#Configuring}Configuring for SDO Persistence}}
-    
-     [[2.4.1]] {{{persist_type.html#Storing}Storing SDO DataObjects}}
-    
      [[2.4.2]] {{{persist_type.html#Querying}Querying SDO DataObjects}}
      
      [[2.4.3]] {{{persist_type.html#Updating}Updating SDO DataObjects}}
@@ -41,3 +27,62 @@
     [[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. 
+    



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


Mime
View raw message