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/03 07:38:35 UTC
svn commit: r608359 - in /labs/fluid/slice/src/doc: ./ css/ images/
Author: ppoddar
Date: Wed Jan 2 22:38:34 2008
New Revision: 608359
URL: http://svn.apache.org/viewvc?rev=608359&view=rev
Log:
doc changes
Added:
labs/fluid/slice/src/doc/
labs/fluid/slice/src/doc/architecture.xml
labs/fluid/slice/src/doc/css/
labs/fluid/slice/src/doc/css/docbook.css
labs/fluid/slice/src/doc/download.xml
labs/fluid/slice/src/doc/features.xml
labs/fluid/slice/src/doc/images/
labs/fluid/slice/src/doc/images/logo_slice.jpg (with props)
labs/fluid/slice/src/doc/images/logo_slice_text.jpg (with props)
labs/fluid/slice/src/doc/introduction.xml
labs/fluid/slice/src/doc/manual-pdf.xsl
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
Added: labs/fluid/slice/src/doc/architecture.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/architecture.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/architecture.xml (added)
+++ labs/fluid/slice/src/doc/architecture.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="architecture">
+ <title>How does Slice work?</title>
+ <section id="openjpa_architecture">
+ <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
+ processing they belong. The object management kernel does not assume any
+ specific nature of data storage system or user-level APIs.
+ </para>
+ </section>
+
+ <section id="openjpa_plugin_framework">
+ <title>OpenJPA Plug-in Framework</title>
+ <para>
+ Every major component of the architecture is pluggable.
+ </para>
+ </section>
+
+ <section id="design_goals">
+ <title>Design Goals</title>
+ <para>
+ Make minimal or no change to OpenJPA code.
+ </para>
+ <para>
+ Make it user-friendly
+ </para>
+ </section>
+
+ <section id="design_challenges">
+ <title>What is critical design?</title>
+ <para>
+ Must get in-memory instances from different slices within the same
+ persistence context.
+ </para>
+ <para>
+ Loaded instance must remember which slice it originated from.
+ </para>
+ </section>
+
+ <section id="distributed_transation">
+ <title>Distributed Transaction</title>
+ <para>
+ Who will manage the distributed transaction across the slices?
+ OpenJPA runtime behaves more like a Resource Manager in distributed
+ transaction i.e. it is a participant rather than a controller of transaction.
+ It depends on external Transaction Manager to manage global transaction.
+ </para>
+ </section>
+
+ <section id="distributed_template_pattern">
+ <title>Distributed Template Pattern</title>
+ </section>
+
+
+</chapter>
+
\ No newline at end of file
Added: labs/fluid/slice/src/doc/css/docbook.css
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/css/docbook.css?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/css/docbook.css (added)
+++ labs/fluid/slice/src/doc/css/docbook.css Wed Jan 2 22:38:34 2008
@@ -0,0 +1,244 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/* content styles */
+html {
+ background-color: white;
+ color: black;
+ font-family: Arial, Lucida Grande, sans-serif;
+ font-size: 0.85em;
+ line-height: 1.25em;
+}
+
+
+/* links */
+a:hover {color: #0044B3;}
+a {color: #597BB3;}
+a.nonexistent, a.badinterwiki {color: gray;}
+
+/* Headings */
+
+h1 a {
+ text-decoration: none;
+ color: black;
+}
+li p {
+ margin: .25em 0;
+}
+li.gap {
+ margin-top: 0.5em;
+}
+a, img, img.drawing {
+ border: 0;
+}
+dt {
+ font-weight: bold;
+}
+
+pre {
+ padding: 0.5em;
+ font-family: courier, monospace;
+ border: 1pt solid #c0c0c0;
+ margin-left: 1em;
+ background: #F0ECE6;
+ white-space: pre;
+ /* begin css 3 or browser specific rules - do not remove!
+ see: http://forums.techguy.org/archive/index.php/t-249849.html */
+ white-space: pre-wrap;
+ word-wrap: break-word;
+ white-space: -moz-pre-wrap;
+ white-space: -pre-wrap;
+ white-space: -o-pre-wrap;
+ /* end css 3 or browser specific rules */
+}
+
+table
+{
+ margin: 0.5em 0;
+ border-collapse: collapse;
+}
+
+td
+{
+ padding: 0.25em;
+ border: 1px solid #ADB9CC;
+}
+
+td p {
+ margin: 0;
+ padding: 0;
+}
+
+/* standard rule ---- */
+hr {
+ height: 1px;
+ background-color: #c0c0c0;
+ border: none;
+}
+
+/* custom rules ----- to ---------- */
+.hr1 {height: 2px;}
+.hr2 {height: 3px;}
+.hr3 {height: 4px;}
+.hr4 {height: 5px;}
+.hr5 {height: 6px;}
+.hr6 {height: 7px;}
+
+/* Replacement for html 3 u tag */
+.u {text-decoration: underline;}
+
+.footnotes ul {
+ padding: 0 2em;
+ margin: 0 0 1em;
+}
+
+.footnotes li {
+ list-style: none;
+}
+
+.info {
+ font-size: 0.85em;
+ color: gray;
+}
+
+#pageinfo {
+ margin-top: 2em;
+}
+
+/* eye catchers */
+.warning
+{
+ color: red;
+}
+
+.error
+{
+ color: red;
+}
+
+strong.highlight
+{
+ background-color: #CCE0FF;
+ padding: 1pt;
+}
+
+#credits img {
+ vertical-align: middle;
+}
+
+/* Recent changes */
+
+.recentchanges p {
+ margin: 0.25em;
+}
+
+.recentchanges td {
+ vertical-align: top;
+ border: none;
+ border-bottom: 1pt solid #F0ECE6;
+ background: #F7F6F2;
+}
+
+.rcdaybreak td {
+ background: #B8C5D9;
+ border: none;
+}
+
+.rcdaybreak td a {
+ font-size: 0.88em;
+}
+
+.rcicon1, .rcicon2 {
+ text-align: center;
+}
+
+.rcpagelink {
+ width: 33%;
+}
+
+.rctime {
+ font-size: 0.88em;
+ white-space: nowrap;
+}
+
+.rceditor {
+ white-space: nowrap;
+ font-size: 0.88em;
+}
+
+.rccomment {
+ width: 66%;
+ color: gray;
+ font-size: 0.88em;
+}
+
+.rcrss {
+ float: right;
+}
+
+.recentchanges[dir="rtl"] .rcrss {
+ float: left;
+}
+
+/* User Preferences */
+
+.userpref table, .userpref td {
+ border: none;
+}
+
+
+/* CSS for new code_area markup used by Colorizer and ParserBase */
+
+div.codearea { /* the div makes the border */
+ margin: 0.5em 0;
+ padding: 0;
+ border: 1pt solid #AEBDCC;
+ background-color: #F3F5F7;
+ color: black;
+}
+
+div.codearea pre { /* the pre has no border and is inside the div */
+ margin: 0;
+ padding: 10pt;
+ border: none;
+}
+
+a.codenumbers { /* format of the line numbering link */
+ margin: 0 10pt;
+ font-size: 0.85em;
+ color: gray;
+}
+
+/* format of certain syntax spans */
+div.codearea pre span.LineNumber {color: gray;}
+div.codearea pre span.ID {color: #000000;}
+div.codearea pre span.Operator {color: #0000C0;}
+div.codearea pre span.Char {color: #004080;}
+div.codearea pre span.Comment {color: #008000;}
+div.codearea pre span.Number {color: #0080C0;}
+div.codearea pre span.String {color: #004080;}
+div.codearea pre span.SPChar {color: #0000C0;}
+div.codearea pre span.ResWord {color: #A00000;}
+div.codearea pre span.ConsWord {color: #008080; font-weight: bold;}
+div.codearea pre span.Error {color: #FF8080; border: solid 1.5pt #FF0000;}
+div.codearea pre span.ResWord2 {color: #0080ff; font-weight: bold;}
+div.codearea pre span.Special {color: #0000ff;}
+div.codearea pre span.Preprc {color: #803999;}
+
+
Added: labs/fluid/slice/src/doc/download.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/download.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/download.xml (added)
+++ labs/fluid/slice/src/doc/download.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="download">
+ <title>Download Instruction</title>
+
+ <section id="download_jar">
+ <title>Get the Jar</title>
+ <para>
+ Slice is available as a single jar and can be downloaded from the following
+ location.
+ </para>
+
+ <table tocentry="1">
+ <tgroup rowsep="2" colsep="4" align="center" cols="3">
+ <colspec colname="version"/>
+ <colspec colname="download"/>
+ <colspec colname="note"/>
+ <thead>
+ <row>
+ <entry colname="version">Version</entry>
+ <entry colname="download">Download</entry>
+ <entry colname="note">Release Notes</entry>
+ </row>
+ </thead>
+ <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="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="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="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="note"><link linkend="release_notes_0.1.0">Release Note</link></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section id="download_source">
+ <title>Source Code Download</title>
+ <para>
+ Source code is maintained in Apache Subversion Repository.
+ The following command will fetch the repository content to
+ local machine, in <code>slice</code> subdirectory relative to the current
+ directory.
+ <programlisting>
+ svn co https://svn.apache.org/repos/asf/labs/fluid/slice slice
+ </programlisting>
+ </para>
+ </section>
+
+ <section id="download_build_source">
+ <title>Build from Source</title>
+ <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>.
+ <programlisting>
+ mvn package
+ </programlisting>
+ </para>
+
+ <note>
+ The test configuration <code>src/test/resources/META-INF/persistence.xml</code> currently
+ assume that two MySQL databases named
+ <code>slice1</code> and <code>slice2</code> are available in <code>localhost</code>.
+ </note>
+
+ <para>
+ To build the project without running the tests,
+ run the following command
+ <programlisting>
+ mvn package -Dtest=false
+ </programlisting>
+ </para>
+
+ </section>
+</chapter>
+
\ No newline at end of file
Added: labs/fluid/slice/src/doc/features.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/features.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/features.xml (added)
+++ labs/fluid/slice/src/doc/features.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="features_and_limitations">
+ <title>Features and Limitations</title>
+
+ <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.
+ </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.
+ </para>
+ </section>
+ <section><title>Custom 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.
+ </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
+ databases.
+ </para>
+ </section>
+ <section><title>Native XA support</title>
+ <para>
+ </para>
+ </section>
+ <section><title>Parallel Execution</title>
+ <para>
+ Query and Flush operations execute in each slice in parallel.
+ </para>
+ </section>
+ </section>
+
+ <section id="Limitations">
+ <title>Limitations</title>
+
+ <section><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.
+ </para>
+ </section>
+
+ <section><title>No Sorting</title>
+ <para>
+ no sorting of query result across multiple databases.
+ </para>
+ </section>
+
+ </section>
+</chapter>
+
\ No newline at end of file
Added: labs/fluid/slice/src/doc/images/logo_slice.jpg
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/images/logo_slice.jpg?rev=608359&view=auto
==============================================================================
Binary file - no diff available.
Propchange: labs/fluid/slice/src/doc/images/logo_slice.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: labs/fluid/slice/src/doc/images/logo_slice_text.jpg
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/images/logo_slice_text.jpg?rev=608359&view=auto
==============================================================================
Binary file - no diff available.
Propchange: labs/fluid/slice/src/doc/images/logo_slice_text.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: labs/fluid/slice/src/doc/introduction.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/introduction.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/introduction.xml (added)
+++ labs/fluid/slice/src/doc/introduction.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="introduction">
+ <title>Introduction</title>
+
+ <section id="introduction_what_is_slice">
+ <title>What is Slice?</title>
+ <para>
+ Slice extends OpenJPA for horizontally-partitioned, distributed database
+ environment.
+ </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
+ 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>
+ </section>
+
+
+
+ <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.
+ </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
+ 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.
+ </para>
+ </section>
+
+
+
+ <section id="introduction_purpose">
+ <title>Purpose of this Document</title>
+ <para>
+ This document describes how to use Slice to enable OpenJPA applications
+ for distributed database environment.
+ </para>
+ </section>
+
+ <section id="introduction_audience">
+ <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.
+ </para>
+ </section>
+</chapter>
+
\ No newline at end of file
Added: labs/fluid/slice/src/doc/manual-pdf.xsl
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/manual-pdf.xsl?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/manual-pdf.xsl (added)
+++ labs/fluid/slice/src/doc/manual-pdf.xsl Wed Jan 2 22:38:34 2008
@@ -0,0 +1,347 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version='1.0'>
+ <!-- used by docbkx-maven-plugin to reference the core styles -->
+ <xsl:import href="urn:docbkx:stylesheet"/>
+
+ <!-- no pictures in note/warn/caution pargs -->
+ <xsl:param name="admon.graphics" select="0" />
+ <xsl:param name="autotoc.label.separator" select="'. '"/>
+ <xsl:param name="toc.indent.width" select="24"/>
+
+ <!-- required for PDF bookmarks and some other stuff -->
+ <xsl:param name="fop.extensions" select="1"/>
+ <!-- <xsl:param name="use.extensions" select="1"/> -->
+
+ <xsl:param name="ulink.hyphenate" select="''"/>
+
+ <!-- don't show link source -->
+ <xsl:param name="ulink.show" select="0"/>
+
+
+ <!-- <xsl:param name="ulink.footnotes" select="1"/> -->
+ <!-- <xsl:param name="ulink.hyphenate" select="1"/> -->
+
+ <!-- don't ever hyphenate words -->
+ <!-- <xsl:param name="hyphenate">false</xsl:param> -->
+
+ <!-- left justify -->
+ <xsl:param name="alignment">left</xsl:param>
+
+ <!-- print page numbers in references -->
+ <xsl:param name="insert.xref.page.number" select="1"/>
+
+ <!-- make all cross-refernce links appear in bold and dark blue -->
+ <xsl:attribute-set name="xref.properties">
+ <!-- <xsl:attribute name="color">#AFAFAF</xsl:attribute> -->
+ <xsl:attribute name="color">#17184A</xsl:attribute>
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+ </xsl:attribute-set>
+
+
+ <!-- page break before level1 sections -->
+ <!--xsl:attribute-set name="section.level1.properties">
+ <xsl:attribute name="break-before">page</xsl:attribute>
+ </xsl:attribute-set-->
+
+ <!-- Chapters: white font on light blue backgrouns -->
+ <xsl:attribute-set name="title.properties">
+ <xsl:attribute name="color">#000000</xsl:attribute>
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+ <xsl:attribute name="background-color">#3366CC</xsl:attribute>
+ </xsl:attribute-set>
+
+
+ <!-- Section title: underline -->
+ <xsl:attribute-set name="section.title.properties">
+ <!-- <xsl:attribute name="color">#005BA6</xsl:attribute> -->
+
+ <!-- simulate underline with border of 1px bottom -->
+ <xsl:attribute name="border-bottom-width">1px</xsl:attribute>
+ <xsl:attribute name="border-top-width">0px</xsl:attribute>
+ <xsl:attribute name="border-left-width">0px</xsl:attribute>
+ <xsl:attribute name="border-right-width">0px</xsl:attribute>
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-width">1px</xsl:attribute>
+ <xsl:attribute name="border-color">#17184A</xsl:attribute>
+ </xsl:attribute-set>
+
+
+ <!-- Examples and other fomal sections: italic -->
+ <xsl:attribute-set name="formal.title.properties">
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 1.2"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+
+ <xsl:attribute name="font-style">italic</xsl:attribute>
+ </xsl:attribute-set>
+
+
+ <xsl:param name="segmentedlist.as.table" select="1"/>
+ <xsl:param name="variablelist.as.blocks" select="1"/>
+
+ <xsl:param name="html.stylesheet">documentation.css</xsl:param>
+ <xsl:param name="annotate.toc" select="1"/>
+ <xsl:param name="toc.section.depth" select="8"/>
+ <xsl:param name="generate.section.toc.level" select="8"/>
+ <xsl:param name="generate.index" select="1"/>
+ <xsl:param name="chapter.autolabel" select="1"/>
+ <xsl:param name="appendix.autolabel" select="1"/>
+ <xsl:param name="part.autolabel" select="1"/>
+ <xsl:param name="preface.autolabel" select="1"/>
+ <xsl:param name="qandadiv.autolabel" select="1"/>
+ <xsl:param name="section.autolabel" select="1"/>
+ <xsl:param name="section.label.includes.component.label" select="1"/>
+ <xsl:param name="label.from.part" select="1"/>
+
+ <xsl:param name="generate.toc">
+ /appendix toc
+ article toc
+ book toc,figure,table,example,equation
+ /chapter toc
+ part toc
+ /preface toc
+ qandadiv toc
+ qandaset toc
+ reference toc
+ /section toc
+ set toc
+ </xsl:param>
+
+
+ <!-- small margins for the PDF -->
+ <xsl:param name="page.margin.inner">0.3in</xsl:param>
+ <xsl:param name="page.margin.outer">0.3in</xsl:param>
+
+
+ <!-- without this, some parts of the body seem to overrin the -->
+ <!-- page number part of the footer -->
+ <xsl:param name="body.margin.bottom">0.88in</xsl:param>
+ <xsl:param name="page.margin.bottom">0.01in</xsl:param>
+
+ <!-- make source code listings be boxed and have a grey background -->
+ <xsl:attribute-set name="monospace.verbatim.properties"
+ use-attribute-sets="verbatim.properties">
+ <xsl:attribute name="font-family">
+ <xsl:value-of select="$monospace.font.family"/>
+ </xsl:attribute>
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 0.7"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+
+ <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
+ <xsl:attribute name="border-color">#000000</xsl:attribute>
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-width">1px</xsl:attribute>
+ <xsl:attribute name="padding-top">0.5cm</xsl:attribute>
+ <xsl:attribute name="padding-bottom">0.5cm</xsl:attribute>
+ <xsl:attribute name="padding-left">0.5cm</xsl:attribute>
+ <xsl:attribute name="padding-right">0.5cm</xsl:attribute>
+ </xsl:attribute-set>
+
+
+ <!-- admonition (note/warn/caution) title properties: italics, -->
+ <!-- with a blue background and white text -->
+ <xsl:attribute-set name="admonition.title.properties">
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 1.5"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+
+ <xsl:attribute name="font-style">bold</xsl:attribute>
+ <xsl:attribute name="text-align">center</xsl:attribute>
+
+ <xsl:attribute name="color">#FFFFFF</xsl:attribute>
+ <xsl:attribute name="background-color">#17184A</xsl:attribute>
+
+ <xsl:attribute name="border-color">#000000</xsl:attribute>
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-width">0px</xsl:attribute>
+ <xsl:attribute name="padding-left">0.2cm</xsl:attribute>
+ <xsl:attribute name="padding-right">0.2cm</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- admonition (note/warn/caution) properties: gray background -->
+ <xsl:attribute-set name="admonition.properties">
+ <xsl:attribute name="background-color">#B0B3B2</xsl:attribute>
+ <xsl:attribute name="border-color">#000000</xsl:attribute>
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-width">0px</xsl:attribute>
+ <xsl:attribute name="padding-top">0.2cm</xsl:attribute>
+ <xsl:attribute name="padding-bottom">0.2cm</xsl:attribute>
+ <xsl:attribute name="padding-left">0.2cm</xsl:attribute>
+ <xsl:attribute name="padding-right">0.2cm</xsl:attribute>
+ </xsl:attribute-set>
+
+ <xsl:attribute-set name="book.titlepage.recto.style">
+ <xsl:attribute name="font-size">18px</xsl:attribute>
+ <xsl:attribute name="text-align">center</xsl:attribute>
+ <xsl:attribute name="padding-top">3cm</xsl:attribute>
+ </xsl:attribute-set>
+
+
+
+ <!-- patches and fixes for stylesheet bugs -->
+
+
+ <!--
+ fix for duplicate ids generated by <qandaset> attributes
+ overrides docbook-xsl/fo/qandaset.xsl
+
+ See: http://lists.oasis-open.org/archives/docbook/200309/msg00070.html
+ -->
+<xsl:template match="question">
+ <xsl:variable name="id"><xsl:call-template name="object.id"/></xsl:variable>
+
+ <xsl:variable name="entry.id">
+ <xsl:call-template name="object.id">
+ <xsl:with-param name="object" select="parent::*"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <xsl:variable name="deflabel">
+ <xsl:choose>
+ <xsl:when test="ancestor-or-self::*[@defaultlabel]">
+ <xsl:value-of select="(ancestor-or-self::*[@defaultlabel])[last()]
+ /@defaultlabel"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$qanda.defaultlabel"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <fo:list-item id="{$entry.id}" xsl:use-attribute-sets="list.item.spacing">
+ <!--
+ This adds duplicate id attributes for some reason
+ See: http://lists.oasis-open.org/archives/docbook/200309/msg00070.html
+ <fo:list-item-label id="{$id}" end-indent="label-end()">
+ -->
+ <fo:list-item-label end-indent="label-end()">
+ <xsl:choose>
+ <xsl:when test="$deflabel = 'none'">
+ <fo:block/>
+ </xsl:when>
+ <xsl:otherwise>
+ <fo:block>
+ <xsl:apply-templates select="." mode="label.markup"/>
+ <xsl:if test="$deflabel = 'number' and not(label)">
+ <xsl:apply-templates select="." mode="intralabel.punctuation"/>
+ </xsl:if>
+ </fo:block>
+ </xsl:otherwise>
+ </xsl:choose>
+ </fo:list-item-label>
+ <fo:list-item-body start-indent="body-start()">
+ <xsl:choose>
+ <xsl:when test="$deflabel = 'none'">
+ <fo:block font-weight="bold">
+ <xsl:apply-templates select="*[local-name(.)!='label']"/>
+ </fo:block>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:apply-templates select="*[local-name(.)!='label']"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </fo:list-item-body>
+ </fo:list-item>
+</xsl:template>
+
+
+<xsl:template match="answer">
+ <xsl:variable name="id"><xsl:call-template name="object.id"/></xsl:variable>
+ <xsl:variable name="entry.id">
+ <xsl:call-template name="object.id">
+ <xsl:with-param name="object" select="parent::*"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <xsl:variable name="deflabel">
+ <xsl:choose>
+ <xsl:when test="ancestor-or-self::*[@defaultlabel]">
+ <xsl:value-of select="(ancestor-or-self::*[@defaultlabel])[last()]
+ /@defaultlabel"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$qanda.defaultlabel"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <fo:list-item xsl:use-attribute-sets="list.item.spacing">
+ <!--
+ This adds duplicate id attributes for some reason
+ See: http://lists.oasis-open.org/archives/docbook/200309/msg00070.html
+ <fo:list-item-label id="{$id}" end-indent="label-end()">
+ -->
+ <fo:list-item-label end-indent="label-end()">
+ <xsl:choose>
+ <xsl:when test="$deflabel = 'none'">
+ <fo:block/>
+ </xsl:when>
+ <xsl:otherwise>
+ <fo:block>
+ <xsl:variable name="answer.label">
+ <xsl:apply-templates select="." mode="label.markup"/>
+ </xsl:variable>
+ <xsl:copy-of select="$answer.label"/>
+ </fo:block>
+ </xsl:otherwise>
+ </xsl:choose>
+ </fo:list-item-label>
+ <fo:list-item-body start-indent="body-start()">
+ <xsl:apply-templates select="*[local-name(.)!='label']"/>
+ </fo:list-item-body>
+ </fo:list-item>
+</xsl:template>
+
+
+<!-- the default stylesheets move the alphabet letter out of the fo
+ block. this fixes that. -->
+<xsl:template name="indexdiv.title">
+ <xsl:param name="title"/>
+ <xsl:param name="titlecontent"/>
+
+ <fo:block
+ font-size="14.4pt"
+ font-family="{$title.fontset}"
+ font-weight="bold"
+ keep-with-next.within-column="always"
+ space-before.optimum="{$body.font.master}pt"
+ space-before.minimum="{$body.font.master * 0.8}pt"
+ space-before.maximum="{$body.font.master * 1.2}pt">
+ <xsl:choose>
+ <xsl:when test="$title">
+ <xsl:apply-templates select="." mode="object.title.markup">
+ <xsl:with-param name="allow-anchors" select="1"/>
+ </xsl:apply-templates>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:copy-of select="$titlecontent"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </fo:block>
+</xsl:template>
+
+</xsl:stylesheet>
+
Added: 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=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl (added)
+++ labs/fluid/slice/src/doc/manual-xhtml-chunk.xsl Wed Jan 2 22:38:34 2008
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+ <!-- docbook stylesheet customizations for openjpa manual -->
+ <!-- <xsl:import href="http://docbook.sourceforge.net/release/xsl/docbook-xsl-1.67.2/html/chunk.xsl"/> -->
+ <!-- locally downloaded cache of stylesheets -->
+ <!-- <xsl:import href="../../../target/stylesheets/docbook-xsl-1.67.2/html/chunk.xsl"/> -->
+
+ <!-- used by docbkx-maven-plugin to reference the core styles -->
+ <xsl:import href="urn:docbkx:stylesheet"/>
+
+ <xsl:param name="html.stylesheet">css/docbook.css</xsl:param>
+
+ <xsl:param name="html.cleanup" select="1"/>
+ <xsl:param name="label.from.part" select="1"/>
+ <xsl:param name="annotate.toc" select="1"/>
+ <xsl:param name="toc.section.depth">5</xsl:param>
+ <xsl:param name="generate.section.toc.level" select="8"/>
+ <xsl:param name="generate.id.attributes" select="1"/>
+ <xsl:param name="generate.index" select="1"/>
+ <xsl:param name="chapter.autolabel" select="1"/>
+ <xsl:param name="appendix.autolabel" select="1"/>
+ <xsl:param name="part.autolabel" select="1"/>
+ <xsl:param name="preface.autolabel" select="0"/>
+ <xsl:param name="qandadiv.autolabel" select="1"/>
+ <xsl:param name="section.autolabel" select="1"/>
+
+ <xsl:param name="use.id.as.filename" select="'1'"/>
+ <xsl:template name="process.image.attributes"/>
+</xsl:stylesheet>
+
Added: labs/fluid/slice/src/doc/manual-xhtml.xsl
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/manual-xhtml.xsl?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/manual-xhtml.xsl (added)
+++ labs/fluid/slice/src/doc/manual-xhtml.xsl Wed Jan 2 22:38:34 2008
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+ <!-- docbook stylesheet customizations for openjpa manual -->
+ <!-- <xsl:import href="http://docbook.sourceforge.net/release/xsl/docbook-xsl-1.67.2/html/docbook.xsl"/> -->
+ <!-- locally downloaded cache of stylesheets -->
+ <!-- <xsl:import href="../../../target/stylesheets/docbook-xsl-1.67.2/html/docbook.xsl"/> -->
+
+ <!-- used by docbkx-maven-plugin to reference the core styles -->
+ <xsl:import href="urn:docbkx:stylesheet"/>
+
+ <xsl:param name="html.stylesheet">css/docbook.css</xsl:param>
+
+<xsl:param name="generate.toc">
+appendix toc,title
+article/appendix nop
+article toc,title
+book toc,title,figure,example,equation
+chapter title
+part toc,title
+preface toc,title
+qandadiv toc
+qandaset toc
+reference toc,title
+sect1 toc
+sect2 toc
+sect3 toc
+sect4 toc
+sect5 toc
+section nop
+set toc,title
+</xsl:param>
+
+ <xsl:param name="html.cleanup" select="1"/>
+ <xsl:param name="label.from.part" select="1"/>
+ <xsl:param name="annotate.toc" select="1"/>
+ <xsl:param name="generate.chapter.toc" select="0"/>
+ <xsl:param name="toc.section.depth">5</xsl:param>
+ <xsl:param name="generate.section.toc.level" select="8"/>
+ <xsl:param name="generate.id.attributes" select="1"/>
+ <xsl:param name="generate.index" select="1"/>
+ <xsl:param name="chapter.autolabel" select="1"/>
+ <xsl:param name="appendix.autolabel" select="1"/>
+ <xsl:param name="part.autolabel" select="1"/>
+ <xsl:param name="preface.autolabel" select="0"/>
+ <xsl:param name="qandadiv.autolabel" select="1"/>
+ <xsl:param name="section.autolabel" select="1"/>
+ <xsl:template name="process.image.attributes"/>
+ <xsl:param name="section.label.includes.component.label" select="1"></xsl:param>
+</xsl:stylesheet>
+
Added: labs/fluid/slice/src/doc/release_notes.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/release_notes.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/release_notes.xml (added)
+++ labs/fluid/slice/src/doc/release_notes.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="release_notes">
+ <title>Release Notes</title>
+
+ <section id="release_notes_0.4.0">
+ <title>Version 0.4.0</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ First working version for extending OpenJPA to horizontally-partitioned,
+ distributed database.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="release_notes_0.3.0">
+ <title>Version 0.3.0</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ Automatic Collocation Constraint : Identifies the correct
+ slice for instances that are newly persistent by cascade. Collocation
+ constraint requires that the closure of any object graph be stored in the
+ same slice. In earlier version, user-defined DistributionPolicy has to
+ ensure this constraint by returning the same slice for all the instances
+ in the same closure.
+ Now DistributionPolicy only needs to be implemented for root instances i.e.
+ the instances that are explicit argument of persist()
+ call. The cascaded instances will be automatically assigned the same slice
+ identifier of the root instance.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="release_notes_0.2.0">
+ <title>Version 0.2.0</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ Per-slice Configuration: Now each slice can be configured with separate
+ database driver or database dictionary or any other property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The previous multi-URL configuration is no more supported.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="release_notes_0.1.0">
+ <title>Version 0.1.0</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ First working version for extending OpenJPA to horizontally-partitioned,
+ distributed database.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+</chapter>
+
\ No newline at end of file
Added: labs/fluid/slice/src/doc/slice.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/slice.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/slice.xml (added)
+++ labs/fluid/slice/src/doc/slice.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<!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 release_notes.xml SYSTEM "release_notes.xml">
+]>
+
+<book id="Slice">
+ <bookinfo>
+ <title>Slice Documentation</title>
+ </bookinfo>
+ &introduction.xml;
+ &features.xml;
+ &user_manual.xml;
+ &architecture.xml;
+ &download.xml;
+ &release_notes.xml;
+</book>
+
+
\ No newline at end of file
Added: labs/fluid/slice/src/doc/user_manual.xml
URL: http://svn.apache.org/viewvc/labs/fluid/slice/src/doc/user_manual.xml?rev=608359&view=auto
==============================================================================
--- labs/fluid/slice/src/doc/user_manual.xml (added)
+++ labs/fluid/slice/src/doc/user_manual.xml Wed Jan 2 22:38:34 2008
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<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>.
+ </para>
+
+ <section id="configuration">
+ <title>Configuration</title>
+ <para>
+ 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.
+ </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"/>
+ <property name="slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/>]]>
+ </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"/>
+ <property name="slice.Two.ConnectionDriverName" value="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"/>]]>
+ </programlisting>
+ </para>
+
+ <para>
+ Any property if unspecified for a particular slice will be defaulted by
+ corresponding OpenJPA property. For example, consider 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"/>
+
+ <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>
+ property value.
+ </para>
+ </section>
+
+ <section>
+ <title>What is Distribution Policy?</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>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Implement DistributionPolicy interface</title>
+ <para>
+ The interface <code>org.apache.openjpa.slice.DistributionPolicy</code>
+ is simple with a single method
+ <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.
+ </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.
+
+ 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>
+ </section>
+
+</chapter>
+
\ 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