openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From strub...@apache.org
Subject svn commit: r953480 [34/37] - in /websites/production/openjpa/content/builds/2.4.0: ./ apache-openjpa/ apache-openjpa/docs/
Date Mon, 01 Jun 2015 20:19:02 GMT
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_oid.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_oid.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_oid.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,406 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>4.&nbsp; Object Identity</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="prev" href="ref_guide_pc_interfaces.html" title="3.&nbsp;Managed Interfaces"><link rel="next" href="ref_guide_inverses.html" title="5.&nbsp; Managed Inverses"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.&nbsp;
+            Object Identity
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc_interfaces.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_inverses.html">Next</a></td></tr></table><hr></div><div class="section" title="4.&nbsp; Object Identity"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_oid">4.&nbsp;
+            Object Identity
+        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_pc_oid.html#ref_guide_pc_oid_datastore">4.1. 
+                Datastore Identity
+            </a></span></dt><dt><span class="section"><a href="ref_guide_pc_oid.html#ref_guide_pc_oid_entitypk">4.2. 
+                Entities as Identity Fields
+            </a></span></dt><dt><span class="section"><a href="ref_guide_pc_oid.html#ref_guide_pc_oid_application">4.3. 
+                Application Identity Tool
+            </a></span></dt><dt><span class="section"><a href="ref_guide_pc_oid.html#ref_guide_pc_oid_pkgen_autoinc">4.4. 
+                Autoassign / Identity Strategy Caveats
+            </a></span></dt></dl></div>
+        
+        <a class="indexterm" name="d5e12263"></a>
+        <p>
+OpenJPA makes several enhancements to JPA's standard entity identity.
+        </p>
+        <div class="section" title="4.1.&nbsp; Datastore Identity"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_datastore">4.1.&nbsp;
+                Datastore Identity
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12268"></a>
+            <p>
+The JPA specification requires you to declare one or more identity fields in
+your persistent classes. OpenJPA fully supports this form of object identity,
+called <span class="emphasis"><em>application</em></span> identity. OpenJPA, however, also
+supports <span class="emphasis"><em>datastore</em></span> identity. In datastore identity, you do
+not declare any primary key fields. OpenJPA manages the identity of your
+persistent objects for you through a surrogate key in the database.
+            </p>
+            <p>
+You can control how your JPA datastore identity value is generated through
+OpenJPA's
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/DataStoreId.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.DataStoreId</code></a> class
+annotation. This annotation has <code class="literal">strategy</code> and <code class="literal">
+generator</code> properties that mirror the same-named properties on the
+standard <code class="classname">javax.persistence.GeneratedValue</code> annotation
+described in <a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_id" title="2.3.&nbsp; Id">Section&nbsp;2.3, &#8220;
+                Id
+            &#8221;</a> of the JPA Overview.
+            </p>
+            <p>
+To retrieve the identity value of a datastore identity entity, use the
+<code class="methodname">OpenJPAEntityManager.getObjectId(Object entity)</code>
+method. See <a class="xref" href="ref_guide_runtime_jpa.html#ref_guide_runtime_em" title="2.2.&nbsp; OpenJPAEntityManager">Section&nbsp;2.2, &#8220;
+                OpenJPAEntityManager
+            &#8221;</a> for more information on
+the <code class="classname">OpenJPAEntityManager</code>.
+            </p>
+            <div class="example"><a name="ref_guide_pc_oid_datastoreentityex"></a><p class="title"><b>Example&nbsp;5.4.&nbsp;
+                    JPA Datastore Identity Metadata
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@DataStoreId
+public class LineItem {
+
+    ... no @Id fields declared ...
+}
+</pre>
+            </div></div><br class="example-break">
+            <p>
+Internally, OpenJPA uses the public
+<a class="ulink" href="../javadoc/org/apache/openjpa/util/Id.html" target="_top"><code class="classname">
+org.apache.openjpa.util.Id</code></a> class for datastore identity
+objects. When writing OpenJPA plugins, you can manipulate datastore identity
+objects by casting them to this class. You can also create your own <code class="classname">
+Id</code> instances and pass them to any internal OpenJPA method that
+expects an identity object.
+            </p>
+            <p>
+In JPA, you will never see <code class="classname">Id</code> instances directly.
+Instead, calling <code class="classname">OpenJPAEntityManager.getObjectId</code> on a
+datastore identity object will return the <code class="classname">Long</code> surrogate
+primary key value for that object. You can then use this value in calls to
+<code class="classname">EntityManager.find</code> for subsequent lookups of the same
+record.
+            </p>
+        </div>
+        <div class="section" title="4.2.&nbsp; Entities as Identity Fields"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_entitypk">4.2.&nbsp;
+                Entities as Identity Fields
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12299"></a>
+            <p>
+OpenJPA allows <code class="literal">ManyToOne</code> and <code class="literal">OneToOne</code> 
+relations to be identity fields.  To identify a relation field as an identity
+field, simply annotate it with both the <code class="literal">@ManyToOne</code> or
+<code class="literal">@OneToOne</code> relation annotation and the <code class="literal">@Id</code>
+identity annotation.
+            </p>
+            <p>
+When finding an entity identified by a relation, pass the id of the 
+<span class="emphasis"><em>relation</em></span> to the <code class="methodname">EntityManager.find</code>
+method:
+            </p>
+            <div class="example"><a name="ref_guide_pc_oid_entitypk_simplefind"></a><p class="title"><b>Example&nbsp;5.5.&nbsp;
+                    Finding an Entity with an Entity Identity Field
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+public Delivery createDelivery(Order order) {
+    Delivery delivery = new Delivery();
+    delivery.setId(order);
+    delivery.setDelivered(new Date());
+    return delivery;
+}
+
+public Delivery findDelivery(EntityManager em, Order order) {
+    // use the identity of the related instance 
+    return em.find(Delivery.class, order.getId());
+}
+</pre>    
+            </div></div><br class="example-break">
+            <p>
+When your entity has multiple identity fields, at least one of which is a 
+relation to another entity, you can use an identity class (see 
+<a class="xref" href="jpa_overview_pc_identity.html#jpa_overview_pc_identitycls" title="2.1.&nbsp; Identity Class">Section&nbsp;2.1, &#8220;
+                Identity Class
+            &#8221;</a> in the JPA Overview), or 
+an embedded identity object.  Identity class fields corresponding to
+entity identity fields should be of the same type as the related entity's 
+identity. If an embedded identity object is used, you must annotate the 
+relation field with both the <code class="literal">@ManyToOne</code> or
+<code class="literal">@OneToOne</code> relation annotation and the 
+<code class="literal">@MapsId</code> annotation.
+
+            </p>
+            
+            <div class="example"><a name="ref_guide_pc_oid_entitypk_idcls"></a><p class="title"><b>Example&nbsp;5.6.&nbsp;
+                    Id Class for Entity Identity Fields
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+@Entity
+public class Order {
+
+    @Id
+    private long id;
+
+    ... 
+}
+
+	/**
+	 * LineItem uses a compound primary key. Part of the compound key 
+	 * LineItemId is relation or reference to Order instance.
+	**/   
+@Entity
+@IdClass(LineItemId.class)
+public class LineItem {
+    
+    @Id
+    private int index;
+
+    @Id
+    @ManyToOne
+    private Order order;
+
+    ...
+}
+
+public class LineItemId {
+
+    public int index;
+    public long order; // same type as identity of Order i.e Order.id
+                       // also the variable name must match the name of the
+                       // variable in LineItem that refers to Order.
+}
+</pre>    
+            </div></div><br class="example-break">
+            <p>
+In the example above, if <code class="classname">Order</code> had used an identity 
+class <code class="classname">OrderId</code> in place of a simple <code class="classname">long
+</code> value, then the <code class="literal">LineItemId.order</code> field would
+have been of type <code class="classname">OrderId</code>.
+            </p>
+            
+            <div class="example"><a name="ref_guide_pc_oid_entitypk_embeded_id"></a><p class="title"><b>Example&nbsp;5.7.&nbsp;
+                    Embedded Id for Entity Identity Fields
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+@Entity
+public class Order {
+
+    @Id
+    private long id;
+
+    ... 
+}
+
+	/**
+	 * LineItem uses a compound primary key. Part of the compound key 
+	 * LineItemId is relation or reference to Order instance.
+	**/   
+@Entity
+public class LineItem {
+    
+    @EmbeddedId LineItemId id;
+
+    @ManyToOne
+    @MapsId("orderId")     // The value element of the MapsId annotation 
+                           // must be used to specify the name of the primary
+                           // key attribute to which the relationship  
+                           // corresponds. If the primary key referenced by  
+                           // the relationship attribute is of the same Java  
+                           // type as the dependent's primary key, then the 
+                           // value element is not specified.
+    private Order order;
+
+    ...
+}
+
+@Embeddable
+public class LineItemId {
+
+    public int index;
+    public long orderId; 
+}
+</pre>    
+            </div></div><br class="example-break">
+
+            <p>
+In the example above, the <code class="classname">LineItem</code> uses an embedded id to  
+represent its primary key. The primary key attribute corresponding to the 
+relationship in the <code class="classname">LineItemId</code> must be of the same 
+type as the primary key of the <code class="classname">Order</code>. The 
+<code class="literal">MapsId</code> annotation must be applied to the relationship 
+field <code class="literal">LineItem.order</code>.
+            </p>
+            
+        </div>
+        
+        <div class="section" title="4.3.&nbsp; Application Identity Tool"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_application">4.3.&nbsp;
+                Application Identity Tool
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12340"></a>
+            <a class="indexterm" name="d5e12344"></a>
+            <p>
+If you choose to use application identity, you may want to take advantage of
+OpenJPA's application identity tool. The application
+identity tool generates Java code implementing the identity class for any
+persistent type using application identity. The code satisfies all the
+requirements the specification places on identity classes. You can use it as-is,
+or simply use it as a starting point, editing it to meet your needs.
+            </p>
+            <p>
+Before you can run the application identity tool on a persistent class, the
+class must be compiled and must have complete metadata. All primary key fields
+must be marked as such in the metadata.
+            </p>
+            <p>
+In JPA metadata, do not attempt to specify the <code class="literal">@IdClass</code>
+annotation unless you are using the application identity tool to overwrite an
+existing identity class. Attempting to set the value of the <code class="literal">@IdClass
+</code> to a non-existent class will prevent your persistent class from
+compiling. Instead, use the <code class="literal">-name</code> or <code class="literal">-suffix
+</code> options described below to tell OpenJPA what name to give your
+generated identity class. Once the application identity tool has generated the
+class code, you can set the <code class="literal">@IdClass</code> annotation.
+            </p>
+            <p>
+The application identity tool can be invoked via its Java class,
+<a class="ulink" href="../javadoc/org/apache/openjpa/enhance/ApplicationIdTool" target="_top">
+<code class="classname">org.apache.openjpa.enhance.ApplicationIdTool</code></a>.
+            </p>
+            <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+                <p>
+<a class="xref" href="ref_guide_integration.html#ref_guide_integration_appidtool" title="1.3.&nbsp; Application Identity Tool Ant Task">Section&nbsp;1.3, &#8220;
+                Application Identity Tool Ant Task
+            &#8221;</a> describes the
+application identity tool's Ant task.
+                </p>
+            </div>
+            <div class="example"><a name="ref_guide_pc_appid_appidtool"></a><p class="title"><b>Example&nbsp;5.8.&nbsp;
+                    Using the Application Identity Tool
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+java org.apache.openjpa.enhance.ApplicationIdTool -s Id Magazine.java
+</pre>
+            </div></div><br class="example-break">
+            <p>
+The application identity tool accepts the standard set of command-line arguments
+defined by the configuration framework (see
+<a class="xref" href="ref_guide_conf_devtools.html" title="3.&nbsp; Command Line Configuration">Section&nbsp;3, &#8220;
+            Command Line Configuration
+        &#8221;</a>), including code formatting
+flags described in <a class="xref" href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format" title="3.1.&nbsp; Code Formatting">Section&nbsp;3.1, &#8220;
+                Code Formatting
+            &#8221;</a>. It
+also accepts the following arguments:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                    <p>
+<code class="literal">-directory/-d &lt;output directory&gt;</code>: Path to the output
+directory. If the directory does not match the generated oid class' package, the
+package structure will be created beneath the directory. If not specified, the
+tool will first try to find the directory of the <code class="filename">.java</code> file
+for the persistence-capable class, and failing that will use the current
+directory.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">-ignoreErrors/-i &lt;true/t | false/f&gt;</code>: If <code class="literal">false
+</code>, an exception will be thrown if the tool is run on any class that
+does not use application identity, or is not the base class in the inheritance
+hierarchy (recall that subclasses never define the application identity class;
+they inherit it from their persistent superclass).
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">-token/-t &lt;token&gt;</code>: The token to use to separate
+stringified primary key values in the string form of the object id. This option
+is only used if you have multiple primary key fields. It defaults to "::".
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">-name/-n &lt;id class name&gt;</code>: The name of the identity
+class to generate. If this option is specified, you must run the tool on exactly
+one class. If the class metadata already names an object id class, this option
+is ignored. If the name is not fully qualified, the persistent class' package is
+prepended to form the qualified name.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">-suffix/-s &lt;id class suffix&gt;</code>: A string to suffix each
+persistent class name with to form the identity class name. This option is
+overridden by <code class="literal">-name</code> or by any object id class specified in
+metadata.
+                    </p>
+                </li></ul></div>
+            <p>
+Each additional argument to the tool must be one of the following:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                    <p>
+The full name of a persistent class.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+The .java file for a persistent class.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+The <code class="filename">.class</code> file of a persistent class.
+                    </p>
+                </li></ul></div>
+            <p>
+If you do not supply any arguments to the tool, it will act on the classes in
+your persistent classes list (see <a class="xref" href="ref_guide_pc.html#ref_guide_pc_pcclasses" title="1.&nbsp; Persistent Class List">Section&nbsp;1, &#8220;
+            Persistent Class List
+        &#8221;</a>).
+            </p>
+        </div>
+        <div class="section" title="4.4.&nbsp; Autoassign / Identity Strategy Caveats"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_pkgen_autoinc">4.4.&nbsp;
+                Autoassign / Identity Strategy Caveats
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12398"></a>
+            <a class="indexterm" name="d5e12401"></a>
+            <a class="indexterm" name="d5e12404"></a>
+            <p>
+<a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_gen" title="2.4.&nbsp; Generated Value">Section&nbsp;2.4, &#8220;
+                Generated Value
+            &#8221;</a> explains how to use JPA's
+<code class="literal">IDENTITY</code> generation type to automatically assign field
+values. However, here are some additional caveats you should be aware of when
+using <code class="literal">IDENTITY</code> generation:
+            </p>
+            <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+                    <p>
+Your database must support auto-increment / identity columns, or some equivalent
+(see <a class="xref" href="ref_guide_dbsetup_dbsupport.html#ref_guide_dbsetup_dbsupport_oracle" title="4.4.&nbsp; OracleDictionary Properties">Section&nbsp;4.4, &#8220;
+                OracleDictionary Properties
+            &#8221;</a> for how to
+configure a combination of triggers and sequences to fake auto-increment support
+in Oracle database).
+                    </p>
+                </li><li class="listitem">
+                    <p>
+Auto-increment / identity columns must be an integer or long integer type.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+Databases support auto-increment / identity columns to varying degrees. Some do
+not support them at all. Others only allow a single such column per table, and
+require that it be the primary key column. More lenient databases may allow
+non-primary key auto-increment columns, and may allow more than one per table.
+See your database documentation for details.
+                    </p>
+                </li></ol></div>
+        </div>
+    </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_pc_interfaces.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_inverses.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.&nbsp;Managed Interfaces&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.&nbsp;
+            Managed Inverses
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_oid.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_reverse.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_reverse.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_reverse.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,446 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>2.&nbsp; Reverse Mapping</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_mapping.html" title="Chapter&nbsp;7.&nbsp; Mapping"><link rel="prev" href="ref_guide_mapping.html" title="Chapter&nbsp;7.&nbsp; Mapping"><link rel="next" href="ref_guide_mapping_middle.html" title="3.&nbsp; Meet-in-the-Middle Mapping"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.&nbsp;
+            Reverse Mapping
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;7.&nbsp;
+        Mapping
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_mapping_middle.html">Next</a></td></tr></table><hr></div><div class="section" title="2.&nbsp; Reverse Mapping"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_reverse">2.&nbsp;
+            Reverse Mapping
+        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_pc_reverse.html#ref_guide_pc_reverse_custom">2.1. 
+                Customizing Reverse Mapping
+            </a></span></dt></dl></div>
+        
+        <a class="indexterm" name="d5e13710"></a>
+        <a class="indexterm" name="d5e13712"></a>
+        <a class="indexterm" name="d5e13715"></a>
+        <p>
+OpenJPA includes a <span class="emphasis"><em>reverse mapping</em></span> tool for generating
+persistent class definitions, complete with metadata, from an existing database
+schema. You do not have to use the reverse mapping tool to access an existing
+schema; you are free to write your classes and mappings yourself, as described
+in <a class="xref" href="ref_guide_mapping_middle.html" title="3.&nbsp; Meet-in-the-Middle Mapping">Section&nbsp;3, &#8220;
+            Meet-in-the-Middle Mapping
+        &#8221;</a>. The reverse mapping tool,
+however, can give you an excellent starting point from which to grow your
+persistent classes.
+        </p>
+        <p>
+To use the reverse mapping tool, follow the steps below:
+        </p>
+        <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+                <p>
+Use the <a class="link" href="ref_guide_schema_schematool.html" title="13.&nbsp; Schema Tool"> schema tool</a> to
+export your current schema to an XML schema file. You can skip this step and the
+next step if you want to run the reverse mapping tool directly against the
+database.
+                </p>
+                <div class="example"><a name="ref_guide_pc_reverse_schemagen"></a><p class="title"><b>Example&nbsp;7.8.&nbsp;
+                        Reflection with the Schema Tool
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml
+</pre>
+                </div></div><br class="example-break">
+            </li><li class="listitem">
+                <p>
+Examine the generated schema file. JDBC drivers often provide incomplete or
+faulty metadata, in which case the file will not exactly match the actual
+schema. Alter the XML file to match the true schema. The XML format for the
+schema file is described in <a class="xref" href="ref_guide_schema_xml.html" title="14.&nbsp; XML Schema Format">Section&nbsp;14, &#8220;
+            XML Schema Format
+        &#8221;</a>.
+                </p>
+                <p>
+After fixing any errors in the schema file, modify the XML to include foreign
+keys between all relations. The schema tool will have automatically detected
+existing foreign key constraints; many schemas, however, do not employ database
+foreign keys for every relation. By manually adding any missing foreign keys,
+you will give the reverse mapping tool the information it needs to generate the
+proper relations between the persistent classes it creates.
+                </p>
+            </li><li class="listitem">
+                <p>
+Run the reverse mapping tool on the finished schema file. If you do not supply
+the schema file to reverse map, the tool will run directly against the schema in
+the database. The tool can be run via its Java class,
+<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/ReverseMappingTool" target="_top">
+<code class="classname">org.apache.openjpa.jdbc.meta.ReverseMappingTool</code></a>.
+                </p>
+                <div class="example"><a name="ref_guide_pc_reverse_reversemappingtool"></a><p class="title"><b>Example&nbsp;7.9.&nbsp;
+                        Using the Reverse Mapping Tool
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -d ~/src -cp customizer.properties schema.xml
+</pre>
+                </div></div><br class="example-break">
+                <p>
+In addition to OpenJPA's <a class="link" href="ref_guide_conf_devtools.html" title="3.&nbsp; Command Line Configuration">standard
+configuration flags</a>, including
+<a class="link" href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format" title="3.1.&nbsp; Code Formatting">code formatting options</a>,
+the reverse mapping tool recognizes the following command line arguments:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                        <p>
+<code class="literal">-schemas/-s &lt;schema and table names&gt;</code>: A
+comma-separated list of schema and table names to reverse map, if no XML schema
+file is supplied. Each element of the list must follow the naming conventions
+for the <code class="literal">openjpa.jdbc.Schemas</code> property described in
+<a class="xref" href="ref_guide_schema_info.html#ref_guide_schema_info_list" title="12.1.&nbsp; Schemas List">Section&nbsp;12.1, &#8220;
+                Schemas List
+            &#8221;</a>. In fact, if this flag is
+omitted, it defaults to the value of the <code class="literal">Schemas</code> property. If
+the <code class="literal">Schemas</code> property is not defined, all schemas will be
+reverse-mapped.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-package/-pkg &lt;package name&gt;</code>: The package name of the
+generated classes. If no package name is given, the generated code will not
+contain package declarations.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-directory/-d &lt;output directory&gt;</code>: All generated code
+and metadata will be written to the directory at this path. If the path does not
+match the package of a class, the package structure will be created beneath this
+directory. Defaults to the current directory.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-metadata/-md &lt;class | package | none&gt;</code>: Specify the
+level the metadata should be generated at. Defaults to generating a single
+package-level metadata file. Set to <code class="literal">none</code> to disable orm.xml
+generation.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-annotations/-ann &lt;true/t | false/f&gt;</code>: Set to
+<code class="literal">true</code> to
+generate JPA annotations in generated Java classes.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-accessType/-access &lt;field | property&gt;</code>: Change access
+type for generated annotations. Defaults to field access.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-useSchemaName/-sn &lt;true/t | false/f&gt;</code>: Set this flag
+to <code class="literal">true</code> to include the schema as well as table name in the
+name of each generated class. This can be useful when dealing with multiple
+schemas with same-named tables.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-useSchemaElement/-se &lt;true/t | false/f&gt;</code>: Set this
+flag to <code class="literal">false</code> to exclude the schema name from the 
+<code class="literal">@Table</code> annotation in the generated class for each table.
+If set to <code class="literal">false</code>, the schema name will also be removed from
+the corresponding XML mapping files (orm.xml) that are generated by the tool.
+The initialized value is true (in order to preserve backwards compatibility).
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-useForeignKeyName/-fkn &lt;true/t | false/f&gt;</code>: Set this
+flag to <code class="literal">true</code> if you would like field names for relations to
+be based on the database foreign key name. By default, relation field names are
+derived from the name of the related class.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-nullableAsObject/-no &lt;true/t | false/f&gt;</code>: By default,
+all non-foreign key columns are mapped to primitives. Set this flag to <code class="literal">
+true</code> to generate primitive wrapper fields instead for columns that
+allow null values.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-blobAsObject/-bo &lt;true/t | false/f&gt;</code>: By default, all
+binary columns are mapped to <code class="classname">byte[]</code> fields. Set this flag
+to <code class="literal">true</code> to map them to <code class="classname">Object</code> fields
+instead. Note that when mapped this way, the column is presumed to contain a
+serialized Java object.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-primaryKeyOnJoin/-pkj &lt;true/t | false/f&gt;</code>: The
+standard reverse mapping tool behavior is to map all tables with primary keys to
+persistent classes. If your schema has primary keys on many-many join tables as
+well, set this flag to <code class="literal">true</code> to avoid creating classes for
+those tables.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-inverseRelations/-ir &lt;true/t | false/f&gt;</code>: Set to
+<code class="literal">false</code> to prevent the creation of inverse 1-many/1-1 relations
+for every many-1/1-1 relation detected.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-useGenericCollections/-gc &lt;true/t | false/f&gt;</code>: Set to
+true to use generic collections on OneToMany and ManyToMany relations.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-useDatastoreIdentity/-ds &lt;true/t | false/f&gt;</code>: Set to
+<code class="literal">true</code> to use datastore identity for tables that have single
+numeric primary key columns. The tool typically uses application identity for
+all generated classes.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-useBuiltinIdentityClass/-bic &lt;true/t | false/f&gt;</code>: Set
+to <code class="literal">false</code> to prevent the tool from using built-in application
+identity classes when possible. This will force the tool to create custom
+application identity classes even when there is only one primary key column.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-innerIdentityClasses/-inn &lt;true/t | false/f&gt;</code>: Set to
+<code class="literal">true</code> to have any generated application identity classes be
+created as static inner classes within the persistent classes. Defaults to
+<code class="literal">false</code>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-identityClassSuffix/-is &lt;suffix&gt;</code>: Suffix to append to
+class names to form application identity class names, or for inner identity
+classes, the inner class name. Defaults to <code class="literal">Id</code>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-typeMap/-typ &lt;type mapping&gt;</code>: A string that specifies
+the default Java classes to generate for each SQL type that is seen in the
+schema. The format is <code class="literal"> SQLTYPE1=JavaClass1,SQLTYPE2=JavaClass2
+</code>. The SQL type name first looks for a customization based on <code class="literal">
+SQLTYPE(SIZE,PRECISION)</code>, then <code class="literal">SQLTYPE(SIZE)</code>, then
+<code class="literal">SQLTYPE</code>. So if a column whose type name is
+<code class="literal">CHAR</code> is found, it will first look for the <code class="literal">
+CHAR(50,0)</code> type name specification, then it will look for <code class="literal">
+CHAR(50)</code>, and finally it will just look for <code class="literal">CHAR</code>.
+For example, to generate a char array for every <code class="literal">CHAR</code> column
+whose size is exactly 50, and to generate a <code class="literal">short</code> for every
+type name of <code class="literal">INTEGER</code>, you might specify: <code class="literal">
+CHAR(50)=char[],INTEGER=short</code>. Note that since various databases
+report different type names differently, one database's type name specification
+might not work for another database. Enable <code class="literal">TRACE</code> level
+logging on the <code class="literal">MetaData</code> channel to track which type names
+OpenJPA is examining.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-customizerClass/-cc &lt;class name&gt;</code>: The full class name
+of a
+<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html" target="_top">
+<code class="classname">org.apache.openjpa.jdbc.meta.ReverseCustomizer</code></a>
+customization plugin. If you do not specify a reverse customizer of your own,
+the system defaults to a
+<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html" target="_top">
+<code class="classname">PropertiesReverseCustomizer</code></a>. This customizer
+allows you to specify simple customization options in the properties file given
+with the <code class="literal">-customizerProperties</code> flag below. We present the
+available property keys <a class="link" href="ref_guide_pc_reverse.html#ref_guide_pc_reverse_custom" title="2.1.&nbsp; Customizing Reverse Mapping">
+below</a>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-customizerProperties/-cp &lt;properties file or resource&gt;</code>
+: The path or resource name of a properties file to pass to the reverse
+customizer on initialization.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">-customizer./-c.&lt;property name&gt; &lt;property value&gt;</code>
+: The given property name will be matched with the corresponding Java bean
+property in the specified reverse customizer, and set to the given value.
+                        </p>
+                    </li></ul></div>
+                <p>
+Running the tool will generate <code class="filename">.java</code> files for each
+generated class (and its application identity class, if applicable), along with
+JPA annotations (if enabled by setting <code class="literal">-annotations true</code>),
+or an <code class="filename">orm.xml</code> file (if not disabled with <code class="literal">
+-metadata none</code>) containing the corresponding persistence metadata.
+                </p>
+            </li><li class="listitem">
+                <p>
+Examine the generated class, metadata, and mapping information, and modify it as
+necessary. Remember that the reverse mapping tool only provides a starting
+point, and you are free to make whatever modifications you like to the code it
+generates.
+                </p>
+                <p>
+After you are satisfied with the generated classes and their mappings, you
+should first compile the classes with <code class="literal">javac</code>, <code class="literal">
+jikes</code>, or your favorite Java compiler. Make sure the classes are
+located in the directory corresponding to the <code class="literal">-package</code> flag
+you gave the reverse mapping tool.  Next, if you have generated an <code class="filename">
+orm.xml</code>, move that file to a <code class="filename">META-INF</code> directory
+within a directory in your classpath.  Finally, enhance the classes
+if necessary (see <a class="xref" href="ref_guide_pc_enhance.html" title="2.&nbsp; Enhancement">Section&nbsp;2, &#8220;
+            Enhancement
+        &#8221;</a>).
+                </p>
+            </li></ol></div>
+        <p>
+Your persistent classes are now ready to access your existing schema.
+        </p>
+        <div class="section" title="2.1.&nbsp; Customizing Reverse Mapping"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_reverse_custom">2.1.&nbsp;
+                Customizing Reverse Mapping
+            </h3></div></div></div>
+            
+            <p>
+The <code class="classname">org.apache.openjpa.jdbc.meta.ReverseCustomizer</code> plugin
+interface allows you to customize the reverse mapping process. See the class
+<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html" target="_top">
+Javadoc</a> for details on the hooks that this interface provides. Specify
+the concrete plugin implementation to use with the <code class="literal">
+-customizerClass/-cc</code> command-line flag, described in the preceding
+section.
+            </p>
+            <p>
+By default, the reverse mapping tool uses a
+<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html" target="_top">
+<code class="classname">org.apache.openjpa.jdbc.meta.PropertiesReverseCustomizer</code>
+</a>. This customizer allows you to perform relatively simple
+customizations through the properties file named with the <code class="literal">
+-customizerProperties</code> tool flag. The customizer recognizes the
+following properties:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                    <p>
+<code class="literal">&lt;table name&gt;.table-type &lt;type&gt;</code>: Override the
+default type of the table with name <code class="literal">&lt;table name&gt;</code>.
+Legal values are:
+                    </p>
+                    <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
+                            <p>
+<code class="literal">base</code>: Primary table for a base class.
+                            </p>
+                        </li><li class="listitem">
+                            <p>
+<code class="literal">secondary</code>: Secondary table for a class. The table must have
+a foreign key joining to a class table.
+                            </p>
+                        </li><li class="listitem">
+                            <p>
+<code class="literal">secondary-outer</code>: Outer-joined secondary table for a class.
+The table must have a foreign key joining to a class table.
+                            </p>
+                        </li><li class="listitem">
+                            <p>
+<code class="literal">association</code>: Association table. The table must have two
+foreign keys to class tables.
+                            </p>
+                        </li><li class="listitem">
+                            <p>
+<code class="literal">collection</code>: Collection table. The table must have one
+foreign key to a class table and one data column.
+                            </p>
+                        </li><li class="listitem">
+                            <p>
+<code class="literal">subclass</code>: A joined subclass table. The table must have a
+foreign key to the superclass' table.
+                            </p>
+                        </li><li class="listitem">
+                            <p>
+<code class="literal">none</code>: The table should not be reverse-mapped.
+                            </p>
+                        </li></ul></div>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;class name&gt;.rename &lt;new class name&gt;</code>: Override
+the given tool-generated name <code class="literal">&lt;class name&gt;</code> with a new
+value. Use full class names, including package. You are free to rename a class
+to a new package. Specify a value of <code class="literal">none</code> to reject the class
+and leave the corresponding table unmapped.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;table name&gt;.class-name &lt;new class name&gt;</code>: Assign
+the given fully-qualified class name to the type created from the table with
+name <code class="literal">&lt;table name&gt;</code>. Use a value of <code class="literal">none
+</code> to prevent reverse mapping this table. This property can be used in
+place of the <code class="literal">rename</code> property.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;class name&gt;.identity &lt;datastore | builtin | identity class
+name&gt;</code>: Set this property to <code class="literal">datastore</code> to use
+datastore identity for the class <code class="literal">&lt;class name&gt;</code>,
+<code class="literal">builtin</code> to use a built-in identity class, or the desired
+application identity class name. Give full class names, including package. You
+are free to change the package of the identity class this way. If the persistent
+class has been renamed, use the new class name for this property key. Remember
+that datastore identity requires a table with a single numeric primary key
+column, and built-in identity requires a single primary key column of any type.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;class name&gt;.&lt;field name&gt;.rename &lt;new field name&gt;
+</code>: Override the tool-generated <code class="literal">&lt;field name&gt;</code> in
+class <code class="literal">&lt;class name&gt;</code> with the given name. Use the field
+owner's full class name in the property key. If the field owner's class was
+renamed, use the new class name. The property value should be the new field
+name, without the preceding class name. Use a value of <code class="literal">none</code>
+to reject the generated mapping and remove the field from the class.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;table name&gt;.&lt;column name&gt;.field-name &lt;new field
+name&gt;</code>: Set the generated field name for the <code class="literal">&lt;table
+name&gt;</code> table's <code class="literal">&lt;column name&gt;</code> column. If
+this is a multi-column mapping, any of the columns can be used. Use a value of
+<code class="literal">none</code> to prevent the column and its associated columns from
+being reverse-mapped.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;class name&gt;.&lt;field name&gt;.type &lt;field type&gt;</code>
+: The type to give the named field. Use full class names. If the field or the
+field's owner class has been renamed, use the new name.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">&lt;class name&gt;.&lt;field name&gt;.value</code>: The initial
+value for the named field. The given string will be placed as-is in the
+generated Java code, so be sure it is valid Java. If the field or the field's
+owner class has been renamed, use the new name.
+                    </p>
+                </li></ul></div>
+            <p>
+All property keys are optional; if not specified, the customizer keeps the
+default value generated by the reverse mapping tool.
+            </p>
+            <div class="example"><a name="ref_guide_pc_reverse_custom_ex"></a><p class="title"><b>Example&nbsp;7.10.&nbsp;
+                    Customizing Reverse Mapping with Properties
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -cp custom.properties schema.xml
+</pre>
+                <p>
+Example <code class="filename">custom.properties</code>:
+                </p>
+<pre class="programlisting">
+com.xyz.TblMagazine.rename:             com.xyz.Magazine
+com.xyz.TblArticle.rename:              com.xyz.Article
+com.xyz.TblPubCompany.rename:           com.xyz.pub.Company
+com.xyz.TblSysInfo.rename:              none
+
+com.xyz.Magazine.allArticles.rename:    articles
+com.xyz.Magazine.articles.type:         java.util.Collection
+com.xyz.Magazine.articles.value:        new TreeSet()
+com.xyz.Magazine.identity:              datastore
+
+com.xyz.pub.Company.identity:           com.xyz.pub.CompanyId
+</pre>
+            </div></div><br class="example-break">
+        </div>
+    </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_mapping.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_mapping_middle.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;7.&nbsp;
+        Mapping
+    &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;3.&nbsp;
+            Meet-in-the-Middle Mapping
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_reverse.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message