You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@labs.apache.org by pp...@apache.org on 2008/01/05 05:55:57 UTC
svn commit: r609091 - in /labs/fluid/slice: ./ src/doc/ src/site/
src/site/resources/
Author: ppoddar
Date: Fri Jan 4 20:55:56 2008
New Revision: 609091
URL: http://svn.apache.org/viewvc?rev=609091&view=rev
Log:
version 0.4.0
Added:
labs/fluid/slice/openjpa-slice-0.4.0.jar (with props)
labs/fluid/slice/src/site/not.site.xml
- copied unchanged from r608351, labs/fluid/slice/src/site/site.xml
labs/fluid/slice/src/site/resources/index.html
- copied unchanged from r608358, labs/fluid/slice/src/site/resources/main.html
Removed:
labs/fluid/slice/openjpa-slice-0.1.0-SNAPSHOT.jar
labs/fluid/slice/openjpa-slice-0.2.0-SNAPSHOT.jar
labs/fluid/slice/openjpa-slice-0.3.0-SNAPSHOT.jar
labs/fluid/slice/src/site/resources/main.html
labs/fluid/slice/src/site/site.xml
Modified:
labs/fluid/slice/pom.xml
labs/fluid/slice/src/doc/architecture.xml
labs/fluid/slice/src/doc/download.xml
labs/fluid/slice/src/doc/features.xml
labs/fluid/slice/src/doc/introduction.xml
labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl
labs/fluid/slice/src/doc/manual-xhtml.xsl
labs/fluid/slice/src/doc/release_notes.xml
labs/fluid/slice/src/doc/slice.xml
labs/fluid/slice/src/doc/user_manual.xml
labs/fluid/slice/src/site/resources/banner.html
labs/fluid/slice/src/site/resources/footer.html
labs/fluid/slice/src/site/resources/menu.html
labs/fluid/slice/src/site/resources/welcome.html
Added: labs/fluid/slice/openjpa-slice-0.4.0.jar
URL: http://svn.apache.org/viewvc/labs/fluid/slice/openjpa-slice-0.4.0.jar?rev=609091&view=auto
==============================================================================
Binary file - no diff available.
Propchange: labs/fluid/slice/openjpa-slice-0.4.0.jar
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: labs/fluid/slice/pom.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/pom.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/pom.xml (original)
+++ labs/fluid/slice/pom.xml Fri Jan 4 20:55:56 2008
@@ -27,7 +27,7 @@
<groupId>org.apache.openjpa</groupId>
<artifactId>openjpa-slice</artifactId>
<packaging>jar</packaging>
- <version>0.3.0-SNAPSHOT</version>
+ <version>0.4.0</version>
<name>Slice</name>
<description>Distributed Persistence Service using OpenJPA</description>
<url>http://people.apache.org/~ppoddar/slice/site/index.html</url>
@@ -273,7 +273,7 @@
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
- <execution>
+ <execution>
<id>build-pdf-doc</id>
<phase>process-resources</phase>
<goals><goal>generate-pdf</goal></goals>
@@ -285,6 +285,7 @@
<imgSrcPath>${docbook.source}/</imgSrcPath>
</configuration>
</execution>
+ <!-- No chunked document for now
<execution>
<id>build-chunked-doc</id>
<phase>process-resources</phase>
@@ -314,6 +315,7 @@
</postProcess>
</configuration>
</execution>
+ No chunked document for now -->
<execution>
<id>build-single-doc</id>
<phase>process-resources</phase>
@@ -388,7 +390,6 @@
<reportSet>
<reports>
<report>javadoc</report>
- <!-- <report>test-javadoc</report> -->
</reports>
</reportSet>
</reportSets>
@@ -399,46 +400,16 @@
<reportSets>
<reportSet>
<reports>
+ <!-- No stock reports for now
<report>dependencies</report>
<report>project-team</report>
<report>mailing-list</report>
<report>scm</report>
+ no reports for now -->
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
-</project>
-
-
-<!--
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>2.2</version>
- <configuration>
- <outputDirectory>${javadoc.output.dir}</outputDirectory>
- <reportOutputDirectory>${javadoc.output.dir}</reportOutputDirectory>
- <additionalparam>${javadoc.additionalparam}</additionalparam>
- <aggregate>true</aggregate>
- <verbose>false</verbose>
- <noqualifier>all</noqualifier>
- <maxmemory>512m</maxmemory>
- <links>
- <link>http://java.sun.com/j2se/1.5.0/docs/api</link>
- <link>http://java.sun.com/javaee/5/docs/api</link>
- <link>http://openjpa.apache.org/docs/latest/javadoc/</link>
- <link>http://jakarta.apache.org/commons/collections/api-release</link>
- </links>
- </configuration>
- <executions>
- <execution>
- <goals>
- <goal>javadoc</goal>
- <goal>test-javadoc</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
--->
+</project>
\ No newline at end of file
Modified: labs/fluid/slice/src/doc/architecture.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/architecture.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/architecture.xml (original)
+++ labs/fluid/slice/src/doc/architecture.xml Fri Jan 4 20:55:56 2008
@@ -23,7 +23,7 @@
<title>OpenJPA Architecture</title>
<para>
OpenJPA is built on sound architectural principles. Its core components
- communicate via well-designed interfaces and respects on which layer of
+ communicate via well-designed interfaces and respects which layer of
processing they belong. The object management kernel does not assume any
specific nature of data storage system or user-level APIs.
</para>
@@ -71,6 +71,7 @@
<title>Distributed Template Pattern</title>
</section>
+ &homer;
</chapter>
Modified: labs/fluid/slice/src/doc/download.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/download.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/download.xml (original)
+++ labs/fluid/slice/src/doc/download.xml Fri Jan 4 20:55:56 2008
@@ -18,6 +18,7 @@
under the License.
-->
<chapter id="download">
+
<title>Download Instruction</title>
<section id="download_jar">
@@ -42,22 +43,22 @@
<tbody>
<row>
<entry colname="version">0.4.0</entry>
- <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.4.0-SNAPSHOT.jar">openjpa-slice-0.4.0-SNAPSHOT.jar</ulink></entry>
+ <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.4.0.jar">openjpa-slice-0.4.0.jar</ulink></entry>
<entry colname="note"><link linkend="release_notes_0.4.0">Release Note</link></entry>
</row>
<row>
<entry colname="version">0.3.0</entry>
- <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.3.0-SNAPSHOT.jar">openjpa-slice-0.3.0-SNAPSHOT.jar</ulink></entry>
+ <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.3.0.jar">openjpa-slice-0.3.0.jar</ulink></entry>
<entry colname="note"><link linkend="release_notes_0.3.0">Release Note</link></entry>
</row>
<row>
<entry colname="version">0.2.0</entry>
- <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.2.0-SNAPSHOT.jar">openjpa-slice-0.2.0-SNAPSHOT.jar</ulink></entry>
+ <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.2.0.jar">openjpa-slice-0.2.0.jar</ulink></entry>
<entry colname="note"><link linkend="release_notes_0.2.0">Release Note</link></entry>
</row>
<row>
<entry colname="version">0.1.0</entry>
- <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.1.0-SNAPSHOT.jar">openjpa-slice-0.1.0-SNAPSHOT.jar</ulink></entry>
+ <entry colname="download"><ulink url="http://svn.apache.org/repos/asf/labs/fluid/slice/openjpa-slice-0.1.0.jar">openjpa-slice-0.1.0.jar</ulink></entry>
<entry colname="note"><link linkend="release_notes_0.1.0">Release Note</link></entry>
</row>
</tbody>
@@ -84,7 +85,7 @@
<para>
To build the project and run the tests, <ulink url="http://maven.apache.org/">Maven 2.0.x</ulink> is required.
The following command will compile the source code, run the tests
- and create a <code>openjpa-slice-{VERSION}-SNAPSHOT.jar</code>.
+ and create a <code>openjpa-slice-{VERSION}.jar</code>.
<programlisting>
mvn package
</programlisting>
@@ -103,7 +104,7 @@
mvn package -Dtest=false
</programlisting>
</para>
-
</section>
+ &homer;
</chapter>
Modified: labs/fluid/slice/src/doc/features.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/features.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/features.xml (original)
+++ labs/fluid/slice/src/doc/features.xml Fri Jan 4 20:55:56 2008
@@ -23,61 +23,99 @@
<section id="Features">
<title>Salient Features</title>
<para>
- Slice virtualizes a set of distributed databases to make it appear
- as a single database to OpenJPA Object Management kernel.
+ The primary objective of Slice is to make building distributed database
+ applications with OpenJPA simple.
</para>
<section><title>Transparency</title>
<para>
- No change to the application or to the persistent domain model to
- upgrade from a single database to a distributed database
- environment.
+ The existing application or the persistent domain model requires
+ <emphasis>no change</emphasis> to upgrade from a single database
+ to a distributed database environment.
</para>
</section>
- <section><title>Custom Distribution Policy</title>
+ <section><title>Custom Data Distribution Policy</title>
<para>
User application decides how the newly persistent instances be
- distributed across multiple databases. Slice tracks the original
- database for existing instances so that any update happens to the
- appropriate database.
+ distributed across multiple database slices. The data
+ distribution policy across the slices may be based on the attribute
+ of the data itself. For example, all Customer whose first name begins with
+ character 'A' to 'M' will be stored in one database while names
+ beginning with 'N' to 'Z' will be stored in another slice. It is
+ also common to find data distribution policies based on temporal
+ attributes.
+ </para>
+ <para>
+ Slice tracks the original database for existing instances. When
+ an application issues a query, the instances may be loaded from
+ from different database slices. This tracking is important as
+ update to any instance gets committed to the appropriate database.
</para>
</section>
<section><title>Heterogeneous Database</title>
<para>
Each slice can be configured independently with its own JDBC
- driver, hence data can be distributed across heterogeneous
+ driver. Hence data can be distributed across heterogeneous
databases.
</para>
</section>
- <section><title>Native XA support</title>
+
+ <section><title>Parallel Execution</title>
<para>
+ All database operations such as query, commit or flush operates
+ in parallel across the database slices.
</para>
</section>
- <section><title>Parallel Execution</title>
+
+ <section><title>Distributed Transaction</title>
<para>
- Query and Flush operations execute in each slice in parallel.
+ The database slices participate in a global transaction provided
+ each slice is configured with a XA-complaint JDBC driver, even
+ when the persistence unit is configured for <code>RESOURCE_LOCAL</code>
+ transaction.
</para>
- </section>
- </section>
-
+ <para>
+ <warning>
+ If any of the configured slices are non-XA-complaint <emphasis>and</emphasis>
+ the persistence unit is configured for <code>RESOURCE_LOCAL</code>
+ transaction then each slice is committed without any two-phase
+ commit protocol. If commit on any slice fails, then atomicity of
+ the transaction is not ensured.
+ </warning>
+ </para>
+ </section>
+ </section>
+
<section id="Limitations">
<title>Limitations</title>
- <section><title>Collocation Constraint</title>
+ <section id="collocation_constraint"><title>Collocation Constraint</title>
<para>
- No relationships across databases.
- Hence the closure of an object graph must be collocated in the same database.
- Slice, however, helps to maintain the collocation constraint by automatically
- assigning the correct slice for all cascaded relationship. The user-defined
- DistributionPolicy requires to supply the slice for the root instance only.
+ No relationship can exist across database slices. In O-R mapping paradigm,
+ this translates to the limitation that the closure of an object graph must be
+ <emphasis>collocated</emphasis> in the same database.
+ For example, consider a domain model where Person relates to Adress.
+ Person X refers to Address A while Person Y refers to Address B.
+ Collocation Constraint means that <emphasis>both</emphasis> X and A
+ must be stored in the same
+ database slice. Similarly Y and B must be stored in a single slice.
+ </para>
+ <para>
+ Slice, however, helps to maintain collocation constraint automatically.
+ The instances in the closure set of any newly persistent instance
+ reachable via cascaded relationship is stored in the same slice.
+ The user-defined distribution policy requires to supply the slice
+ for the root instance only.
</para>
</section>
<section><title>No Sorting</title>
<para>
- no sorting of query result across multiple databases.
+ If a query specified <code>ORDER BY</code> clause, then the results
+ from individual database slices are sorted but the result is not sorted
+ across multiple slices.
</para>
</section>
-
</section>
+ &homer;
</chapter>
Modified: labs/fluid/slice/src/doc/introduction.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/introduction.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/introduction.xml (original)
+++ labs/fluid/slice/src/doc/introduction.xml Fri Jan 4 20:55:56 2008
@@ -23,21 +23,41 @@
<section id="introduction_what_is_slice">
<title>What is Slice?</title>
<para>
- Slice extends OpenJPA for horizontally-partitioned, distributed database
- environment.
+ Slice extends OpenJPA for distributed databases. Slice plugs-in to OpenJPA
+ runtime as a single library and can be activated by configuring
+ a persistence unit for multiple databases.
</para>
-
<para>
- JPA is a industry-standard specification for persistence of Java objects to
- relational database.
- OpenJPA is a mature, production-quality implementation of Java Persistence
- API (JPA). OpenJPA is available as top level Apache Open Source Project.
- OpenJPA supports numerous extended features over JPA specification and
+ Once configured for Slice, an existing OpenJPA application can transact
+ against multiple databases in the same transaction. The application
+ queries will be executed in parallel against all the databases and
+ any update will be committed to the appropriate databases.
+ </para>
+ </section>
+
+ <section id="introduction_background">
+ <title>Background</title>
+ <para>
+ Java Persistence API (JPA) is a industry-standard specification for persistence of Java objects to
+ relational database. JPA standardizes the complex object-relational mapping
+ problem and is supported by mature implementations from vendors such as
+ BEA Kodo, JBoss Hibernate or Oracle Toplink. JPA is
+ also the persistence service for EJB 3.0 in JEE environment.
+ </para>
+
+ <para>
+ <ulink url="http://openjpa.apache.org">OpenJPA</ulink> - a top level Apache
+ Open Source Project
+ - is a feature-rich, production-quality implementation of JPA.
+ OpenJPA supports numerous extended features over JPA standards and
its well-crafted architecture allows a sophisticated plug-in framework for
addition of new features.
-
- Slice is one such plug-in extension to enable JPA-based applications to
- work with distributed databases.
+ </para>
+ <para>
+ Slice is one such plug-in extension to enable any OpenJPA-based application
+ to work with distributed, horizontally-partitioned, possibly heterogeneous
+ databases <emphasis>without</emphasis> any change
+ to application code or the persistent domain model.
</para>
</section>
@@ -46,24 +66,27 @@
<section id="why">
<title>Why Slice?</title>
<para>
- 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 may benefit from partitioning data into separate databases.
+ Enterprise applications are increasingly using a distributed databases.
+ The reasons for distributed, often horizontally-partitioned databases can
+ be to counter massive data growth, or to support multiple external clients
+ on a hosted platform and in many other scenarios that may benefit from
+ data partitioning.
</para>
<para>
- 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
+ Any JPA-based user application has to address serious technical and conceptual
+ challenges if it tries to directly interact with a set of physical databases
+ within a single transaction.
+ Slice encapsulates this complexity of distributed database interaction
+ via the abstraction of a virtual database which internally
+ manages multiple physical databases henceforth referred as <emphasis>database
+ slice</emphasis>.
+ This <emphasis>virtualization</emphasis> of distributed databases approach
+ 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
+ database. Via this database virtualization approach, Slice effectively
provides the user application an object-oriented view over a distributed set
- of databases.
+ of, possibly heterogeneous, databases,
</para>
</section>
@@ -73,7 +96,8 @@
<title>Purpose of this Document</title>
<para>
This document describes how to use Slice to enable OpenJPA applications
- for distributed database environment.
+ for distributed database environment. This document also discusses the
+ architecture and critical design aspects of Slice.
</para>
</section>
@@ -81,9 +105,14 @@
<title>Intended Audience</title>
<para>
This document is intended for developers interested in building
- distributed applications using OpenJPA. It assumes familiarity with
- OpenJPA usage and distributed database environment.
+ distributed database applications using OpenJPA. This document assumes
+ familiarity with OpenJPA usage and distributed database environment.
+ </para>
+ <para>
+ This document is also targeted for developers who are interested in
+ extending OpenJPA or its basic architectural aspects.
</para>
</section>
+ &homer;
</chapter>
Modified: labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl (original)
+++ labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl Fri Jan 4 20:55:56 2008
@@ -45,5 +45,6 @@
<xsl:param name="use.id.as.filename" select="'1'"/>
<xsl:template name="process.image.attributes"/>
+ <xsl:param name="section.label.includes.component.label" select="1"></xsl:param>
</xsl:stylesheet>
Modified: labs/fluid/slice/src/doc/manual-xhtml.xsl
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/manual-xhtml.xsl?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/manual-xhtml.xsl (original)
+++ labs/fluid/slice/src/doc/manual-xhtml.xsl Fri Jan 4 20:55:56 2008
@@ -34,7 +34,7 @@
article/appendix nop
article toc,title
book toc,title,figure,example,equation
-chapter title
+chapter title,toc
part toc,title
preface toc,title
qandadiv toc
Modified: labs/fluid/slice/src/doc/release_notes.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/release_notes.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/release_notes.xml (original)
+++ labs/fluid/slice/src/doc/release_notes.xml Fri Jan 4 20:55:56 2008
@@ -21,20 +21,20 @@
<title>Release Notes</title>
<section id="release_notes_0.4.0">
- <title>Version 0.4.0</title>
- <orderedlist>
+ <title>Changes in version 0.4.0</title>
+ <itemizedlist>
<listitem>
<para>
- First working version for extending OpenJPA to horizontally-partitioned,
- distributed database.
+ Uses a native and naive internal Distributed Transaction Manager to
+ enable 2-phase commit when underlying slices are XA-complaint.
</para>
</listitem>
- </orderedlist>
+ </itemizedlist>
</section>
<section id="release_notes_0.3.0">
- <title>Version 0.3.0</title>
- <orderedlist>
+ <title>Changes in version 0.3.0</title>
+ <itemizedlist>
<listitem>
<para>
Automatic Collocation Constraint : Identifies the correct
@@ -49,12 +49,12 @@
identifier of the root instance.
</para>
</listitem>
- </orderedlist>
+ </itemizedlist>
</section>
<section id="release_notes_0.2.0">
- <title>Version 0.2.0</title>
- <orderedlist>
+ <title>Changes in version 0.2.0</title>
+ <itemizedlist>
<listitem>
<para>
Per-slice Configuration: Now each slice can be configured with separate
@@ -66,20 +66,20 @@
The previous multi-URL configuration is no more supported.
</para>
</listitem>
- </orderedlist>
+ </itemizedlist>
</section>
<section id="release_notes_0.1.0">
- <title>Version 0.1.0</title>
- <orderedlist>
+ <title>Changes in version 0.1.0</title>
+ <itemizedlist>
<listitem>
<para>
First working version for extending OpenJPA to horizontally-partitioned,
distributed database.
</para>
</listitem>
- </orderedlist>
+ </itemizedlist>
</section>
-
+ &homer;
</chapter>
Modified: labs/fluid/slice/src/doc/slice.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/slice.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/slice.xml (original)
+++ labs/fluid/slice/src/doc/slice.xml Fri Jan 4 20:55:56 2008
@@ -19,14 +19,15 @@
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY slice-version "VERSION">
-
- <!ENTITY introduction.xml SYSTEM "introduction.xml">
- <!ENTITY features.xml SYSTEM "features.xml">
- <!ENTITY architecture.xml SYSTEM "architecture.xml">
- <!ENTITY user_manual.xml SYSTEM "user_manual.xml">
- <!ENTITY download.xml SYSTEM "download.xml">
+
+ <!ENTITY introduction.xml SYSTEM "introduction.xml">
+ <!ENTITY features.xml SYSTEM "features.xml">
+ <!ENTITY architecture.xml SYSTEM "architecture.xml">
+ <!ENTITY user_manual.xml SYSTEM "user_manual.xml">
+ <!ENTITY download.xml SYSTEM "download.xml">
<!ENTITY release_notes.xml SYSTEM "release_notes.xml">
+ <!ENTITY project_data.xml SYSTEM "project_data.xml">
+ <!ENTITY homer SYSTEM "homer.xml">
]>
<book id="Slice">
@@ -36,9 +37,10 @@
&introduction.xml;
&features.xml;
&user_manual.xml;
- &architecture.xml;
+<!-- &architecture.xml; -->
&download.xml;
&release_notes.xml;
+ &project_data.xml;
</book>
Modified: labs/fluid/slice/src/doc/user_manual.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/user_manual.xml?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/doc/user_manual.xml (original)
+++ labs/fluid/slice/src/doc/user_manual.xml Fri Jan 4 20:55:56 2008
@@ -20,137 +20,130 @@
<chapter id="user_manual">
<title>User Manual</title>
<para>
- Slice is designed for ease of use and requires no change to your application
- or in the persistent entity model. A OpenJPA based application working against
- a single database can be upgraded to work against a set of databases by
- configuring a persistence unit in <code>META-INF/persistence.xml</code>.
+ Slice is designed for ease of use. The user application
+ or the persistent entity model requires no change. A OpenJPA based application
+ working against a single database can be upgraded to work against a set of
+ databases by configuring a persistence unit in <code>META-INF/persistence.xml</code>.
</para>
<section id="configuration">
<title>Configuration</title>
<para>
- Slice is activated via the following property settings:
+ Slice is activated via the following property settings:
</para>
<section>
<title>How to activate Slice Runtime?</title>
<para>
- The basic configuration property is
- <programlisting>
- <![CDATA[<property name="openjpa.BrokerFactory" value="slice"/>]]>
- </programlisting>
- This configuration activates a specialized factory class aliased
- as <code>slice</code> to create object management kernel that
- can work against multiple databases.
+ The basic configuration property is
+ <programlisting>
+ <![CDATA[ <property name="openjpa.BrokerFactory" value="slice"/>]]>
+ </programlisting>
+ This configuration activates a specialized factory class aliased
+ as <code>slice</code> to create object management kernel that
+ can work against multiple databases.
</para>
</section>
<section>
<title>How to configure each database slice?</title>
<para>
- The next configuration task is to specify each slice properties. Each
- slice in a configuration is assigned a logical name. For example, the
- following configuration will register two slices with logical name
- <code>One</code> and <code>Two</code>.
- <programlisting>
- <![CDATA[<property name="slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/>
+ The next task is to configuration each database slice. Each
+ slice is assigned a logical name. For example, the
+ following configuration will register two slices with logical name
+ <code>One</code> and <code>Two</code>.
+ <programlisting>
+ <![CDATA[<property name="slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/>
<property name="slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/>]]>
- </programlisting>
+ </programlisting>
</para>
<para>
- Any OpenJPA specific property can be configured per slice basis.
- For example, the following configuration will use two different JDBC
- drivers for slice <code>One</code> and
- <code>Two</code>.
- <programlisting>
- <![CDATA[<property name="slice.One.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
+ Any OpenJPA specific property can be configured per slice basis.
+ For example, the following configuration will use two different JDBC
+ drivers for slice <code>One</code> and <code>Two</code>.
+ <programlisting>
+ <![CDATA[<property name="slice.One.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
<property name="slice.Two.ConnectionDriverName" value="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"/>]]>
- </programlisting>
+ </programlisting>
</para>
<para>
Any property if unspecified for a particular slice will be defaulted by
- corresponding OpenJPA property. For example, consider three slices
+ corresponding OpenJPA property. For example, consider following three slices
<programlisting>
- <![CDATA[<property name="slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/>
- <property name="slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/>
- <property name="slice.Three.ConnectionURL" value="jdbc:oracle:localhost//slice3"/>
+ <![CDATA[<property name="slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/>
+ <property name="slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/>
+ <property name="slice.Three.ConnectionURL" value="jdbc:oracle:localhost//slice3"/>
- <property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
- <property name="slice.Three.ConnectionDriverName" value="oracle.jdbc.Driver"/>]]>
+ <property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
+ <property name="slice.Three.ConnectionDriverName" value="oracle.jdbc.Driver"/>]]>
</programlisting>
In this example, <code>Three</code> will use slice-specific
<code>oracle.jdbc.Driver</code> driver while slice
<code>One</code> and <code>Two</code> will use
- the driver specified by <code>openjpa.ConnectionDriverName</code>
+ the driver <code>com.mysql.jdbc.Driver</code> as
+ specified by <code>openjpa.ConnectionDriverName</code>
property value.
</para>
</section>
<section>
- <title>What is Distribution Policy?</title>
+ <title>Implement DistributionPolicy interface</title>
<para>
- Slice needs to determine which slice will persist a new instance.
- The application can only decide this policy (for example,
- all PurchaseOrders before April 30 goes to slice <code>One</code>,
- all the rest goes to slice <code>Two</code>). This is why
- the application has to implement
- <code>org.apache.openjpa.slice.DistributionPolicy</code> and
- specify the implementation class in configuration
- <programlisting>
- <![CDATA[<property name="slice.DistributionPolicy" value="com.acme.foo.MyOptimialDistributionPolicy"/>]]>
- </programlisting>
+ Slice needs to determine which slice will persist a new instance.
+ The application can only decide this policy (for example,
+ all PurchaseOrders before April 30 goes to slice <code>One</code>,
+ all the rest goes to slice <code>Two</code>). This is why
+ the application has to implement
+ <code>org.apache.openjpa.slice.DistributionPolicy</code> and
+ specify the implementation class in configuration
+ <programlisting>
+ <![CDATA[ <property name="slice.DistributionPolicy" value="com.acme.foo.MyOptimialDistributionPolicy"/>]]>
+ </programlisting>
</para>
- </section>
- </section>
- <section>
- <title>Implement DistributionPolicy interface</title>
- <para>
+ <para>
The interface <code>org.apache.openjpa.slice.DistributionPolicy</code>
- is simple with a single method
+ is simple with a single method. The complete listing of the
+ documented interface follows:
<programlisting>
- <![CDATA[String distribute(Object pc, Set<String> slices, Object context)]]>
-} </programlisting>
- The first argument <code>pc</code> is the newly persistent
- entity instance.
- The second argument is the list of configured slice names.
- The last argument is unused and kept for future use.
- The contract of this interface is to return one of the
- <code>slices</code> supplied as the second argument.
+ <![CDATA[
+public interface DistributionPolicy {
+ /**
+ * 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 context 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);
+}
+]]>
+ </programlisting>
</para>
- </section>
-
- <section id="distribution_policy">
- <title>Why Distribution Policy is required?</title>
- <para>
- 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.
- </para>
- </section>
-
- <section id="collocation_constraint">
- <title>Collocation Constraint</title>
- <para>
- 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.
-
- 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.
+
+ <para>
+ While implementing a distribution policy the most important thing to
+ remember is <link linkend="collocation_constraint">collocation constraint</link>.
+ Because Slice can not establish or query any cross-database relationship, all the
+ related instances must be stored in the same database slice.
- Slice can determine the closure of a root object by traversal of
- cascaded relationships. Hence user-defined policy has to only decide the
- database for the root instance that is the explicit argument of persist() call.
- Slice will ensure that all other instances that gets persisted by cascade
- is assigned to the same database as that of the root instance.
- </para>
+ Slice can determine the closure of a root object by traversal of
+ cascaded relationships. Hence user-defined policy has to only decide the
+ database for the root instance that is the explicit argument to
+ <code>EntityManager.persist()</code> call.
+ Slice will ensure that all other related instances that gets persisted by cascade
+ is assigned to the same database slice as that of the root instance.
+ However, the user-defined distribution policy must return the
+ same slice identifier for the instances that are logically related but
+ not cascaded for persist.
+ </para>
+ </section>
</section>
-
+ &homer;
</chapter>
Modified: labs/fluid/slice/src/site/resources/banner.html
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/resources/banner.html?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/site/resources/banner.html (original)
+++ labs/fluid/slice/src/site/resources/banner.html Fri Jan 4 20:55:56 2008
@@ -3,11 +3,11 @@
<link rel="stylesheet" href="css/docbook.css" type="text/css">
</head>
<body>
-<table width="100%" rules="none" frame="box" border="0">
+<table width="100%" rules="none" frame="void" border="0">
<tr>
<TD align="left" width="50"><img src="images/logo_slice.jpg" width="50" height="50" border="0"></TD>
-<TD align="left" width="100" valign="baseline"><h1> Slice</h1></TD>
-<TD align="center" width="*"><H1>Distributed Object Persistence</center></TD>
+<TD align="left" width="100" valign="bottom"><h1>Slice</h1></TD>
+<TD align="center" width="*"><H1>OpenJPA for Distributed Object Persistence</center></TD>
</tr>
</table>
</body>
Modified: labs/fluid/slice/src/site/resources/footer.html
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/resources/footer.html?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/site/resources/footer.html (original)
+++ labs/fluid/slice/src/site/resources/footer.html Fri Jan 4 20:55:56 2008
@@ -2,5 +2,8 @@
<head>
<link rel="stylesheet" href="css/docbook.css" type="text/css">
</head>
-<body>Blended Open Source: BEA Systems & Apache Labs</body>
+<body>
+<HR>
+<p align="left">Blended Open Source: BEA Systems & Apache Labs</p>
+</body>
</HTML>
Modified: labs/fluid/slice/src/site/resources/menu.html
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/resources/menu.html?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/site/resources/menu.html (original)
+++ labs/fluid/slice/src/site/resources/menu.html Fri Jan 4 20:55:56 2008
@@ -1,23 +1,19 @@
<HTML>
<head>
<link rel="stylesheet" href="css/docbook.css" type="text/css">
+<base target="main">
</head>
<body>
-<A HREF="welcome.html" target="main">Welcome</A> <br>
-<A HREF="slice.html" target="main">User Manual</A> <br>
- <A HREF="slice.pdf" target="main">PDF Version</A> <br>
- <A HREF="introduction.html" target="main">Browse</A> <br>
-<A HREF="download.html" target="main">Download 2</A> <br>
-<A HREF="faq.html" target="main">FAQ</A> <br>
-<hr>
-For Developers<br>
-<A HREF="apidocs/index.html" target="main">JavaDoc</A> <br>
-Project Details <br>
-<A HREF="team-list.html" target="main">Team</A> <br>
-<A HREF="mail-lists.html" target="main">Mailing Lists</A> <br>
-<A HREF="dependencies.html" target="main">Dependencies</A> <br>
-
-
+<A HREF="welcome.html">Home</A> <br>
+<A HREF="slice.html">User Manual</A> <br>
+ <A HREF="slice.pdf">PDF Version</A> <br>
+<A HREF="slice.html#download">Download</A> <br>
+<A HREF="apidocs/index.html">JavaDoc</A> <br>
+<A HREF="project-info.html">Project Information</A> <br>
+<br>
+<br>
+<br>
+<strong class="hightlight">version 0.4.0</strong>
</body>
</HTML>
Modified: labs/fluid/slice/src/site/resources/welcome.html
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/site/resources/welcome.html?rev=609091&r1=609090&r2=609091&view=diff
==============================================================================
--- labs/fluid/slice/src/site/resources/welcome.html (original)
+++ labs/fluid/slice/src/site/resources/welcome.html Fri Jan 4 20:55:56 2008
@@ -3,13 +3,9 @@
<link rel="stylesheet" href="css/docbook.css" type="text/css">
</head>
<body>
-Slice transacts on cloud.
-But Slice is simple and not cloudy at all.
-<img src="images/slice_small.png" align="left">Slice is a OpenJPA plug-in for
-your application to transact against horizontally-partitioned, possible
-heterogeneous set of distributed databases.
-Slice doe snot require any change to OpenJPA application and only requires
-configuration.
-Slice needs the user application to decide the distribution policy.
+<center>
+<img src="images/slice_overview.png" align="left"><h3>Slice extends OpenJPA runtime
+for distributed, possibly heterogeneous, horizontally partitioned databases.</h3>
+</center>
</body>
</HTML>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@labs.apache.org
For additional commands, e-mail: commits-help@labs.apache.org