Menu
▾
▴
[Jpox-commits] SF.net SVN: jpox: [2417] documentation/user.platform/trunk
|
From: <and...@us...> - 2008-04-19 19:34:15
|
Revision: 2417
http://jpox.svn.sourceforge.net/jpox/?rev=2417&view=rev
Author: andy_jefferson
Date: 2008-04-19 12:34:10 -0700 (Sat, 19 Apr 2008)
Log Message:
-----------
MIssing 1.2 doc
Modified Paths:
--------------
documentation/user.platform/trunk/1_2/jdo/metadata.xml
documentation/user.platform/trunk/navigation.xml
Added Paths:
-----------
documentation/user.platform/trunk/1_2/jdo/sequences.xml
Modified: documentation/user.platform/trunk/1_2/jdo/metadata.xml
===================================================================
--- documentation/user.platform/trunk/1_2/jdo/metadata.xml 2008-04-19 18:37:44 UTC (rev 2416)
+++ documentation/user.platform/trunk/1_2/jdo/metadata.xml 2008-04-19 19:34:10 UTC (rev 2417)
@@ -2370,7 +2370,7 @@
<tr>
<td>factory-class</td>
<td>Factory class for creating the sequence. Please refer to the
- <a href="datastore_sequences.html">Sequence guide</a></td>
+ <a href="sequences.html">Sequence guide</a></td>
<td/>
</tr>
<tr>
Added: documentation/user.platform/trunk/1_2/jdo/sequences.xml
===================================================================
--- documentation/user.platform/trunk/1_2/jdo/sequences.xml (rev 0)
+++ documentation/user.platform/trunk/1_2/jdo/sequences.xml 2008-04-19 19:34:10 UTC (rev 2417)
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document>
+ <properties>
+ <title>JDO Datastore Sequences</title>
+ <jpoxpagetype>Persistence</jpoxpagetype>
+ <jpoxversion>1_2</jpoxversion>
+ </properties>
+
+ <body>
+ <section name="JDO Datastore Sequences">
+ <img src="../images/jdo2.gif"/>
+ <p>
+ Particularly when specifying the identity of an object, sequences are a very useful facility.
+ JPOX supports the <a href="identity_generation.html">automatic assignment of sequence values for
+ object identities</a>. However such sequences may also have use when a user wishes to assign such
+ identity values themselves, or for other roles within an application. JDO 2 defines an interface
+ for sequences for use in an application - known as <B>Sequence</B>.
+ <a href="http://db.apache.org/jdo/api20/apidocs/javax/jdo/datastore/Sequence.html" target="_blank"><IMG SRC="../images/javadoc.gif"/></a>.
+ There are 2 forms of "sequence" available through this interface - the ones that JPOX provides
+ utilising datastore capabilities, and ones that a user provides using something known as a
+ "factory class".
+ </p>
+ <br/>
+ <subsection name="JPOX Sequences">
+ <p>
+ JPOX internally provides 2 forms of sequences. When the underlying datastore supports native
+ sequences, then these can be leveraged through this interface. Alternatively, where the
+ underlying datastore doesn't support native sequences, then a table-based incrementing sequence
+ can be used. The first thing to do is to specify the <B>Sequence</B> in the Meta-Data for the
+ package requiring the sequence. This is done as follows
+ </p>
+ <source><![CDATA[
+<jdo>
+ <package name="MyPackage">
+ <class name="MyClass">
+ ...
+ </class>
+
+ <sequence name="ProductSequence" datastore-sequence="PRODUCT_SEQ" strategy="contiguous"/>
+ <sequence name="ProductSequenceNontrans" datastore-sequence="PRODUCT_SEQ_NONTRANS" strategy="nontransactional"/>
+ </package>
+</jdo>]]></source>
+ <p>
+ So we have defined two <B>Sequences</B> for the package <I>MyPackage</I>. Each sequence has a
+ symbolic name that is referred to within JDO (within JPOX), and it has a name in the datastore.
+ The final attribute represents whether the sequence is transactional or not.
+ </p>
+ <p>
+ All we need to do now is to access the <B>Sequence</B> in our persistence code in our application. This is done as follows
+ </p>
+ <source><![CDATA[
+PersistenceManager pm = pmf.getPersistenceManager();
+
+Sequence seq = pm.getSequence("MyPackage.ProductSequence");
+]]></source>
+ <p>
+ and this <B>Sequence</B> can then be used to provide values.
+ </p>
+ <source>long value = seq.nextValue();</source>
+ <p>
+ Please be aware that when you have a <B>Sequence</B> declared with a strategy of "contiguous"
+ this means "transactional contiguous" and that you need to have a Transaction open when you
+ access it.
+ </p>
+ <p>
+ A JPOX extension to this capability allows the user some control over the underlying datastore
+ sequence being used. This is specified using <extension>. The underlying sequences used
+ by JPOX here are the "SequenceTablePoidGenerator" and "SequenceTableGenerator" as described in
+ the <a href="identity_generation.html">Identity Generation guide</a>. So we can do
+ </p>
+ <source><![CDATA[
+ <sequence name="ProductSequence" datastore-sequence="PRODUCT_SEQ" strategy="contiguous">
+ <extension vendor-name="jpox" key="key-cache-size" value="10"/>
+ </sequence>]]></source>
+ <p>
+ which will allocate 10 new sequence values each time the allocated sequence values is exhausted.
+ </p>
+ <br/>
+ </subsection>
+
+ <subsection name="Factory Class Sequences">
+ <p>
+ It is equally possible to provide your own <B>Sequence</B> capability using a
+ <I>factory class</I>. This is a class that creates an implementation of the JDO <B>Sequence</B>.
+ Let's give an example of what you need to provide. Firstly you need an implementation of the
+ JDO <B>Sequence</B> interface, so we define ours like this
+ </p>
+ <source><![CDATA[
+public class SimpleSequence implements Sequence
+{
+ String name;
+ long current = 0;
+
+ public SimpleSequence(String name)
+ {
+ this.name = name;
+ }
+
+ public String getName()
+ {
+ return name;
+ }
+
+ public Object next()
+ {
+ current++;
+ return new Long(current);
+ }
+
+ public long nextValue()
+ {
+ current++;
+ return current;
+ }
+
+ public void allocate(int arg0)
+ {
+ }
+
+ public Object current()
+ {
+ return new Long(current);
+ }
+
+ public long currentValue()
+ {
+ return current;
+ }
+}]]></source>
+ <p>
+ So our sequence simply increments by 1 each call to <I>next()</I>. The next thing we need to
+ do is provide a <I>factory class</I> that creates this <B>Sequence</B>. This factory needs to
+ have a static <I>newInstance</I> method that returns the <B>Sequence</B> object. We define our
+ factory like this
+ </p>
+ <source><![CDATA[
+package org.jpox.samples.sequence;
+
+import javax.jdo.datastore.Sequence;
+
+public class SimpleSequenceFactory
+{
+ public static Sequence newInstance()
+ {
+ return new SimpleSequence("MySequence");
+ }
+}]]></source>
+ <p>
+ and now we define our MetaData like this
+ </p>
+ <source><![CDATA[
+<jdo>
+ <package name="MyPackage">
+ <class name="MyClass">
+ ...
+ </class>
+
+ <sequence name="ProductSequenceFactory" strategy="nontransactional"
+ factory-class="org.jpox.samples.sequence.SimpleSequenceFactory"/>
+ </package>
+</jdo>]]></source>
+ <p>
+ So now we can call
+ </p>
+ <source><![CDATA[
+PersistenceManager pm = pmf.getPersistenceManager();
+
+Sequence seq = pm.getSequence("MyPackage.ProductSequenceFactory");
+]]></source>
+ <br/>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified: documentation/user.platform/trunk/navigation.xml
===================================================================
--- documentation/user.platform/trunk/navigation.xml 2008-04-19 18:37:44 UTC (rev 2416)
+++ documentation/user.platform/trunk/navigation.xml 2008-04-19 19:34:10 UTC (rev 2417)
@@ -194,6 +194,7 @@
<item name="Nondurable Identity" href="/1_2/nondurable_identity.html"/>
<item name="Identity Generation" href="/1_2/identity_generation.html"/>
<item name="Primary Keys" href="/1_2/primary_key.html"/>
+ <item name="Datastore Sequences" href="/1_2/jdo/sequences.html"/>
</menu>
<menu jpoxmenutype="JDO ORM" jpoxversion="1_2" name="O/R Mapping">
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|