openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kwsut...@apache.org
Subject svn commit: r447584 [8/8] - in /incubator/openjpa/sandboxes/OPENJPA-24: ./ openjpa-all/ openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/conf/ openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/ openjpa-jdbc/src/main/java/org/apache/openjpa/jd...
Date Mon, 18 Sep 2006 21:58:05 GMT
Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml?view=diff&rev=447584&r1=447583&r2=447584
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml
(original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml
Mon Sep 18 14:57:52 2006
@@ -114,7 +114,7 @@
             <imageobject>
                 <!-- PNG image data, 509 x 133 (see README) -->
                 <imagedata fileref="img/enhancement.png" width="339px"/>
-                
+
             </imageobject>
         </mediaobject>
         <para>
@@ -138,9 +138,9 @@
                 </secondary>
             </indexterm>
             <para>
-The enhancer can be invoked at build time via the included <literal>openjpac
-</literal> script or via its Java class, <classname>
-org.apache.openjpa.enhance.PCEnhancer</classname>.
+The enhancer can be invoked at build time 
+via the Java tool,
+<classname>org.apache.openjpa.enhance.PCEnhancer</classname>.
             </para>
             <note>
                 <para>
@@ -153,7 +153,7 @@
                     Using the OpenJPA Enhancer
                 </title>
 <programlisting>
-openjpac Magazine.java
+java org.apache.openjpa.enhance.PCEnhancer Magazine.java
 </programlisting>
             </example>
             <para>
@@ -513,8 +513,7 @@
 class code, you can set the <literal>@IdClass</literal> annotation.
             </para>
             <para>
-The application identity tool can be invoked via the included <literal>
-appidtool</literal> shell/bat script or via its Java class,
+The application identity tool can be invoked via the Java class,
 <ulink url="../apidocs/org/apache/openjpa/enhance/ApplicationIdTool">
 <classname>org.apache.openjpa.enhance.ApplicationIdTool</classname></ulink>.
             </para>
@@ -529,7 +528,7 @@
                     Using the Application Identity Tool
                 </title>
 <programlisting>
-appidtool -s Id Magazine.java
+java org.apache.openjpa.enhance.ApplicationIdTool -s Id Magazine.java
 </programlisting>
             </example>
             <para>
@@ -722,7 +721,7 @@
 {
     @OneToOne
     private Photograph coverPhoto;
-    
+
     ...
 }
 
@@ -732,7 +731,7 @@
     @OneToOne
     @InverseLogical("coverPhoto")
     private Magazine mag;
-    
+
     ...
 }
 </programlisting>
@@ -1099,8 +1098,8 @@
 @Entity
 public class Company
 {
-    @ManyToMany 
-    @LRS private Collection&lt;Employee&gt; employees;     
+    @ManyToMany
+    @LRS private Collection&lt;Employee&gt; employees;
 
     ...
 }
@@ -1230,9 +1229,9 @@
                 </title>
                 <tgroup cols="2" align="left" colsep="1" rowsep="1">
                     <colspec colname="method"/>
-                    
+
                     <colspec colname="extension"/>
-                    
+
                     <thead>
                         <row>
                             <entry colname="method">
@@ -1247,64 +1246,64 @@
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public String CustomType.toString()
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Externalizer("toString")
-              
+
                                 </literal>
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public String CustomType.toString(StoreContext ctx)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Externalizer("toString")
-              
+
                                 </literal>
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public static String AnyClass.toString(CustomType ct)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Externalizer("AnyClass.toString")
-              
+
                                 </literal>
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public static String AnyClass.toString(CustomType ct, StoreContext ctx)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Externalizer("AnyClass.toString")
-              
+
                                 </literal>
                             </entry>
                         </row>
@@ -1336,9 +1335,9 @@
                 </title>
                 <tgroup cols="2" align="left" colsep="1" rowsep="1">
                     <colspec colname="method"/>
-                    
+
                     <colspec colname="extension"/>
-                    
+
                     <thead>
                         <row>
                             <entry colname="method">
@@ -1353,78 +1352,78 @@
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public CustomType(String str)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
-                                
+
               none
-              
+
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public static CustomType CustomType.fromString(String str)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Factory("fromString")
-              
+
                                 </literal>
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public static CustomType CustomType.fromString(String str, StoreContext ctx)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Factory("fromString")
-              
+
                                 </literal>
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public static CustomType AnyClass.fromString(String str)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Factory("AnyClass.fromString")
-              
+
                                 </literal>
                             </entry>
                         </row>
                         <row>
                             <entry colname="method">
                                 <literal>
-                                    
+
               public static CustomType AnyClass.fromString(String str, StoreContext ctx)
-              
+
                                 </literal>
                             </entry>
                             <entry colname="extension">
                                 <literal>
-                                    
+
               @Factory("AnyClass.fromString")
-              
+
                                 </literal>
                             </entry>
                         </row>
@@ -1482,19 +1481,19 @@
 {
     // use Class.getName and Class.forName to go to/from strings
     @Persistent
-    @Externalizer("getName") 
+    @Externalizer("getName")
     @Factory("forName")
     private Class cls;
 
-    // use URL.getExternalForm for externalization. no factory; 
+    // use URL.getExternalForm for externalization. no factory;
     // we can rely on the URL string constructor
     @Persistent
     @Externalizer("toExternalForm")
     private URL url;
 
-    // use our custom methods; notice how we use the KeyType and ElementType 
+    // use our custom methods; notice how we use the KeyType and ElementType
     // annotations to specify the metadata for our externalized map
-    @Persistent 
+    @Persistent
     @Externalizer("Magazine.mapFromCustomType")
     @Factory("Magazine.mapToCustomType")
     @KeyType(String.class) @ElementType(String.class)
@@ -1649,30 +1648,11 @@
             </title>
             <para>
 OpenJPA places any field that is eagerly loaded according to the JPA metadata
-rules into the built-in <emphasis>default</emphasis> fetch group. The default
-fetch group is always active; you cannot remove it at runtime. Thus fields in
-this group are always loaded immediately when an object is fetched from the
-datastore.
-            </para>
-            <para>
-A field can be a member of zero or one fetch groups, including the default fetch
-group. That is, fields in the default fetch group cannot be in an additional
-fetch group, and a field cannot declare itself a member of more than one fetch
-group. So to place a field in a custom fetch group, you must first exclude it
-from eager fetching in your JPA metadata, if it does not already default to lazy
-loading.
-            </para>
-            <para>
-When lazy-loading a field, OpenJPA checks to see if that field declares itself
-to be a member of a fetch group. If so, OpenJPA will load all fields in that
-fetch group.
-            </para>
-            <para>
-Additionally, it is possible to configure a OpenJPA <classname> EntityManager
-</classname> or <classname>Query</classname> to use a particular fetch
group or
-set of fetch groups when loading new objects, as described later in this
-chapter. When this is the case, OpenJPA loads the default fetch group plus any
-fields in the specified set of additional fetch groups.
+rules into the built-in <emphasis>default</emphasis> fetch group. As its name
+implies, the default fetch group is active by default.  You may also
+define your own named fetch groups and activate or deactivate them at runtime,
+as described later in this chapter. OpenJPA will eagerly-load the fields in all
+active fetch groups when loading objects from the datastore.
             </para>
             <para>
 You create fetch groups with the
@@ -1712,7 +1692,7 @@
                 </listitem>
                 <listitem>
                     <para>
-<literal>String[] fetchGroups</literal>: Other fetch groups whose fields to 
+<literal>String[] fetchGroups</literal>: Other fetch groups whose fields to
 include in this group.
                     </para>
                 </listitem>
@@ -1734,36 +1714,35 @@
                 </listitem>
                 <listitem>
                     <para>
-<literal>depth</literal>: If the attribute represents a relation, the depth to
-which to recurse. The current fetch group will be applied to the related object
-when fetching it, and so on until the depth is exhausted or the related object
-has no relations in the current fetch group. Under the default depth of 1, the
-related object will be fetched, but none of its relations will be traversed,
-even if they are in the current fetch group. With a depth of 2, the related
-object will be fetched, and if it has any relations in the current fetch group,
-those will be fetched with a depth of 1. A depth of 0 indicates that the
-recursion continues until the graph is exhausted or a related object has no
-relations in the current fetch group.
+<literal>recursionDepth</literal>: If the attribute represents a relation, the
+maximum number of same-typed relations to eager-fetch from this field.  Defaults
+to 1.  For example, consider an <classname>Employee</classname> class with a
+<literal>manager</literal> field, also of type <classname>Employee</classname>.
+When we load an <classname>Employee</classname> and the <literal>
+manager</literal> field is in an active fetch group, the recursion depth (along
+with the max fetch depth setting, described below) determines whether we only
+retrieve the target <classname>Employee</classname> and his manager (depth 1),
+or whether we also retrieve the manager's manager (depth 2), or the manager's
+manager's manager (depth 3), etc.  Use -1 for unlimited depth.
                     </para>
                 </listitem>
             </itemizedlist>
-            <para>
-Thus, to create a <emphasis>detail</emphasis> fetch group consisting of the
-<literal>publisher</literal> and <literal>articles</literal> relations,
with the
-fetch group applied recursively to the related objects, use:
-            </para>
             <example id="ref_guide_fetch_customgroups">
                 <title>
                     Custom Fetch Group Metadata
                 </title>
+                <para>
+Creates a <emphasis>detail</emphasis> fetch group consisting of the
+<literal>publisher</literal> and <literal>articles</literal> relations,
use:
+                </para>
 <programlisting>
 import org.apache.openjpa.persistence.*;
 
 @Entity
 @FetchGroups({
     @FetchGroup(name="detail", attributes={
-        @FetchAttribute(name="publisher" depth=0),
-        @FetchAttribute(name="articles" depth=0)
+        @FetchAttribute(name="publisher"),
+        @FetchAttribute(name="articles")
     }),
     ...
 })
@@ -1773,13 +1752,51 @@
 }
 </programlisting>
             </example>
-            <note>
-                <para>
-OpenJPA currently only supports a depth of 0 for fetch attributes. This
-restriction will be lifted in a future release, along with the restriction
-limiting each attribute to a single fetch group.
-                </para>
-            </note>
+            <para>
+A field can be a member of any number of fetch groups.  A field can also
+declare a <emphasis>load fetch group</emphasis>.
+When you access a lazy-loaded field for the first time, OpenJPA makes a
+datastore trip to fetch that field's data.  Sometimes, however, you know
+that whenever you access a lazy field A, you're likely to access lazy fields B
+and C as well.  Therefore, it would be more efficient to fetch the data for A,
+B, and C in the same datastore trip.  By setting A's load fetch group to the
+name of a <link linkend="ref_guide_fetch">fetch group</link> containing B and
+C, you can tell OpenJPA to load all of these fields together when A is first
+accessed.
+            </para>
+            <para>
+Use OpenJPA's
+<ulink url="../apidocs/org/apache/openjpa/persistence/LoadFetchGroup.html">
+<classname>org.apache.openjpa.persistence.LoadFetchGroup</classname></ulink>
+annotation to specify the load fetch group of any persistent field. The value of
+the annotation is the name of a declared fetch group whose members should be
+loaded along with the annotated field.
+            </para>
+            <example id="ref_guide_fetch_loadgroup">
+                <title>
+                    Load Fetch Group Metadata
+                </title>
+<programlisting>
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@FetchGroups({
+    @FetchGroup(name="detail", attributes={
+        @FetchAttribute(name="publisher"),
+        @FetchAttribute(name="articles")
+    }),
+    ...
+})
+public class Magazine
+{
+   @ManyToOne(fetch=FetchType.LAZY)
+   @LoadFetchGroup("detail")
+   private Publisher publisher;
+
+   ...
+}
+</programlisting>
+            </example>
         </section>
         <section id="ref_guide_fetch_conf">
             <title>
@@ -1808,16 +1825,31 @@
 fetch group names.
             </para>
             <para>
-In JPA, OpenJPA's <classname>OpenJPAEntityManager</classname> and <classname>
+You can also set the system's default maximum fetch depth with the
+<link linkend="openjpa.MaxFetchDepth"><literal>openjpa.MaxFetchDepth</literal>
+</link> configuration property.  The maximum fetch depth determines how "deep"
+into the object graph to traverse when loading an instance.  The default maximum
+depth is 1, meaning that OpenJPA will load at most the target instance and its
+immediate relations.  By increasing the depth, you can allow OpenJPA to also
+load relations of relations, to arbitrary depth.  A value of -1 symbolizes an
+infinite maximum, telling OpenJPA to fetch configured relations until it reaches
+the edges of the object graph.  Of course, which relation fields are loaded
+depends on whether the fields are eager or lazy, and on the active fetch groups.
+A fetch group member's recursion depth may also limit the fetch depth to
+something less than the configured maximum.
+            </para>
+            <para>
+OpenJPA's <classname>OpenJPAEntityManager</classname> and <classname>
 OpenJPAQuery</classname> extensions to the standard <classname>EntityManager
 </classname> and <classname>Query</classname> interfaces provide access
to a
 <ulink url="../../api/openjpa/persistence/FetchPlan.html"><classname>
 org.apache.openjpa.persistence.FetchPlan</classname></ulink> object. The
-<classname>FetchPlan</classname> maintains the set of active fetch groups. It
-begins with the groups defined in the <literal>openjpa.FetchGroups</literal>
-property, but allows you to add and remove groups for an individual <classname>
-EntityManager</classname> or <classname>Query</classname> through the methods
-below.
+<classname>FetchPlan</classname> maintains the set of active fetch groups and
+the maximum fetch depth. It begins with the groups and depth defined in the
+<literal>openjpa.FetchGroups</literal> and <literal>openjpa.MaxFetchDepth
+</literal> properties, but allows you to add or remove groups and change the
+maximum fetch depth for an individual <classname>EntityManager</classname> or
+<classname>Query</classname> through the methods below.
             </para>
 <programlisting>
 public FetchPlan addFetchGroup (String group);
@@ -1827,8 +1859,10 @@
 public FetchPlan removeFetchGroups (String... groups);
 public FetchPlan removeFetchGroups (Collection groups);
 public FetchPlan resetFetchGroups ();
-public Collection&lt;String&gt; getFetchGroups (); 
+public Collection&lt;String&gt; getFetchGroups ();
 public void clearFetchGroups ();
+public FetchPlan setMaxFetchDepth(int depth);
+public int getMaxFetchDepth();
 </programlisting>
             <para>
 <xref linkend="ref_guide_runtime"/> details the <classname>
@@ -1845,7 +1879,7 @@
 ...
 
 OpenJPAQuery kq = OpenJPAPersistence.cast (em.createQuery (...));
-kq.getFetchPlan ().addFetchGroup ("detail");
+kq.getFetchPlan ().setMaxFetchDepth(3).addFetchGroup ("detail");
 List results = kq.getResultList ();
 </programlisting>
             </example>
@@ -1865,8 +1899,8 @@
             <para>
 In addition to controlling fetch configuration on a per-fetch-group basis, you
 can configure OpenJPA to include particular fields in the current fetch
-configuration. This allows you to add individual fields that are not in the
-default fetch group or in any other currently-active fetch groups to the set of
+plan. This allows you to add individual fields that are not in the
+default fetch group or in any other active fetch groups to the set of
 fields that will be eagerly loaded from the database.
             </para>
             <para>
@@ -1883,7 +1917,7 @@
 public FetchPlan removeFields (Class cls, String... fields);
 public FetchPlan removeFields (Collection fields);
 public FetchPlan removeFields (Class cls, Collection fields);
-public Collection&lt;String&gt; getFields (); 
+public Collection&lt;String&gt; getFields ();
 public void clearFields ();
 </programlisting>
             <para>
@@ -1994,15 +2028,16 @@
 objects, and then you have to retrieve the <classname>Address</classname> for
 each person, OpenJPA may make as many as 101 queries (the initial query, plus
 one for the address of each person returned). Or if some of the <classname>
-Person</classname> instances turn out to be <classname>Employee</classname>
s,
+Person</classname> instances turn out to be <classname>Employee</classname>s,
 where <classname>Employee</classname> has additional data in its own joined
 table, OpenJPA once again might need to make extra database trips to access the
 additional employee data. With eager fetching, OpenJPA can reduce these cases to
 a single query.
         </para>
         <para>
-Eager fetching only affects relations in the fetch groups being loaded (see
-<xref linkend="ref_guide_fetch"/> ). In other words, relations that would
+Eager fetching only affects relations in the active fetch groups, and is limited
+by the declared maximum fetch depth and field recursion depth (see
+<xref linkend="ref_guide_fetch"/>). In other words, relations that would
 not normally be loaded immediately when retrieving an object or accessing a
 field are not affected by eager fetching. In our example above, the address of
 each person would only be eagerly fetched if the query were configured to
@@ -2072,8 +2107,7 @@
 Some databases may not support UNIONs or outer joins. Also, OpenJPA can not use
 outer joins if you have set the <link linkend="openjpa.jdbc.DBDictionary">
 <literal> DBDictionary</literal></link>'s <literal>JoinSyntax</literal>
to
-<literal>traditional</literal>. See <xref linkend="ref_guide_dbsetup_sql92"/>
-.
+<literal>traditional</literal>. See <xref linkend="ref_guide_dbsetup_sql92"/>.
                     </para>
                 </note>
             </listitem>
@@ -2291,13 +2325,6 @@
                 </listitem>
                 <listitem>
                     <para>
-Eager fetching can sometimes be <emphasis>less</emphasis> efficient than
-standard fetching when circular relations are included in the configured fetch
-groups.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
 Once OpenJPA eager-joins into a class, it cannot issue any further eager to-many
 joins or parallel selects from that class in the same query. To-one joins,
 however, can recurse to any level.
@@ -2316,276 +2343,10 @@
                     <para>
 OpenJPA cannot eagerly join to polymorphic relations to non-leaf classes in a
 table-per-class inheritance hierarchy. You can work around this restriction
-using the mapping extensions described in <xref linkend="nonpolymorphic"/>
-.
+using the mapping extensions described in <xref linkend="nonpolymorphic"/>.
                     </para>
                 </listitem>
             </itemizedlist>
-        </section>
-    </section>
-    <section id="ref_guide_lock_groups">
-        <title>
-            Lock Groups
-        </title>
-        <indexterm zone="ref_guide_lock_groups">
-            <primary>
-                locking
-            </primary>
-            <secondary>
-                lock groups
-            </secondary>
-        </indexterm>
-        <indexterm zone="ref_guide_lock_groups">
-            <primary>
-                lock groups
-            </primary>
-            <seealso>
-                locking
-            </seealso>
-        </indexterm>
-        <para>
-OpenJPA supports both optimistic and datastore locking strategies, but
-optimistic locking is the preferred approach in most applications. Typically,
-optimistic locking is performed at the object level of granularity. That is,
-changes to any part of the same object in concurrent transactions will result in
-an optimistic locking exception being thrown by the transaction that commits
-last. In many applications, this is acceptable. However, if your application has
-a high likelihood of concurrent writes to different parts of the same object,
-then it may be advantageous to use a finer-grained optimistic lock.
-Additionally, certain parts of an object model may be best modeled without any
-locking at all, or with a last-commit-wins strategy. It is for these types of
-situations that OpenJPA offers customizable optimistic lock groups, which allow
-you to achieve sub-object-level locking granularity.
-        </para>
-        <para>
-For example, an <classname>Employee</classname> class may have some fields
-configurable by the employee the object represents ( <literal> firstName
-</literal>, <literal>lastName</literal>, <literal> phoneNumber</literal>
), some
-that are only modifiable by that employee's manager ( <literal>salary</literal>
-, <literal>title</literal> ), and some in which concurrent updates are
-acceptable (a list of <literal> projects</literal> ). In such a model, you can
-greatly improve the success of concurrent updates in optimistic transactions by
-putting <literal>firstName</literal>, <literal>lastName</literal>,
and <literal>
-phoneNumber</literal> into one lock group, <literal>salary</literal> and
-<literal>title</literal> into another, and excluding the <literal>projects
-</literal> field from optimistic lock checks altogether.
-        </para>
-        <para>
-<phrase> You specify a field's lock group in JPA metadata with the
-<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroup.html">
-<classname>org.apache.openjpa.persistence.LockGroup</classname></ulink>
-annotation.</phrase> See <xref linkend="lock-group"/> for details on lock
-group metadata.
-        </para>
-        <example id="ref_guide_lock_groups_metadata">
-            <title>
-                Lock Group Metadata
-            </title>
-<programlisting>
-import org.apache.openjpa.persistence.*;
-
-@Entity
-public class Employee
-{
-    // default lock group
-    private String firstName;
-    private String lastName;
-    private String phoneNumber;
-
-    // named lock group
-    @LockGroup("corporate") private float  salary;
-    @LockGroup("corporate") private String title;
-
-    // no lock group; allow concurrent modifications
-    @LockGroup(LockGroup.NONE) private Set&lt;Project&gt; projects;
-
-    ...
-}
-</programlisting>
-        </example>
-        <para>
-Currently, lock groups are only supported when using number and timestamp
-version strategies. They are not supported in the state-comparison strategy,
-though you can still exclude fields from participating in optimistic versioning
-under this strategy by setting the their lock group to <literal>none</literal>.
-        </para>
-        <section id="ref_guide_lock_groups_and_subclasses">
-            <title>
-                Lock Groups and Subclasses
-            </title>
-            <indexterm zone="ref_guide_lock_groups_and_subclasses">
-                <primary>
-                    lock groups
-                </primary>
-                <secondary>
-                    subclasses
-                </secondary>
-            </indexterm>
-            <para>
-Due to mapping restrictions, subclasses cannot simply declare additional lock
-groups implicitly, as is done in the example shown above. Instead, the
-least-derived mapped type in the persistent hierarchy must list all lock groups
-that its children can use via the <phrase>
-<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroups.html">
-<classname> org.apache.openjpa.persistence.LockGroups</classname></ulink>
-annotation</phrase> For example, if the <classname>Employee</classname>
class in
-the last example extended <classname>Person</classname>, the metadata would
-have looked like so:
-            </para>
-            <example id="ref_guide_lock_groups_and_subclasses_metadata">
-                <title>
-                    Lock Group Metadata
-                </title>
-                <!-- ### -->
-<programlisting>
-import org.apache.openjpa.persistence.*;
-
-@Entity
-@LockGroups({"corporate"})
-public class Person
-{
-    // default lock group
-    private String firstName;
-    private String lastName;
-    private String phoneNumber;
-
-    ...
-}
-
-@Entity
-public class Employee
-    extends Person
-{
-    // named lock group
-    @LockGroup("corporate") private float  salary;
-    @LockGroup("corporate") private String title;
-
-    // no lock group; allow concurrent modifications
-    @LockGroup(LockGroup.NONE) private Set&lt;Project&gt; projects;
-
-    ...
-}
-</programlisting>
-<programlisting>
-public class Person
-{
-    private String firstName;
-    private String lastName;
-    private String phoneNumber;
-
-    ...
-}
-
-
-public class Employee
-    extends Person
-{
-    // these fields can only be set by the employee's manager
-    private float  salary;
-    private String title;
-
-    // this field might be updated concurrently by the employee,
-    // other team members, or the employee's manager
-    private Set projects;
-
-    ...
-}
-
-
-&lt;?xml version="1.0"?&gt;
-&lt;jdo&gt;
-  &lt;package name=""&gt;
-    &lt;class name="Person"&gt;
-      &lt;!-- here we list the lock groups that will be used by Employee --&gt;
-      &lt;extension vendor-name="openjpa" key="lock-groups" value="corporate"/&gt;
-    &lt;/class&gt;
-    &lt;class name="Employee"&gt;
-      &lt;!-- named lock group --&gt;
-      &lt;field name="salary"&gt;
-        &lt;extension vendor-name="openjpa" key="lock-group" value="corporate"/&gt;
-      &lt;/field&gt;
-      &lt;field name="title"&gt;
-        &lt;extension vendor-name="openjpa" key="lock-group" value="corporate"/&gt;
-      &lt;/field&gt;
-      &lt;!-- no lock group; allow concurrent modifications --&gt;
-      &lt;field name="projects"&gt;
-        &lt;collection element-type="Project"/&gt;
-        &lt;extension vendor-name="openjpa" key="lock-group" value="none"/&gt;
-      &lt;/field&gt;
-    &lt;/class&gt;
-  &lt;/package&gt;
-&lt;/jdo&gt;
-</programlisting>
-            </example>
-            <para>
-The exceptions to this rule are the <literal>none</literal> and <literal>
-default</literal> built-in lock groups. They can be used at any point in the
-inheritance hierarchy without pre-declaration. Additionally, the lock groups
-listing can contain lock groups that would otherwise be implicitly defined in
-the least-derived type metadata.
-            </para>
-        </section>
-        <section id="ref_guide_lock_group_mapping">
-            <title>
-                Lock Group Mapping
-            </title>
-            <indexterm zone="ref_guide_lock_group_mapping">
-                <primary>
-                    lock groups
-                </primary>
-                <secondary>
-                    mapping metadata
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_lock_group_mapping">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    version
-                </secondary>
-                <tertiary>
-                    lock group mapping
-                </tertiary>
-                <seealso>
-                    lock groups
-                </seealso>
-            </indexterm>
-            <para>
-When using custom lock groups with a relational database, OpenJPA will need a
-version column for each of the groups, instead of just one version column. This
-means that you must use surrogate versioning; you cannot use a version field.
-OpenJPA also currently requires that all the version columns for a given object
-be in the same table. Finally, it is only possible to use a single version
-strategy for a given object. That is, you cannot have one version number column
-and another timestamp version column.
-            </para>
-            <para>
-<phrase> Use the
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.VersionColumn(s)</classname>
-</ulink> annotation to specify the version column for each lock group in JPA
-mapping.</phrase>
-            </para>
-            <example id="ref_guide_lock_groups_mapping_ex">
-                <title>
-                    Mapping Lock Groups
-                </title>
-<programlisting>
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Entity
-@Table(name="EMP")
-@VersionColumns({
-    @VersionColumn(name="VERS_CORP" lockGroup="corporate"),
-    @VersionColumn(name="VERS")
-})
-public class Employee
-{
-    ...
-}
-</programlisting>
-            </example>
         </section>
     </section>
 </chapter>

Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml?view=diff&rev=447584&r1=447583&r2=447584
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml
(original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml
Mon Sep 18 14:57:52 2006
@@ -53,7 +53,7 @@
         </indexterm>
         <para>
 The JPA Overview describes the specification's standard detach and attach APIs
-in <xref linkend="jpa_overview_em_lifecycle"/>. This section enumerates 
+in <xref linkend="jpa_overview_em_lifecycle"/>. This section enumerates
 OpenJPA's enhancements to the standard behavior.
         </para>
         <section id="ref_guide_detach_behavior">
@@ -621,7 +621,7 @@
                         TCP Remote Commit Provider Configuration
                     </title>
 <programlisting>
-&lt;property name="openjpa.RemoteCommitProvider" 
+&lt;property name="openjpa.RemoteCommitProvider"
     value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/&gt;
 </programlisting>
                 </example>
@@ -685,9 +685,7 @@
 <classname> RemoteCommitProvider</classname></ulink> interface, possibly
by
 extending the
 <ulink url="../apidocs/org/apache/openjpa/event/AbstractRemoteCommitProvider.html">
-<classname>AbstractRemoteCommitProvider</classname></ulink> abstract class.
For
-details on particular customization needs, contact us at
-<ulink url="mailto:support@solarmetric.com"> support@solarmetric.com</ulink>.
+<classname>AbstractRemoteCommitProvider</classname></ulink> abstract class..
             </para>
         </section>
     </section>

Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/samples_guide.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/samples_guide.xml?view=diff&rev=447584&r1=447583&r2=447584
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/samples_guide.xml
(original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/samples_guide.xml
Mon Sep 18 14:57:52 2006
@@ -86,31 +86,23 @@
 enhancer:
                 </para>
                 <para>
-<userinput>openjpac -p persistence.xml Machine.java Crane.java Bulldozer.java
-Operator.java</userinput>
-                </para>
-                <para>
-or
-                </para>
-                <para>
-<userinput>jdoc -p jdo.properties Machine.java Crane.java Bulldozer.java
+<userinput>java org.apache.openjpa.enhance.PCEnhancer -p persistence.xml Machine.java
Crane.java Bulldozer.java
 Operator.java</userinput>
                 </para>
             </listitem>
             <listitem>
                 <para>
-Similarly, you should pass in the same argument to <literal>mappingtool
-</literal>:
+Similarly, you should pass in the same argument to <literal>org.apache.openjpa.jdbc.meta.MappingTool</literal>:
                 </para>
                 <para>
-<userinput>mappingtool -p persistence.xml -a buildSchema Machine.java
+<userinput>java org.apache.openjpa.jdbc.meta.MappingTool -p persistence.xml -a buildSchema
Machine.java
 Crane.java Bulldozer.java Operator.java</userinput>
                 </para>
                 <para>
 or
                 </para>
                 <para>
-<userinput>mappingtool -p jdo.properties -a buildSchema Machine.java Crane.java
+<userinput>java org.apache.openjpa.jdbc.meta.MappingTool -p jdo.properties -a buildSchema
Machine.java Crane.java
 Bulldozer.java Operator.java</userinput>
                 </para>
             </listitem>

Modified: incubator/openjpa/sandboxes/OPENJPA-24/pom.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/pom.xml?view=diff&rev=447584&r1=447583&r2=447584
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/pom.xml (original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/pom.xml Mon Sep 18 14:57:52 2006
@@ -86,6 +86,7 @@
         <module>openjpa-kernel</module>
         <module>openjpa-jdbc</module>
         <module>openjpa-xmlstore</module>
+        <module>openjpa-all</module>
         <module>openjpa-project</module>
     </modules>
     <profiles>
@@ -122,7 +123,46 @@
                 <module>openjpa-project</module>
             </modules>
         </profile>
+        <profile>
+            <!--                        
+                Javadoc profile. Docs can be built by running:
+                    mvn package -Dtest=false -Pjavadoc-profile,docbook-profile
+            -->  
+            <id>javadoc-profile</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-javadoc-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <phase>package</phase>
+                                <goals><goal>javadoc</goal></goals>
+                                <configuration>
+                                    <aggregate>true</aggregate>
+                                    <!-- <linksource>true</linksource> -->
+                                    <maxmemory>512m</maxmemory>
+                                    <links>
+                                        <link>http://java.sun.com/j2se/1.5.0/docs/api</link>
+                                        <link>http://java.sun.com/javaee/5/docs/api</link>
+                                        <link>http://jakarta.apache.org/commons/collections/api-release</link>
+                                    </links>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+            <activation>
+                <property>
+                    <name>builddocs</name>
+                    <value>true</value>
+                </property>
+            </activation>
+        </profile>
+
     </profiles>
+
     <repositories>
         <repository>
             <id>central</id>
@@ -183,24 +223,10 @@
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>taglist-maven-plugin</artifactId>
             </plugin>
-            <!--
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-javadoc-plugin</artifactId>
-                <configuration>
-                    <aggregate>true</aggregate>
-                    <linksource>true</linksource>
-                    <maxmemory>512m</maxmemory>
-                    <links>
-                        <link>http://java.sun.com/j2se/1.5.0/docs/api</link>
-                        <link>http://java.sun.com/javaee/5/docs/api</link>
-                        <link>http://jakarta.apache.org/commons/collections/api-release</link>
-                    </links>
-                </configuration>
-            </plugin>
-            -->
         </plugins>
     </reporting>
+
+
     <distributionManagement>
       <repository>
         <id>people.apache.org</id>



Mime
View raw message