db-jdo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From an...@apache.org
Subject svn commit: r1432659 [9/12] - in /db/jdo/site: ./ src/ src/site/ src/site/resources/ src/site/resources/images/ src/site/resources/releases/ src/site/xdoc/ src/site/xdoc/guides/ src/site/xdoc/releases/
Date Sun, 13 Jan 2013 17:05:18 GMT
Added: db/jdo/site/src/site/xdoc/jdo_3_0_overview.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdo_3_0_overview.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdo_3_0_overview.xml (added)
+++ db/jdo/site/src/site/xdoc/jdo_3_0_overview.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,192 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDO 3.0 Overview</title>
+    </properties>
+
+    <body>
+        <section name="JDO 3.0 Overview">
+            <subsection name="Background">
+                <p>
+                    Java Data Objects (JDO) is a specification begun in 2000, with 2 major releases
+                    JDO1 (2002 under JSR0012) and JDO2 (2006 under JSR0243). It was placed under 
+                    Apache in 2005 and is the rare example of a specification that has undergone
+                    continual improvement during its lifetime, for the last 4 years being developed
+                    totally in the open, accepting input from everyone.
+                </p>
+                <p>
+                    JDO 3.0 was started in October 2008, and encompasses additions to the specification
+                    in the areas of a metadata API, an enhancer API, addition of cancel/timeout control
+                    to queries, and addition of control to the locking of objects when read.
+                </p>
+            </subsection>
+
+            <subsection name="Metadata API">
+                <p>
+                    To persist Java objects you need to specify which classes are persistable, and
+                    how they are persisted. This was traditionally handled using XML configuration. With
+                    the advent of JDK1.5, annotations were added as another possible way of defining such
+                    information. JDO 3.0 takes this further and provides a <b>Metadata API</b>, allowing
+                    runtime definition. This is of particular use for systems that don't know at application
+                    startup which classes should be persistable, maybe because the class hasn't been
+                    written yet.
+                </p>
+                <p>
+                    To demonstrate the Metadata API, lets assume that we have a PersistenceManagerFactory
+                    created for our datastore. So we request a new Metadata object.
+                </p>
+                <source><![CDATA[
+PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(props);
+JDOMetaData jdomd = pmf.newMetadata();]]></source>
+                <p>
+                    So we can now start defining the metadata for the package/class(es) we want to persist.
+                    The Metadata is structured in a similar way to the XML DTD/XSD. So let's add a class
+                </p>
+                <source><![CDATA[
+ClassMetadata cmd = jdomd.newClassMetadata("test.Client");
+cmd.setTable("CLIENT").setDetachable(true).setIdentityType(javax.jdo.annotations.IdentityType.DATASTORE);
+cmd.setPersistenceModifier(javax.jdo.metadata.ClassPersistenceModifier.PERSISTENCE_CAPABLE);]]></source>
+                <p>
+                    So we have a class <i>test.Client</i> using datastore-identity, that is detachable, 
+                    and is persisted to a table <i>CLIENT</i>. As you can see, you can chain setters
+                    for convenient coding.
+                </p>
+                <source><![CDATA[
+InheritanceMetadata inhmd = cmd.newInheritanceMetadata();
+inhmd.setStrategy(javax.jdo.annotations.InheritanceStrategy.NEW_TABLE);
+DiscriminatorMetadata dmd = inhmd.newDiscriminatorMetadata();
+dmd.setColumn("disc").setValue("Client").setStrategy(javax.jdo.annotations.DiscriminatorStrategy.VALUE_MAP);
+dmd.setIndexed(Indexed.TRUE);
+
+VersionMetadata vermd = cmd.newVersionMetadata();
+vermd.setStrategy(javax.jdo.annotations.VersionStrategy.VERSION_NUMBER).setColumn("version");
+vermd.setIndexed(Indexed.TRUE);]]></source>
+                <p>
+                    So we will use "new-table" inheritance for this class, and it will have a discriminator
+                    stored in column <i>disc</i> of type "value-map". The class will also be versioned, using
+                    column <i>version</i>, that is indexed. All of this was for the class as a whole, so let's
+                    look at the fields/properties of the class.
+                </p>
+                <source><![CDATA[
+FieldMetadata fmd = cmd.newFieldMetadata("name");
+fmd.setNullValue(javax.jdo.annotations.NullValue.DEFAULT).setColumn("name").setIndexed(true).setUnique(true);
+]]></source>
+                <p>
+                    So we have a field <i>name</i> that is persisted into column <i>name</i>, and is unique
+                    and indexed. The API metadata components all follow the DTD as stated earlier, so if
+                    our field was a collection we could then define <i>CollectionMetadata</i> below it.
+                </p>
+                <p>
+                    The only thing left to do is register the metadata with the PersistenceManagerFactory,
+                    like this
+                </p>
+                <source><![CDATA[
+pmf.registerMetadata(jdomd);]]></source>
+                <p>
+                    and any contact with the class will now persist according to this API.
+                </p>
+                <p>
+                    You can similarly browse already registered metadata using
+                </p>
+                <source><![CDATA[
+ComponentMetadata compmd = pmf.getMetadata("mydomain.MyClass");]]></source>
+                <p>
+                    Note that you cannot change already registered metadata with JDO 3.0.
+                </p>
+                <p>
+                    You can view the Javadocs for the Metadata API
+                    <a href="http://db.apache.org/jdo/api30/apidocs/javax/jdo/metadata/package-summary.html">here</a>.
+                </p>
+            </subsection>
+
+            <subsection name="Enhancer API">
+                <p>
+                    JDO implementations typically (but aren't compelled to) include a bytecode enhancement
+                    step, allowing for efficient change detection of objects.
+                    While the Metadata API above is very useful, if we just define metadata for a class
+                    we still need to enhance the class using this metadata. This is where the 
+                    <b>Enhancer API</b> comes in. To start we need to get a JDOEnhancer
+                </p>
+                <source><![CDATA[
+JDOEnhancer enhancer = JDOHelper.getEnhancer();]]></source>
+                <p>
+                    and now that we have the enhancer and want to enhance our class above so we
+                    need to register our new metadata with it (generate the metadata as shown above)
+                </p>
+                <source><![CDATA[
+enhancer.registerMetadata(jdomd);]]></source>
+                <p>
+                    Now we can handle the enhancement using a separate class loader if required (for
+                    example if the classes were defined dynamically, e.g by ASM)
+                </p>
+                <source><![CDATA[
+enhancer.setClassLoader(myClassLoader);]]></source>
+                <p>
+                    Finally we select what to enhance, and perform the enhancement
+                </p>
+                <source><![CDATA[
+String[] classes = {"test.Client"};
+enhancer.addClasses(classes);
+enhancer.enhance();]]></source>
+                <p>
+                    So the class is now enhanced and is ready for use.
+                </p>
+                <p>
+                    You can view the Javadocs for the Enhancer API
+                    <a href="http://db.apache.org/jdo/api30/apidocs/index.html">here</a>.
+                </p>
+            </subsection>
+
+            <subsection name="Query Cancel/Timeout API">
+                <p>
+                    On occasions a query may be inefficient, or may suffer from problems in the underlying
+                    datastore, and so we don't want to affect the application. In this case it would make
+                    sense to have control over a timeout for the query, or be able to cancel it.
+                    JDO 3.0 introduces the Query cancel/timeout control, via the following new methods
+                    to <i>javax.jdo.Query</i>
+                </p>
+                <source><![CDATA[
+void setTimeoutMillis(Integer interval);
+Integer getTimeoutMillis();
+void cancelAll();
+void cancel(Thread thread);]]></source>
+                <p>
+                    So we have the ability to cancel a query as required, or just let it timeout.
+                </p>
+            </subsection>
+
+            <subsection name="Control of read objects locking">
+                <p>
+                    When we are using datastore (pessimistic) transactions it often doesn't make sense
+                    to just lock all objects read in the transaction. For this reason JDO 3.0 introduces
+                    control over which objects are locked and which aren't.
+                </p>
+                <p>
+                    In metadata for each class you can specify the "serialize-read" setting. 
+                    True will mean that objects of this type will be locked when read.
+                </p>
+                <p>
+                    On a Transaction you can override the metadata settings via the following
+                    method
+                </p>
+                <source><![CDATA[
+void setSerializeRead(Boolean serialize);
+Boolean getSerializeRead();]]></source>
+                <p>
+                    On a Query you can override the metadata and Transaction settings via the following
+                    method
+                </p>
+                <source><![CDATA[
+void setSerializeRead(Boolean serialize);
+Boolean getSerializeRead();]]></source>
+            </subsection>
+
+            <p>
+                This concludes our simple overview of JDO3. We hope you enjoy using it
+            </p>
+        </section>
+
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdo_dtd.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdo_dtd.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdo_dtd.xml (added)
+++ db/jdo/site/src/site/xdoc/jdo_dtd.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDO DTD</title>
+    </properties>
+    <body>
+        <section name="Meta-Data - JDO">
+            <p> 
+                JDO2 defines XML MetaData in <b>jdo</b> files as well as <b>orm</b> files. 
+                As always with XML, the metadata must match the defined DTD/XSD for that file type.
+                This section describes the content of the <b>jdo</b> files.
+                The content of <b>orm</b> files can be found <a href="orm_dtd.html">here</a>.
+                All <b>jdo</b> files must contain a valid DTD/DOCTYPE specification. You can use PUBLIC or SYSTEM versions of these.
+            </p>
+            <p>
+                Here are a few examples valid for <b>jdo</b> files with DTD specifications
+            </p>
+            <source><![CDATA[
+<!DOCTYPE jdo PUBLIC
+    "-//Sun Microsystems, Inc.//DTD Java Data Objects Metadata 3.0//EN"
+    "http://java.sun.com/dtd/jdo_3_0.dtd">
+
+
+<!DOCTYPE jdo SYSTEM "file:/javax/jdo/jdo.dtd">]]></source>
+            <br/>
+            <p>
+                Here is an example valid for <b>jdo</b> files with XSD specification
+            </p>
+            <source><![CDATA[
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdo xmlns="http://java.sun.com/xml/ns/jdo/jdo"
+     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdo
+        http://java.sun.com/xml/ns/jdo/jdo_3_0.xsd">
+    ...
+</jdo>]]></source>
+            <p>
+                Your MetaData should match either the <a href="http://java.sun.com/dtd/jdo_3_0.dtd" target="_blank">DTD</a>
+                or the <a href="http://java.sun.com/xml/ns/jdo/jdo_3_0.xsd" target="_blank">XSD</a> specification.
+            </p>
+        </section>
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdo_v_jpa.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdo_v_jpa.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdo_v_jpa.xml (added)
+++ db/jdo/site/src/site/xdoc/jdo_v_jpa.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,208 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDO .v. JPA</title>
+    </properties>
+
+    <body>
+        <section name="Which Persistence Specification ?">
+            <p>
+                There are several competing persistence technologies available for Java. 
+				Two of these are "standardised" (via the JCP). When developing your application you need 
+				to choose the most appropriate technology for your needs. <b>Java Data Objects (JDO)</b> 
+				has been a standard since 2001 with the release of JDO1. It was improved with the release 
+				of JDO2. Just to confuse issues the <b>Java Persistence API (JPA)</b> was approved 
+				in its JPA1 form, and JDO2.1/JDO2.2 provide updates to JDO2 building on some of the new 
+                features of JPA1. Since then we have had JDO3 adding on extra metadata and enhancer
+                standardisation, and JPA2 providing criteria queries. 
+                Below we show some of the differences of these 2 standards to give you 
+                assistance in selecting what you need. Highlighted in bold are the notable differences where one 
+                specification provides something not available in the other.
+            </p>
+            <table>
+                <tr>
+                    <th width="20%">Feature</th>
+                    <th width="40%">JDO</th>
+                    <th width="40%">JPA</th>
+                </tr>
+                <tr>
+                    <td>JDK Requirement</td>
+                    <td><b>1.3+</b></td>
+                    <td>1.5+</td>
+                </tr>
+                <tr>
+                    <td>Usage</td>
+                    <td>J2EE, J2SE</td>
+                    <td>J2EE, J2SE</td>
+                </tr>
+                <tr>
+                    <td>Persistence specification mechanism</td>
+                    <td>XML, Annotations, <b>API</b></td>
+                    <td>XML, Annotations</td>
+                </tr>
+                <tr>
+                    <td>Datastore supported</td>
+                    <td><b>Any</b></td>
+                    <td>RDBMS only</td>
+                </tr>
+                <tr>
+                    <td>Restrictions on persisted classes</td>
+                    <td><b>no-arg constructor (could be added by compiler/enhancer)</b></td>
+                    <td>No final classes. No final methods. Non-private no-arg constructor. Identity Field.
+					    Version Field.</td>
+                </tr>
+                <tr>
+                    <td>Ability to persist "transient" fields</td>
+                    <td><b>Yes</b></td>
+                    <td>No</td>
+                </tr>
+                <tr>
+                    <td>Persist static/final fields</td>
+                    <td>No</td>
+                    <td>Not specified</td>
+                </tr>
+                <tr>
+                    <td>Transactions</td>
+                    <td><b>Pessimistic</b>, Optimistic</td>
+                    <td>Optimistic, some locking</td>
+                </tr>
+                <tr>
+                    <td>Object Identity</td>
+                    <td><b>datastore-identity</b>, application-identity</td>
+                    <td>application-identity</td>
+                </tr>
+                <tr>
+                    <td>Object Identity generation</td>
+                    <td>Sequence, Table, Identity, Auto, <b>UUID String, UUID Hex</b></td>
+                    <td>Sequence, Table, Identity, Auto</td>
+                </tr>
+                <tr>
+                    <td>Change objects identity</td>
+                    <td><b>Throw exception when not allowed</b></td>
+                    <td>Undefined !!</td>
+                </tr>
+                <tr>
+                    <td>Supported types</td>
+                    <td>Java primitive types, wrappers of primitive types, java.lang.String, <b>java.lang.Number</b>, java.math.BigInteger, java.math.BigDecimal,
+                        <b>java.util.Currency, java.util.Locale</b>, java.util.Date, java.sql.Time, java.sql.Date, java.sql.Timestamp, java.io.Serializable,
+                        <b>boolean[]</b>, byte[], char[], <b>double[], float[], int[], long[], short[]</b>,
+                        <b>java.lang.Object</b>, <b>interface</b>,
+                        <b>Boolean[]</b>, Byte[], Character[], <b>Double[], Float[], Integer[], Long[], Short[], BigDecimal[], BigInteger[], String[]</b>,
+                        <b>PersistenceCapable[]</b>, <b>interface[]</b>, <b>Object[]</b>, Enums,
+                        java.util.Collection, java.util.Set, java.util.List, java.util.Map,
+                        <b>Collection/List/Map of simple types</b>, <b>Collection/List/Map of reference (interface/Object) types</b>,
+                        Collection/List/Map of persistable types
+                    </td>
+                    <td>Java primitive types, wrappers of the primitive types, java.lang.String, java.math.BigInteger, java.math.BigDecimal, 
+                        java.util.Date, <b>java.util.Calendar</b>, java.sql.Date, java.sql.Time, java.sql.Timestamp, java.io.Serializable,
+                        byte[], Byte[], char[], Character[], Enums,
+                        java.util.Collection, java.util.Set, java.util.List, java.util.Map
+                        Collection/List/Map of persistable types</td>
+                </tr>
+                <tr>
+                    <td>Embedded Fields</td>
+                    <td>Embedded persistent objects, <b>Embedded Collections, Embedded Maps</b></td>
+                    <td>Embedded persistent objects</td>
+                </tr>
+                <tr>
+                    <td>Access a non-detached field</td>
+                    <td><b>Throw exception</b></td>
+                    <td>Undefined !!</td>
+                </tr>
+                <tr>
+                    <td>Inheritance</td>
+                    <td><b>Each class has its own strategy</b></td>
+                    <td>Root class defines the strategy</td>
+                </tr>
+                <tr>
+                    <td>Operation cascade default</td>
+                    <td>persist, (delete)</td>
+                    <td></td>
+                </tr>
+                <tr>
+                    <td>Operation Cascade configuration</td>
+                    <td>delete</td>
+                    <td>persist, delete, refresh</td>
+                </tr>
+                <tr>
+                    <td>Query Language</td>
+                    <td>JDOQL, SQL, others</td>
+                    <td>JPQL, SQL</td>
+                </tr>
+                <tr>
+                    <td>Query candidates</td>
+                    <td><b>Candidate without subclasses</b>, Candidate and its subclasses</td>
+                    <td>Candidate and its subclasses</td>
+                </tr>
+                <tr>
+                    <td>Query of candidate collection</td>
+                    <td><b>yes</b></td>
+                    <td>no</td>
+                </tr>
+                <tr>
+                    <td>Query language case sensitivity</td>
+                    <td>JDOQL lowercase/UPPERCASE</td>
+                    <td>JPQL case-insensitive</td>
+                </tr>
+                <tr>
+                    <td>Query language aliases</td>
+                    <td>No, but has variables in JDOQL</td>
+                    <td>Yes in JPQL</td>
+                </tr>
+                <tr>
+                    <td>Query Criteria API</td>
+                    <td>No, available as extension in QueryDSL</td>
+                    <td><b>Yes</b></td>
+                </tr>
+                <tr>
+                    <td>Object retrieval control</td>
+                    <td>Lazy/Eager control, <b>fetch groups</b></td>
+                    <td>Lazy/Eager control</td>
+                </tr>
+                <tr>
+                    <td>Bulk update/delete</td>
+                    <td>JDOQL Bulk Delete</td>
+                    <td>JPQL Bulk Delete, <b>JPQL Bulk Update</b></td>
+                </tr>
+                <tr>
+                    <td>RDBMS Schema Control</td>
+                    <td>Tables, columns, PK columns, <b>PK constraints</b>, FK columns, <b>FK constraints</b>, <b>index columns</b>, 
+                        <b>index constraints</b>, unique key columns, <b>unique key constraints</b></td>
+                    <td>Tables, columns, PK columns, FK columns, unique key columns</td>
+                </tr>
+                <tr>
+                    <td>ORM Relationships</td>
+                    <td><a href="jdo_v_jpa_orm.html"><b>Full range of Collection, Map, List, Array, 1-1, 1-N, M-N using 
+                        PC, Non-PC and interface objects</b></a></td>
+                    <td>Basic 1-1, 1-N, M-N, Collection&lt;NonPC&gt;, Map&lt;NonPC&gt;</td>
+                </tr>
+                <tr>
+                    <td>Default ORM column size</td>
+                    <td>256</td>
+                    <td>255</td>
+                </tr>
+                <tr>
+                    <td>Default ORM identifiers (tables/columns)</td>
+                    <td>No</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td>Default ORM mappings</td>
+                    <td>Yes, JDBC types defined for Java types</td>
+                    <td>No</td>
+                </tr>
+                <tr>
+                    <td>Caching interface</td>
+                    <td>L2 Caching API</td>
+                    <td>L2 Caching API</td>
+                </tr>
+            </table>
+            <p>
+                As an overall conclusion "JPA" is a subset of what is already available in "JDO".
+            </p>
+        </section>
+
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdo_v_jpa_api.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdo_v_jpa_api.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdo_v_jpa_api.xml (added)
+++ db/jdo/site/src/site/xdoc/jdo_v_jpa_api.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDO .v. JPA : API</title>
+    </properties>
+
+    <body>
+        <section name="JDO .v. JPA : API">
+            <p>
+                The two persistence standards in Java have very similar API's on the face of it.
+                Here we give a comparison of the method calls and their equivalent in the other
+                API.
+            </p>
+            <table>
+                <tr>
+                    <th width="20%">Operation</th>
+                    <th width="40%">JDO</th>
+                    <th width="40%">JPA</th>
+                </tr>
+                <tr>
+                    <td>Persist Object</td>
+                    <td>pm.makePersistent()</td>
+                    <td>em.persist</td>
+                </tr>
+                <tr>
+                    <td>Update Object</td>
+                    <td>pm.makePersistent()</td>
+                    <td>em.merge()</td>
+                </tr>
+                <tr>
+                    <td>Remove Object</td>
+                    <td>pm.deletePersistent()</td>
+                    <td>em.remove()</td>
+                </tr>
+                <tr>
+                    <td>Retrieve Object</td>
+                    <td>pm.getObjectById()<br/>
+                        pm.getExtent()</td>
+                    <td>em.find()</td>
+                </tr>
+                <tr>
+                    <td>Refresh Object</td>
+                    <td>pm.refresh()</td>
+                    <td>em.refresh()</td>
+                </tr>
+                <tr>
+                    <td>Detach single Object</td>
+                    <td>pm.detachCopy()</td>
+                    <td>em.detach()</td>
+                </tr>
+                <tr>
+                    <td>Flush changes</td>
+                    <td>pm.flush()</td>
+                    <td>em.flush()</td>
+                </tr>
+                <tr>
+                    <td>Access transaction</td>
+                    <td>pm.currentTransaction()</td>
+                    <td>em.getTransaction()</td>
+                </tr>
+                <tr>
+                    <td>New Query</td>
+                    <td>pm.newQuery()</td>
+                    <td>em.createQuery()</td>
+                </tr>
+                <tr>
+                    <td>New Named Query</td>
+                    <td>pm.newNamedQuery()</td>
+                    <td>em.createNamedQuery()</td>
+                </tr>
+                <tr>
+                    <td>New SQL Query</td>
+                    <td>pm.newQuery()</td>
+                    <td>em.createNativeQuery()</td>
+                </tr>
+            </table>
+        </section>
+
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdo_v_jpa_orm.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdo_v_jpa_orm.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdo_v_jpa_orm.xml (added)
+++ db/jdo/site/src/site/xdoc/jdo_v_jpa_orm.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,285 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDO .v. JPA : Object/Relational Mapping</title>
+    </properties>
+
+    <body>
+        <section name="Which ORM specification ?">
+            <p>
+				There are 2 prevalent specification in the Java ORM world. JDO provides the most complete
+                definition, whilst JPA is the most recent. 
+            </p>
+
+            <subsection name="Relationships">
+                <p>
+                    In this guide we show the different types of ORM relation commonly used, and mark 
+                    against it which specification supports it. This list is not yet complete but will be 
+                    added to to provide a comprehensive list of relationship type and where you can find it.
+                </p>
+                <table>
+                    <tr>
+                        <th>Field Type</th>
+                        <th>Relation</th>
+                        <th width="50">JDO</th>
+                        <th width="50">JPA</th>
+                    </tr>
+                    <tr>
+                        <td>PC</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_one.html#uni">1-1 Unidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_one.html#bi">1-1 Bidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#PC">1-1 serialised</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/compound_identity.html#1_1_uni">1-1 CompoundIdentity Unidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/compound_identity.html#1_N_coll_bi">1-N CompoundIdentity Collection Bidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/compound_identity.html#1_N_map_bi">1-N CompoundIdentity Map Bidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Interface</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/interfaces.html">1-1 Unidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Interface</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/interfaces.html">1-1 Bidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Interface</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#Reference">1-1 serialised</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td>?</td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#fk_uni">1-N ForeignKey Unidirectional Collection</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#fk_bi">1-N ForeignKey Bidirectional Collection</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#join_uni">1-N JoinTable Unidirectional Collection</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#join_bi">1-N JoinTable Bidirectional Collection</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;Non-PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#join_nonpc">1-N JoinTable Collection</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#shared_join">1-N JoinTable Collection using shared JoinTable</a></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_collection.html#shared_fk">1-N ForeignKey Collection using shared ForeignKey</a></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/many_to_many.html">M-N JoinTable</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/compound_identity.html#1_N_uni">1-N CompoundIdentity Unidirectional</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#Collection">1-N serialised Collection</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Collection&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#CollectionElements">1-N JoinTable Collection of serialised elements</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_list.html#fk_uni">1-N ForeignKey Unidirectional Indexed List</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_list.html#fk_bi">1-N ForeignKey Bidirectional Indexed List</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_list.html#join_uni">1-N JoinTable Unidirectional Indexed List</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_list.html#join_bi">1-N JoinTable Bidirectional Indexed List</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;Non-PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_list.html#join_nonpc">1-N JoinTable Indexed List</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jpa_orm/one_to_many_list.html#fk_uni">1-N ForeignKey Unidirectional Ordered List</a></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jpa_orm/one_to_many_list.html#fk_bi">1-N ForeignKey Bidirectional Ordered List</a></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jpa_orm/one_to_many_list.html#join_uni">1-N JoinTable Unidirectional Ordered List</a></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>List&lt;PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jpa_orm/one_to_many_list.html#join_bi">1-N JoinTable Bidirectional Ordered List</a></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;PC, PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#join_pc_pc">1-N JoinTable Map</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;Non-PC, PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#join_simple_pc">1-N JoinTable Map</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;PC, Non-PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#join_pc_simple">1-N JoinTable Map</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;Non-PC, Non-PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#join_simple_simple">1-N JoinTable Map</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;Non-PC, PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#fk_uni_key">1-N ForeignKey Map Unidirectional (key stored in value)</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;Non-PC, PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#fk_bi_key">1-N ForeignKey Map Bidirectional (key stored in value)</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;PC, Non-PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/one_to_many_map.html#fk_uni_value">1-N ForeignKey Map Unidirectional (value stored in key)</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;PC, PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#Map">1-N serialised Map</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Map&lt;PC, PC&gt;</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#MapKeysValues">1-N JoinTable Map of serialised keys/values</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC[   ]</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/arrays.html#fk">1-N ForeignKey Unidirectional Array</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC[   ]</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/arrays.html#join">1-N JoinTable Unidirectional Array</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>PC[   ]</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/serialised.html#Array">1-N serialised Array</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                    </tr>
+                    <tr>
+                        <td>Non-PC[   ]</td>
+                        <td><a href="http://www.jpox.org/docs/1_2/jdo_orm/arrays.html#join">1-N JoinTable Unidirectional Array</a></td>
+                        <td><img alt="" src="images/icon_success_sml.gif" border="0"/></td>
+                        <td><img alt="" src="images/icon_error_sml.gif" border="0"/></td>
+                    </tr>
+                </table>
+            </subsection>
+        </section>
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdocentral.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdocentral.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdocentral.xml (added)
+++ db/jdo/site/src/site/xdoc/jdocentral.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+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.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+  <properties>
+    <title>Home</title>
+    <author email="jdo-dev@db.apache.org">JDO Documentation Team</author>
+  </properties>
+  <body>
+    <section name="JDOCentral at Apache JDO">
+      <p>
+      Welcome to the new home of JDOCentral!
+      </p>
+      <p>
+      JDOCentral was a privately maintained site.
+      Apache JDO is home for the development of the JDO specification and the TCK. 
+      The <a href="http://www.datanucleus.org">DataNucleus</a> site is home for the development of 
+      the Reference Implementation of the JDO specification.
+      </p>
+      <p>
+      Visit the other pages on the Apache JDO site to find out what's going on with JDO.
+      Join the <a href="http://db.apache.org/jdo/mail-lists.html">mailing lists</a> to get involved 
+      and provide feedback.
+      </p>
+    </section>
+  </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdoconfig_dtd.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdoconfig_dtd.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdoconfig_dtd.xml (added)
+++ db/jdo/site/src/site/xdoc/jdoconfig_dtd.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDOConfig DTD/XSD</title>
+    </properties>
+    <body>
+        <section name="Meta-Data - JDOConfig">
+            <p> 
+                JDO allows you to define a file <i>jdoconfig.xml</i> that specifies the properties
+				for a named PMF. As always with XML, the metadata must match the defined DTD/XSD for 
+				that file type. This section describes the content of the <b>jdoconfig</b> files.
+                All <b>jdoconfig</b> files must contain a valid DTD/DOCTYPE specification. You can use 
+				PUBLIC or SYSTEM versions of these.
+            </p>
+            <p>
+                Here are a few examples valid for <b>jdoconfig</b> files with DTD specifications
+            </p>
+            <source><![CDATA[
+<!DOCTYPE jdoconfig PUBLIC 
+    "-//Sun Microsystems, Inc.//DTD Java Data Objects Configuration 3.0//EN"
+    "http://java.sun.com/dtd/jdoconfig_3_0.dtd">
+
+
+<!DOCTYPE jdoconfig SYSTEM "file:/javax/jdo/jdoconfig.dtd">]]></source>
+            <br/>
+            <p>
+                Here is an example valid for <b>jdoconfig</b> files with XSD specification
+            </p>
+            <source><![CDATA[
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdoconfig xmlns="http://java.sun.com/xml/ns/jdo/jdoconfig"
+     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdoconfig
+        http://java.sun.com/xml/ns/jdo/jdoconfig_3_0.xsd">
+    ...
+</jdoconfig>]]></source>
+            <p>
+                Your MetaData should match either the <a href="http://java.sun.com/dtd/jdoconfig_3_0.dtd" target="_blank">DTD</a>
+                or the <a href="http://java.sun.com/xml/ns/jdo/jdoconfig_3_0.xsd" target="_blank">XSD</a> specification.
+            </p>
+        </section>
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdohelper.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdohelper.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdohelper.xml (added)
+++ db/jdo/site/src/site/xdoc/jdohelper.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDOHelper</title>
+    </properties>
+
+    <body>
+        <section name="JDOHelper">
+            <p>
+                JDO provides a standard utility that gives access to useful parts of the JDO persistence process.
+                This is known as <b>JDOHelper</b> (javax.jdo.JDOHelper)
+                <a href="api20/apidocs/javax/jdo/JDOHelper.html" target="_blank"><img alt="" src="images/javadoc.gif"/></a>
+            </p>
+
+            <subsection name="PersistenceManagerFactory methods">
+                <p>
+                    The methods in JDOHelper can be split into categories. Here we start with the methods
+					for creating the starting point for persistence, the PersistenceManagerFactory (PMF)
+                </p>
+                <ul>
+                    <li><b>getPersistenceManagerFactory(Map props)</b> - 
+                        creates a PMF given a Map of the properties</li>
+                    <li><b>getPersistenceManagerFactory(Map props, ClassLoader cl)</b> - 
+                        creates a PMF given a Map of the properties, and a ClassLoader to use</li>
+                    <li><b>getPersistenceManagerFactory(String resource)</b> - 
+                        creates a PMF given a resource defining the properties.
+                        This can be used to create a named PMF in JDO2.1</li>
+                    <li><b>getPersistenceManagerFactory(String props, ClassLoader cl)</b> - 
+                        creates a PMF given a resource defining the properties, and a ClassLoader to use</li>
+                    <li><b>getPersistenceManagerFactory(File props)</b> - 
+                        creates a PMF given a file containing the properties</li>
+                    <li><b>getPersistenceManagerFactory(File props, ClassLoader cl)</b> - 
+                        creates a PMF given a file containing the properties and a ClassLoader to use</li>
+                    <li><b>getPersistenceManagerFactory(String jndi, Context ctx)</b> - 
+                        creates a PMF given a JNDI resource</li>
+                    <li><b>getPersistenceManagerFactory(String jndi, Context ctx, ClassLoader cl)</b> - 
+                        creates a PMF given a JNDI resource and a ClassLoader to use</li>
+                    <li><b>getPersistenceManagerFactory(InputStream strm)</b> - 
+                        creates a PMF given an InputStream</li>
+                    <li><b>getPersistenceManagerFactory(InputStream strm, ClassLoader cl)</b> - 
+                       creates a PMF given an InputStream and a ClassLoader to use</li>
+                </ul>
+	            <br/>
+			</subsection>
+			<subsection name="Persistence methods">
+                <p>
+                    Now we move onto the operations for persistence.
+                </p>
+                <ul>
+                    <li><b>getPersistenceManager(Object pc)</b> - 
+                        returns the PersistenceManager associated with the passed object (if any)</li>
+                    <li><b>makeDirty(Object pc, String fieldName)</b> - 
+                       marks the field of the passed object as dirty (meaning that it needs updating in ther datastore)</li>
+                    <li><b>getObjectId(Object pc)</b> - 
+                        returns the object identity for the passed object (if persistent)</li>
+                    <li><b>getObjectIds(Collection pc)</b> - 
+                        returns the object identities for the passed objects (if persistent)</li>
+                    <li><b>getObjectIds(Object[] pc)</b> - 
+                        returns the object identities for the passed objects (if persistent)</li>
+                    <li><b>getVersion(Object pc)</b> - 
+                        returns the version for the passed object (if persistent)</li>
+                </ul>
+	            <br/>
+            </subsection>
+
+            <subsection name="Lifecycle methods">
+                <p>
+                    Now we move onto lifecycle operations
+                </p>
+                <ul>
+                    <li><b>getObjectState(Object pc)</b> - 
+                        returns the object state (JDO2.1 JDK1.5+ only)</li>
+                    <li><b>isDirty(Object pc)</b> - 
+                        returns whether the passed object is dirty</li>
+                    <li><b>isTransactional(Object pc)</b> - 
+                        returns whether the passed object is transactional</li>
+                    <li><b>isPersistent(Object pc)</b> - 
+                        returns whether the passed object is persistent</li>
+                    <li><b>isNew(Object pc)</b> -
+                        returns whether the passed object is new</li>
+                    <li><b>isDeleted(Object pc)</b> - 
+                        returns whether the passed object is deleted</li>
+                    <li><b>isDetached(Object pc)</b> - 
+                        returns whether the passed object is detached</li>
+                </ul>
+			</subsection>
+        </section>
+
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdoql.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdoql.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdoql.xml (added)
+++ db/jdo/site/src/site/xdoc/jdoql.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDOQL</title>
+    </properties>
+
+    <body>
+        <section name="JDOQL">
+            <p>
+                JDO defines ways of querying objects persisted into the datastore. It provides 
+                its own object-based query language (JDOQL). JDOQL is designed as the Java 
+                developers way of having the power of SQL queries, yet retaining the Java 
+                object relationship that exist in their application model. 
+                A typical JDOQL query may be set up in one of 2 ways. Here's an example
+            </p>
+            <source>
+Declarative JDOQL :
+Query q = pm.newQuery(mydomain.Person.class, "lastName == \"Jones\" &amp;&amp; age &lt; age_limit");
+q.declareParameters("double age_limit");
+List results = (List)q.execute(20.0);
+
+Single-String JDOQL :
+Query q = pm.newQuery("SELECT FROM mydomain.Person WHERE lastName == \"Jones\"" +
+                      " &amp;&amp; age &lt; :age_limit PARAMETERS double age_limit");
+List results = (List)q.execute(20.0);</source>
+			<p>
+                So here in our example we select all "Person" objects with surname of "Jones" 
+                and where the persons age is below 20. The language is intuitive for Java 
+                developers, and is intended as their interface to accessing the persisted 
+                data model. As can be seen above, the query is made up of distinct parts. 
+                The class being selected (the SELECT clause in SQL), the filter (which equates 
+                to the WHERE clause in SQL), together with any sorting (the ORDER BY clause 
+                in SQL), etc.
+			</p>
+            <p>
+                Before giving details on JDOQL, you can download a quick
+                reference guide <a href="jdoql_quickref.pdf">here</a>
+            </p>
+            <br/>
+
+			<a name="singlestring"/>
+            <subsection name="Single-String JDOQL">
+                <p>
+                    In traditional (declarative) JDOQL (JDO 1.0) it was necessary to specify 
+                    the component parts (filter, candidate class, ordering, etc) of the query 
+                    using the mutator methods on the Query. In JDO 2 you can now specify it 
+                    all in a single string. This string has to follow a particular pattern,
+                    but provides the convenience that many people have been asking for. 
+                    The pattern to use is as follows
+                </p>
+                <source>
+SELECT [UNIQUE] [&lt;result&gt;] [INTO &lt;result-class&gt;]
+        [FROM &lt;candidate-class&gt; [EXCLUDE SUBCLASSES]]
+        [WHERE &lt;filter&gt;]
+        [VARIABLES &lt;variable declarations&gt;]
+        [PARAMETERS &lt;parameter declarations&gt;]
+        [&lt;import declarations&gt;]
+        [GROUP BY &lt;grouping&gt;]
+        [ORDER BY &lt;ordering&gt;]
+        [RANGE &lt;start&gt;, &lt;end&gt;]</source> 
+                <p>
+                    The "keywords" in the query are shown in UPPER CASE but can be in 
+                    <i>UPPER</i> or <i>lower</i> case.
+                </p>
+                <p>
+                    Lets give an example of a query using this syntax
+                </p>
+<source>SELECT UNIQUE FROM org.datanucleus.samples.Employee ORDER BY departmentNumber</source>
+                <p>
+                    so we form the parts of the query as before, yet here we just specify it 
+                    all in a single call.
+                </p>
+            </subsection>
+
+            <subsection name="Accessing Fields">
+                <p>
+                    In JDOQL you access fields in the query by referring to the field name. 
+                    For example, if you are querying a class called <i>Product</i> and it has 
+                    a field "price", then you access it like this
+                </p>
+                <source>
+Query query = pm.newQuery(mydomain.Product.class, "price &lt; 150.0");</source>
+                <p>
+                    In addition to the persistent fields, you can also access 
+                    "public static final" fields of any class. You can do this as follows
+                </p>
+                <source>
+Query query = pm.newQuery(mydomain.Product.class, 
+       "taxPercent &lt; mydomain.Product.TAX_BAND_A");</source>
+                <p>
+                    So this will find all products that include a tax percentage less than 
+                    some "BAND A" level. Where you are using "public static final" fields you 
+                    can either fully-qualify the class name or you can include it in the 
+                    "imports" section of the query (see later).
+                </p>
+            </subsection>
+
+            <subsection name="Data types : literals">
+                <p>
+                    JDOQL supports the following literals: IntegerLiteral, 
+                    FloatingPointLiteral, BooleanLiteral, CharacterLiteral, StringLiteral, 
+                    and NullLiteral.
+                </p>
+            </subsection>
+            
+            <subsection name="Operators precedence">
+                <p>
+                    The following list describes the operator precedence in JDOQL.
+                </p>
+                    <ol>
+                        <li>Cast</li>
+                        <li>Unary ("~") ("!")</li>
+                        <li>Unary ("+") ("-")</li>
+                        <li>Multiplicative ("*") ("/") ("%")</li>
+                        <li>Additive ("+") ("-")</li>
+                        <li>Relational (">=") (">") ("&lt;=") ("&lt;") ("instanceof")</li>
+                        <li>Equality ("==") ("!=")</li>
+                        <li>Boolean logical AND ("&amp;")</li>
+                        <li>Boolean logical OR ("|")</li>
+                        <li>Conditional AND ("&amp;&amp;")</li>
+                        <li>Conditional OR ("||")</li>
+                    </ol>
+            </subsection>
+            
+            <subsection name="Concatenation Expressions">
+                <p>
+                    The concatenation operator(+) concatenates a String to either another 
+                    String or Number. Concatenations of String or Numbers to null results in 
+                    null.
+                </p>
+            </subsection>
+
+            <subsection name="Example 1 - Use of Explicit Parameters">
+                <p>
+                    Here's a simple example for finding the elements of a class with a field 
+                    below a particular threshold level. Here we pass in the threshold value 
+                    (<i>limit</i>), and sort the output in order of ascending price.
+                </p>
+                <source>
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class,"price &lt; limit");
+query.declareParameters("double limit");
+query.setOrdering("price ascending");
+List results = (List)query.execute(150.00);
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " +
+                "price &lt; limit PARAMETERS double limit ORDER BY price ASCENDING");
+List results = (List)query.execute(150.00);</source>
+                <p>
+                    For completeness, the class is shown here
+                </p>
+                <source><![CDATA[
+class Product
+{
+    String name;
+    double price;
+    java.util.Date endDate;
+    ...
+}
+
+<jdo>
+    <package name="mydomain">
+        <class name="Product">
+            <field name="name">
+                <column length="100" jdbc-type="VARCHAR"/>
+            </field>
+            <field name="abreviation">
+                <column length="20" jdbc-type="VARCHAR"/>
+            </field>
+            <field name="price"/>
+            <field name="endDate"/>
+        </class>
+    </package>
+</jdo>]]></source>
+                <br/>
+            </subsection>
+
+            <subsection name="Example 2 - Use of Implicit Parameters">
+                <p>
+                    Let's repeat the previous query but this time using <i>implicit</i> 
+                    parameters.
+                </p>
+                <source>
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class,"price &lt; :limit");
+query.setOrdering("price ascending");
+List results = (List)query.execute(150.00);
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " +
+                "price &lt; :limit ORDER BY price ASCENDING");
+List results = (List)query.execute(150.00);</source>
+                <p>
+                    So we omitted the declaration of the parameter and just prefixed it with 
+                    a colon (:)
+                </p>
+                <br/>
+            </subsection>
+
+            <subsection name="Example 3 - Comparison against Dates">
+                <p>
+                    Here's another example using the same Product class as above, but this 
+                    time comparing to a Date field. Because we are using a type in our query, 
+                    we need to <i>import</i> it ... 
+                    just like you would in a Java class if you were using it there.
+                </p>
+                <source>
+Declarative JDOQL :
+Query query = pm.newQuery(domain.Product.class,
+                          "endDate &gt; best_before_limit");
+query.declareImports("import java.util.Date");
+query.declareParameters("Date best_before_limit");
+query.setOrdering("endDate descending");
+Collection results = (Collection)query.execute(my_date_limit);
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.Product " +
+                "WHERE endDate &gt; best_before_limit " +
+                "PARAMETERS Date best_before_limit " +
+                "import java.util.Date ORDER BY endDate DESC");
+List results = (List)query.execute(my_date_limit);</source>
+                <br/>
+            </subsection>
+
+            <subsection name="Example 4 - Instanceof">
+                <p>
+                    This example demonstrates use of the "instanceof" operator. We have a 
+                    class A that has a field "b" of type B and B has subclasses B1, B2, B3. 
+                    Clearly the field "b" of A can be of type B, B1, B2, B3 etc, and we want 
+                    to find all objects of type A that have the field "b" that is of type B2. 
+                    We do it like this
+                </p>
+                <source>
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.A.class);
+query.setFilter("b instanceof mydomain.B2");
+List results = (List)query.execute();
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.A WHERE b instanceof mydomain.B2");
+List results = (List)query.execute();</source>
+            </subsection>
+        </section>
+
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdoql_methods.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdoql_methods.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdoql_methods.xml (added)
+++ db/jdo/site/src/site/xdoc/jdoql_methods.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,217 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDOQL - Methods</title>
+    </properties>
+
+    <body>
+        <section name="JDOQL : Methods">
+            <p>
+                When writing the "filter" for a JDOQL Query you can make use of some methods on the various 
+                Java types. The range of methods included as standard in JDOQL is not as flexible as with
+                the true Java types, but the ones that are available are typically of much use.
+            </p>
+            <br/>
+            <subsection name="String Methods">
+                <table>
+                    <tr>
+                        <th width="220">Method</th>
+                        <th>Description</th>
+                    </tr>
+                    <tr>
+                        <td>startsWith(String)</td>
+                        <td>Returns if the string starts with the passed string</td>
+                    </tr>
+                    <tr>
+                        <td>endsWith(String)</td>
+                        <td>Returns if the string ends with the passed string</td>
+                    </tr>
+                    <tr>
+                        <td>indexOf(String)</td>
+                        <td>Returns the first position of the passed string</td>
+                    </tr>
+                    <tr>
+                        <td>indexOf(String,int)</td>
+                        <td>Returns the position of the passed string, after the passed position</td>
+                    </tr>
+                    <tr>
+                        <td>substring(int)</td>
+                        <td>Returns the substring starting from the passed position</td>
+                    </tr>
+                    <tr>
+                        <td>substring(int,int)</td>
+                        <td>Returns the substring between the passed positions</td>
+                    </tr>
+                    <tr>
+                        <td>toLowerCase()</td>
+                        <td>Returns the string in lowercase</td>
+                    </tr>
+                    <tr>
+                        <td>toUpperCase()</td>
+                        <td>Retuns the string in UPPERCASE</td>
+                    </tr>
+                    <tr>
+                        <td>matches(String pattern)</td>
+                        <td>Returns whether string matches the passed expression. The pattern argument follows the rules of 
+                            java.lang.String.matches method.</td>
+                    </tr>
+                </table>
+                <p>
+                    Here's an example using a Product class, looking for objects which their abreviation is the 
+                    beginning of a trade name. The trade name is provided as parameter.
+                </p>
+                <source><![CDATA[
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class);
+query.setFilter(":tradeName.startsWith(this.abbreviation)");
+List results = (List)query.execute("Workbook Advanced");
+
+Single-String JDOQL :
+Query query = pm.newQuery(
+    "SELECT FROM mydomain.Product " +
+    "WHERE :tradeName.startsWith(this.abbreviation)");
+List results = (List)query.execute("Workbook Advanced");]]></source>
+                <br/>
+                <p>
+                    Here's another example, demonstrating the "matches" method.
+                    Consult the javadocs for Java regular expressions for the
+                    syntax of the matches input.
+                </p>
+                <source><![CDATA[
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class);
+query.setFilter("this.abbreviation.matches(\"a*b\")");
+List results = (List)query.execute();
+
+Single-String JDOQL :
+Query query = pm.newQuery(
+    "SELECT FROM mydomain.Product " +
+    "WHERE this.abbreviation.matches(\"a*b\")");
+List results = (List)query.execute();]]></source>
+                <br/>
+            </subsection>
+
+            <subsection name="Collection Methods">
+                <table>
+                    <tr>
+                        <th width="220">Method</th>
+                        <th>Description</th>
+                    </tr>
+                    <tr>
+                        <td>isEmpty()</td>
+                        <td>Returns whether the collection is empty</td>
+                    </tr>
+                    <tr>
+                        <td>contains(value)</td>
+                        <td>Returns whether the collection contains the passed element</td>
+                    </tr>
+                    <tr>
+                        <td>size()</td>
+                        <td>Returns the number of elements in the collection</td>
+                    </tr>
+                </table>
+                <p>
+                    Here's an example demonstrating use of contains(). We have an Inventory class that has a
+                    Collection of Product objects, and we want to find the Inventory objects with 2 particular 
+                    Products in it. Here we make use of a variable (<i>prd</i> to represent the Product being 
+                    contained
+                </p>
+                <source><![CDATA[
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Inventory.class);
+query.setFilter("products.contains(prd) && (prd.name==\"product 1\" || prd.name==\"product 2\")");
+List results = (List)query.execute();
+
+Single-String JDOQL:
+Query query = pm.newQuery(
+    "SELECT FROM mydomain.Inventory EXCLUDE SUBCLASSES " + 
+    "WHERE products.contains(prd) && (prd.name==\"product 1\" || prd.name==\"product 2\")");
+List results = (List)query.execute();]]></source>
+                <br/>
+            </subsection>
+
+            <subsection name="List Methods">
+                <table>
+                    <tr>
+                        <th width="220">Method</th>
+                        <th>Description</th>
+                    </tr>
+                    <tr>
+                        <td>get(position)</td>
+                        <td>Returns the element at that position in the List (JDO3.1)</td>
+                    </tr>
+                </table>
+                <br/>
+            </subsection>
+
+            <subsection name="Map Methods">
+                <table>
+                    <tr>
+                        <th width="220">Method</th>
+                        <th>Description</th>
+                    </tr>
+                    <tr>
+                        <td>isEmpty()</td>
+                        <td>Returns whether the map is empty</td>
+                    </tr>
+                    <tr>
+                        <td>containsKey(key)</td>
+                        <td>Returns whether the map contains the passed key</td>
+                    </tr>
+                    <tr>
+                        <td>containsValue(value)</td>
+                        <td>Returns whether the map contains the passed value</td>
+                    </tr>
+                    <tr>
+                        <td>get(key)</td>
+                        <td>Returns the value from the map with the passed key</td>
+                    </tr>
+                    <tr>
+                        <td>size()</td>
+                        <td>Returns the number of entries in the map</td>
+                    </tr>
+                </table>
+                <p>
+                    Here's an example using a Product class as a value in a Map. Our example represents an 
+                    organisation that has several Inventories of products. Each Inventory of products is stored 
+                    using a Map, keyed by the Product name. The query searches for all Inventories that contain a 
+                    product with the name "product 1".
+                </p>
+                <source>
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Inventory.class, "products.containsKey(\"product 1\")");
+List results = (List)query.execute();
+
+Single-String JDOQL :
+Query query = pm.newQuery(
+    "SELECT FROM mydomain.Inventory EXCLUDE SUBCLASSES " +
+    "WHERE products.containsKey(\"product 1\")");
+List results = (List)query.execute();</source>
+                <br/>
+            </subsection>
+ 
+            <subsection name="Other Methods">
+                <table>
+                    <tr>
+                        <th width="220">Method</th>
+                        <th>Description</th>
+                    </tr>
+                    <tr>
+                        <td>Math.abs(number)</td>
+                        <td>Returns the absolute value of the passed number</td>
+                    </tr>
+                    <tr>
+                        <td>Math.sqrt(number)</td>
+                        <td>Returns the square root of the passed number</td>
+                    </tr>
+                    <tr>
+                        <td>JDOHelper.getObjectId(object)</td>
+                        <td>Returns the object identity of the passed persistent object</td>
+                    </tr>
+                </table>
+            </subsection>
+        </section>
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdoql_result.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdoql_result.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdoql_result.xml (added)
+++ db/jdo/site/src/site/xdoc/jdoql_result.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDOQL - Result</title>
+    </properties>
+
+    <body>
+        <section name="JDOQL : Result">
+            <p>
+                As we have seen, a JDOQL query is made up of different parts. In this section we look at the 
+                <i>result</i> part of the query. The result is what we want returning. By default (when not specifying 
+                the result) the objects returned will be of the candidate class type, where they match the query
+                filter. Firstly let's look at what you can include in the <i>result</i> clause.
+            </p>
+            <ul>
+                <li><i>this</i> - the candidate instance</li>
+                <li>A field name</li>
+                <li>A variable</li>
+                <li>A parameter (though why you would want a parameter returning is hard to see since you input 
+                    the value in the first place)</li>
+                <li>An aggregate (count(), avg(), sum(), min(), max())</li>
+                <li>An expression involving a field (e.g "field1 + 1")</li>
+                <li>A navigational expression (navigating from one field to another ... e.g "field1.field4")</li>
+            </ul>
+            <p>
+                The result is specified in JDOQL like this
+            </p>
+            <source>query.setResult("count(field1), field2");</source>
+            <p>
+                In <b>Single-String JDOQL</b> you would specify it directly.
+            </p>
+            <br/>
+
+            <subsection name="Result type">
+                <p>
+                    What you specify in the <i>result</i> defines what form of result you get back.
+                </p>
+                <ul>
+                    <li><b>Object</b> - this is returned if you have only a single row in the results and a single 
+                        column. This is achived when you specified either UNIQUE, or just an aggregate 
+                        (e.g "max(field2)")</li>
+                    <li><b>Object[]</b> - this is returned if you have only a single row in the results, but more 
+                        than 1 column (e.g "max(field1), avg(field2)")</li>
+                    <li><b>List&lt;Object&gt;</b> - this is returned if you have only a single column in the result, 
+                        and you don't have only aggregates in the result (e.g "field2")</li>
+                    <li><b>List&lt;Object[]&gt;</b> - this is returned if you have more than 1 column in the result, 
+                        and you don't have only aggregates in the result (e.g "field2, avg(field3)")</li>
+                </ul>
+            </subsection>
+
+            <subsection name="Aggregates">
+                <p>
+                    There are situations when you want to return a single number for a column, representing an 
+                    aggregate of the values of all records. There are 5 standard JDO2 aggregate functions available. 
+                    These are
+                </p>
+                <ul>
+                    <li><b>avg(val)</b> - returns the average of "val". "val" can be a field, numeric field expression 
+                        or "distinct field".</li>
+                    <li><b>sum(val)</b> - returns the sum of "val". "val" can be a field, numeric field expression, 
+                        or "distinct field".</li>
+                    <li><b>count(val)</b> - returns the count of records of "val". "val" can be a field, or can be 
+                        "this", or "distinct field".</li>
+                    <li><b>min(val)</b> - returns the minimum of "val". "val" can be a field</li>
+                    <li><b>max(val)</b> - returns the maximum of "val". "val" can be a field</li>
+                </ul>
+                <p>
+                    So to utilise these you could specify something like
+                </p>
+                <source>
+Query q = pm.newQuery("SELECT max(price), min(price) FROM mydomain.Product WHERE status == 1");</source>
+                <p>
+                    This will return a single row of results with 2 values, the maximum price and the minimum price of
+                    all products that have status code of 1.
+                </p>
+                <br/>
+            </subsection>
+
+            <subsection name="Example - Use of aggregates">
+                <p>
+                    JDO 2 introduces the ability to use aggregates in queries. Here's another example using the 
+                    same Product class as above, but this time looking for the maximum price of products that are 
+                    CD Players. Note that the result for this particular query will be of type Double since there 
+                    is a single double precision value being returned via the "result".
+                </p>
+                <source>
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class);
+query.setFilter("name == \"CD Player\"");
+query.setResult("max(this.price)");
+List results = (List)query.execute();
+Iterator iter = c.iterator();
+Double max_price = (Double)iter.next();
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT max(price) FROM mydomain.Product WHERE name == \"CD Player\"");
+List results = (List)query.execute();
+Iterator iter = c.iterator();
+Double max_price = (Double)iter.next();</source>
+                <br/>
+            </subsection>
+
+        </section>
+
+    </body>
+</document>

Added: db/jdo/site/src/site/xdoc/jdoquery_dtd.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/src/site/xdoc/jdoquery_dtd.xml?rev=1432659&view=auto
==============================================================================
--- db/jdo/site/src/site/xdoc/jdoquery_dtd.xml (added)
+++ db/jdo/site/src/site/xdoc/jdoquery_dtd.xml Sun Jan 13 17:05:15 2013
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+    <properties>
+        <title>JDOQuery DTD</title>
+    </properties>
+    <body>
+        <section name="Meta-Data - JDOQuery">
+            <p> 
+                JDO2 defines XML MetaData in <b>jdo</b> files as well as <b>orm</b> files, but also 
+                specifies that named queries can be defined in <i>jdoquery</i> files. 
+                As always with XML, the metadata must match the defined DTD/XSD for that file type.
+                This section describes the content of the <b>jdoquery</b> files.
+                All <b>jdoquery</b> files must contain a valid DTD/DOCTYPE specification. 
+                You can use PUBLIC or SYSTEM versions of these.
+            </p>
+            <p>
+                Here are a few examples valid for <b>jdoquery</b> files eith DTD specification
+            </p>
+            <source><![CDATA[
+<!DOCTYPE jdoquery PUBLIC
+    "-//Sun Microsystems, Inc.//DTD Java Data Objects Query Metadata 3.0//EN"
+    "http://java.sun.com/dtd/jdoquery_3_0.dtd">
+
+
+<!DOCTYPE jdoquery SYSTEM "file:/javax/jdo/jdoquery.dtd">]]></source>
+            <br/>
+            <p>
+                Here is an example valid for <b>jdoquery</b> files with XSD specification
+            </p>
+            <source><![CDATA[
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdo xmlns="http://java.sun.com/xml/ns/jdo/jdo"
+     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdoquery
+        http://java.sun.com/xml/ns/jdo/jdoquery_3_0.xsd">
+    ...
+</jdo>]]></source>
+            <p>
+                Your MetaData should match either the <a href="http://java.sun.com/dtd/jdoquery_3_0.dtd" target="_blank">DTD</a>
+                or the <a href="http://java.sun.com/xml/ns/jdo/jdoquery_3_0.xsd" target="_blank">XSD</a> specification.
+            </p>
+        </section>
+    </body>
+</document>



Mime
View raw message