You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by kw...@apache.org on 2014/05/15 00:22:26 UTC
svn commit: r908837 [34/37] -
/websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_oid.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_oid.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_oid.html Wed May 14 22:22:23 2014
@@ -0,0 +1,406 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>4. 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.3 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter 5. Persistent Classes"><link rel="prev" href="ref_guide_pc_interfaces.html" title="3. Managed Interfaces"><link rel="next" href="ref_guide_inverses.html" title="5. 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.
+ Object Identity
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc_interfaces.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Persistent Classes
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_inverses.html">Next</a></td></tr></table><hr></div><div class="section" title="4. Object Identity"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_oid">4.
+ 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="d5e12205"></a>
+ <p>
+OpenJPA makes several enhancements to JPA's standard entity identity.
+ </p>
+ <div class="section" title="4.1. Datastore Identity"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_datastore">4.1.
+ Datastore Identity
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12210"></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. Id">Section 2.3, “
+ Id
+ ”</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. OpenJPAEntityManager">Section 2.2, “
+ OpenJPAEntityManager
+ ”</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 5.4.
+ 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. Entities as Identity Fields"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_entitypk">4.2.
+ Entities as Identity Fields
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12241"></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 5.5.
+ 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. Identity Class">Section 2.1, “
+ Identity Class
+ ”</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">@MappedById</code> annotation.
+
+ </p>
+
+ <div class="example"><a name="ref_guide_pc_oid_entitypk_idcls"></a><p class="title"><b>Example 5.6.
+ 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 5.7.
+ 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
+ @MappedById("orderId") // The value element of the MappedById 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">MappedById</code> annotation must be applied to the relationship
+field <code class="literal">LineItem.order</code>.
+ </p>
+
+ </div>
+
+ <div class="section" title="4.3. Application Identity Tool"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_application">4.3.
+ Application Identity Tool
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12282"></a>
+ <a class="indexterm" name="d5e12286"></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. Application Identity Tool Ant Task">Section 1.3, “
+ Application Identity Tool Ant Task
+ ”</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 5.8.
+ 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. Command Line Configuration">Section 3, “
+ Command Line Configuration
+ ”</a>), including code formatting
+flags described in <a class="xref" href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format" title="3.1. Code Formatting">Section 3.1, “
+ Code Formatting
+ ”</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 <output directory></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 <true/t | false/f></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 <token></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 <id class name></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 <id class suffix></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. Persistent Class List">Section 1, “
+ Persistent Class List
+ ”</a>).
+ </p>
+ </div>
+ <div class="section" title="4.4. Autoassign / Identity Strategy Caveats"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_oid_pkgen_autoinc">4.4.
+ Autoassign / Identity Strategy Caveats
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12340"></a>
+ <a class="indexterm" name="d5e12343"></a>
+ <a class="indexterm" name="d5e12346"></a>
+ <p>
+<a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_gen" title="2.4. Generated Value">Section 2.4, “
+ Generated Value
+ ”</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. OracleDictionary Properties">Section 4.4, “
+ OracleDictionary Properties
+ ”</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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_inverses.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Managed Interfaces </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 5.
+ Managed Inverses
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_oid.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_reverse.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_reverse.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_reverse.html Wed May 14 22:22:23 2014
@@ -0,0 +1,446 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. 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.3 User's Guide"><link rel="up" href="ref_guide_mapping.html" title="Chapter 7. Mapping"><link rel="prev" href="ref_guide_mapping.html" title="Chapter 7. Mapping"><link rel="next" href="ref_guide_mapping_middle.html" title="3. 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.
+ Reverse Mapping
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping.html">Prev</a> </td><th width="60%" align="center">Chapter 7.
+ Mapping
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_mapping_middle.html">Next</a></td></tr></table><hr></div><div class="section" title="2. Reverse Mapping"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_reverse">2.
+ 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="d5e13652"></a>
+ <a class="indexterm" name="d5e13654"></a>
+ <a class="indexterm" name="d5e13657"></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. Meet-in-the-Middle Mapping">Section 3, “
+ Meet-in-the-Middle Mapping
+ ”</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. 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 7.8.
+ 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. XML Schema Format">Section 14, “
+ XML Schema Format
+ ”</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 7.9.
+ 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. 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. 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 <schema and table names></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. Schemas List">Section 12.1, “
+ Schemas List
+ ”</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 <package name></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 <output directory></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 <class | package | none></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 <true/t | false/f></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 <field | property></code>: Change access
+type for generated annotations. Defaults to field access.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-useSchemaName/-sn <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></code>: Set to
+true to use generic collections on OneToMany and ManyToMany relations.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-useDatastoreIdentity/-ds <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <suffix></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 <type mapping></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 <class name></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. Customizing Reverse Mapping">
+below</a>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-customizerProperties/-cp <properties file or resource></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.<property name> <property value></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. Enhancement">Section 2, “
+ Enhancement
+ ”</a>).
+ </p>
+ </li></ol></div>
+ <p>
+Your persistent classes are now ready to access your existing schema.
+ </p>
+ <div class="section" title="2.1. Customizing Reverse Mapping"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_reverse_custom">2.1.
+ 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"><table name>.table-type <type></code>: Override the
+default type of the table with name <code class="literal"><table name></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"><class name>.rename <new class name></code>: Override
+the given tool-generated name <code class="literal"><class name></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"><table name>.class-name <new class name></code>: Assign
+the given fully-qualified class name to the type created from the table with
+name <code class="literal"><table name></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"><class name>.identity <datastore | builtin | identity class
+name></code>: Set this property to <code class="literal">datastore</code> to use
+datastore identity for the class <code class="literal"><class name></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"><class name>.<field name>.rename <new field name>
+</code>: Override the tool-generated <code class="literal"><field name></code> in
+class <code class="literal"><class name></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"><table name>.<column name>.field-name <new field
+name></code>: Set the generated field name for the <code class="literal"><table
+name></code> table's <code class="literal"><column name></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"><class name>.<field name>.type <field type></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"><class name>.<field name>.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 7.10.
+ 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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_mapping_middle.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7.
+ Mapping
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3.
+ Meet-in-the-Middle Mapping
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_reverse.html
------------------------------------------------------------------------------
svn:mime-type = text/plain