From dev-return-5118-apmail-openjpa-dev-archive=openjpa.apache.org@openjpa.apache.org Fri Jul 27 19:26:33 2007 Return-Path: Delivered-To: apmail-openjpa-dev-archive@www.apache.org Received: (qmail 10056 invoked from network); 27 Jul 2007 19:26:32 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 27 Jul 2007 19:26:32 -0000 Received: (qmail 20998 invoked by uid 500); 27 Jul 2007 19:26:33 -0000 Delivered-To: apmail-openjpa-dev-archive@openjpa.apache.org Received: (qmail 20841 invoked by uid 500); 27 Jul 2007 19:26:32 -0000 Mailing-List: contact dev-help@openjpa.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@openjpa.apache.org Delivered-To: mailing list dev@openjpa.apache.org Received: (qmail 20832 invoked by uid 99); 27 Jul 2007 19:26:32 -0000 Received: from Unknown (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 27 Jul 2007 12:26:32 -0700 X-ASF-Spam-Status: No, hits=2.0 required=10.0 tests=HTML_MESSAGE,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of catalina.wei@gmail.com designates 66.249.82.237 as permitted sender) Received: from [66.249.82.237] (HELO wx-out-0506.google.com) (66.249.82.237) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 27 Jul 2007 19:26:27 +0000 Received: by wx-out-0506.google.com with SMTP id s7so839082wxc for ; Fri, 27 Jul 2007 12:26:06 -0700 (PDT) DKIM-Signature: a=rsa-sha1; c=relaxed/relaxed; d=gmail.com; s=beta; h=domainkey-signature:received:received:message-id:date:from:to:subject:in-reply-to:mime-version:content-type:references; b=pca+AhWF8aTEn5oPvlBmE7JYx0U1PaGdcZOngQ/6wS1kgn87nxapPrwjn0GKnFR1LzO8lnIDSLIdPbBSf6rPLdHtNTwMr8X+4w2iuIp4JlEAU1mw1VYP6CWbRgDmz3P4qGLfIB7fVatJ5GUWEyQ6gkP6W7nNq25zqzdq1zhsLcM= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta; h=received:message-id:date:from:to:subject:in-reply-to:mime-version:content-type:references; b=SR5HlShRvRpQy1g2Xjecl3Ac6ePWSAuxXDZZyRBxUspsp1oounPaUda/YUfErr3xiSmvan83ByxT9VlGHkxWsbUj22owdxHbrglmr2aCXV7D64Cis1Un+zPVwwUCeva0brVJOSyU4FMsP7hyKsJXqv9pVZpPAJshW0h1JaXkhPs= Received: by 10.70.89.1 with SMTP id m1mr5499173wxb.1185564366107; Fri, 27 Jul 2007 12:26:06 -0700 (PDT) Received: by 10.70.98.6 with HTTP; Fri, 27 Jul 2007 12:26:05 -0700 (PDT) Message-ID: Date: Fri, 27 Jul 2007 12:26:05 -0700 From: "catalina wei" To: dev@openjpa.apache.org Subject: Re: svn commit: r560330 [2/2] - /openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml In-Reply-To: <7262f25e0707271101s72fb812eg41b07908f4f8cb6f@mail.gmail.com> MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="----=_Part_7391_19768266.1185564365953" References: <20070727173826.7492F1A9820@eris.apache.org> <7262f25e0707271101s72fb812eg41b07908f4f8cb6f@mail.gmail.com> X-Virus-Checked: Checked by ClamAV on apache.org ------=_Part_7391_19768266.1185564365953 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline Hi, Patrick, Sorry about this mess and thanks for correcting it. The attached openjpa-project.patch looked GOOD. Probably the "irgnore white space diffs" got turned on when comparing the working copy with the latest revision in svn, but forgot to turn it off at commit time. We will be careful next time. Catalina On 7/27/07, Patrick Linskey wrote: > > Hi, > > These types of commits are really difficult to parse -- I find it hard > to believe that we really needed to change every line of the file. > Does anyone know of any way to put in place some sort of line-ending > restrictions, or otherwise avoid these sorts of commits? > > -Patrick > > On 7/27/07, wisneskid@apache.org wrote: > > > > Modified: > openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml > > URL: > http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml?view=diff&rev=560330&r1=560329&r2=560330 > > > ============================================================================== > > --- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml > (original) > > +++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml > Fri Jul 27 10:38:24 2007 > > @@ -1,3032 +1,3328 @@ > > - > > - > > - > > - > > - Mapping > > - > > - > > - > > - mapping metadata > > - > > - > > - > > -The JPA Overview's explains > > -object-relational mapping under JPA. This chapter reviews the mapping > utilities > > -OpenJPA provides and examines OpenJPA features that go beyond the JPA > > -specification. > > - > > -
> > - > > - Forward Mapping > > - > > - > > - > > - forward mapping > > - > > - > > - > > - > > - mapping tool > > - > > - > > - forward mapping > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - forward mapping > > - > > - > > - forward mapping > > - > > - > > - > > -Forward mapping is the process of creating > mappings and > > -their corresponding database schema from your object model. OpenJPA > supports > > -forward mapping through the mapping tool. The next > section > > -presents several common mapping tool use cases. You can invoke the tool > through > > -its Java class, > > - url="../javadoc/org/apache/openjpa/jdbc/meta/MappingTool"> > > -org.apache.openjpa.jdbc.meta.MappingTool. > > - > > - > > - > > - describes the > mapping > > -tool Ant task. > > - > > - > > - > > - > > - Using the Mapping Tool > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java > > - > > - > > - > > -In addition to the universal flags of the > > -configuration framework, > the > > -mapping tool accepts the following command line arguments: > > - > > - > > - > > - > > --schemaAction/-sa <add | refresh | drop | build | retain | > reflect | createDB | dropDB | import | export | none> > > -: The action to take on the schema. These options correspond > to the > > -same-named actions on the schema tool described in > > -. Actions can be composed > in a > > -comma-separated list. Unless you are running the mapping tool on all of > > -your persistent types at once or dropping a mapping, we strongly > > -recommend you use the default add action or the > > -build action. Otherwise you may end up inadvertently > > -dropping schema components that are used by classes you are not > > -currently running the tool over. > > - > > - > > - > > - > > --schemaFile/-sf <stdout | output file>: Use > this > > -option to write the planned schema to an XML document rather than > modify the > > -database. The document can then be manipulated and committed to the > database > > -with the schema > tool. > > - > > - > > - > > - > > --sqlFile/-sql <stdout | output file>: Use this > option > > -to write the planned schema modifications to a SQL script rather than > modify the > > -database. Combine this with a schemaAction of > build > > - to generate a script that recreates the schema for the > current > > -mappings, even if the schema already exists. > > - > > - > > - > > - > > --dropTables/-dt <true/t | false/f>: > Corresponds to the > > -same-named option on the schema tool. > > - > > - > > - > > - > > --dropSequences/-dsq <true/t | false/f>: > Corresponds to > > -the same-named option on the schema tool. > > - > > - > > - > > - > > --openjpaTables/-ot <true/t | false/f>: > Corresponds to > > -the same-named option on the schema tool. > > - > > - > > - > > - > > --ignoreErrors/-i <true/t | false/f>: > Corresponds to > > -the same-named option on the schema tool. > > - > > - > > - > > - > > --schemas/-s <schema and table names>: > Corresponds to > > -the same-named option on the schema tool. This option is ignored if > > > -readSchema is not set to true. > > - > > - > > - > > - > > --readSchema/-rs <true/t | false/f>: Set this > option to > > -true to read the entire existing schema when the > tool runs. > > -Reading the existing schema ensures that OpenJPA does not generate any > mappings > > -that use table, index, primary key, or foreign key names that conflict > with > > -existing names. Depending on the JDBC driver, though, it can be a slow > process > > -for large schemas. > > - > > - > > - > > - > > --primaryKeys/-pk <true/t | false/f>: Whether > to read > > -and manipulate primary key information of existing tables. Defaults to > false. > > - > > - > > - > > - > > --foreignKeys/-fk <true/t | false/f>: Whether > to read > > -and manipulate foreign key information of existing tables. Defaults to > false. > > -This means that to add any new foreign keys to a class that has already > been > > -mapped, you must explicitly set this flag to true. > > - > > - > > - > > - > > --indexes/-ix <true/t | false/f>: Whether to > read and > > -manipulate index information of existing tables. Defaults to false. > This means > > -that to add any new indexes to a class that has already been mapped > once, you > > -must explicitly set this flag to true. > > - > > - > > - > > - > > --sequences/-sq <true/t | false/f>: Whether to > > -manipulate sequences. Defaults to true. > > - > > - > > - > > - > > --meta/-m <true/t | false/f>: Whether the given > action > > -applies to metadata rather than or in addition to mappings. > > - > > - > > - > > - > > -The mapping tool also uses an -action/-a argument to > specify > > -the action to take on each class. The available actions are: > > - > > - > > - > > - > > -buildSchema: This is the default action. It > > -makes the database schema match your existing mappings. If your > provided > > -mappings conflict with your class definitions, OpenJPA will fail with > an > > -informative exception. > > - > > - > > - > > - > > -validate: Ensure that the mappings for the given > classes are > > -valid and that they match the schema. No mappings or tables will be > changed. An > > -exception is thrown if any mappings are invalid. > > - > > - > > - > > - > > -Each additional argument to the tool should be one of: > > - > > - > > - > > - > > -The full name of a persistent class. > > - > > - > > - > > - > > -The .java file for a persistent class. > > - > > - > > - > > - > > -The .class file of a persistent class. > > - > > - > > - > > - > > -If you do not supply any arguments to the mapping tool, it will run on > the > > -classes in your persistent classes list (see > > -). > > - > > - > > -The mappings generated by the mapping tool are stored by the system > > > -mapping factory. > > -discusses your mapping factory options. > > - > > -
> > - > > - Using the Mapping Tool > > - > > - > > - > > - mapping tool > > - > > - > > - use cases > > - > > - > > - > > -The JPA specification defines a comprehensive set of defaults for > missing > > -mapping information. Thus, forward mapping in JPA is virtually > automatic. After > > -using the mapping annotations covered in linkend="jpa_overview_mapping"/> > > -of the JPA Overview to override any unsatisfactory defaults, run the > > -mapping tool on your persistent classes. The default > buildSchema > > - mapping tool action manipulates the database schema to > > -match your mappings. It fails if any of your mappings don't match your > object > > -model. > > - > > - > > - > > - Creating the Relational Schema from Mappings > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java > > - > > - > > - > > -To drop the schema for a persistent class, set the mapping tool's > > > -schemaAction to drop. > > - > > - > > - > > - Refreshing entire schema and cleaning out tables > > - > > - zone="ref_guide_mapping_mappingtool_cleanup_tables"> > > - > > - testing > > - > > - > > - Rebuild mappings and clean tables > > - > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool -sa > add,deleteTableContents > > - > > - > > - > > - > > - Dropping Mappings and Association Schema > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool -sa drop Magazine.java > > - > > - > > -
> > -
> > - > > - Generating DDL SQL > > - > > - > > - > > - mapping tool > > - > > - > > - DDL generation > > - > > - > > - > > - > > - DDL > > - > > - > > - with mapping tool > > - > > - > > - > > -The examples below show how to use the mapping tool to generate DDL SQL > scripts, > > -rather than modifying the database directly. > > - > > - > > - > > - Create DDL for Current Mappings > > - > > - > > -This example uses your existing mappings to determine the needed > schema, then > > -writes the SQL to create that schema to create.sql > . > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool -sa build -sql create.sql > Magazine.java > > - > > - > > - > > - > > - Create DDL to Update Database for Current Mappings > > - > > - > > -This example uses your existing mappings to determine the needed > schema. It then > > -writes the SQL to add any missing tables and columns to the current > schema to > > -update.sql. > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool -sql update.sql > Magazine.java > > - > > - > > -
> > -
> > - > > - Runtime Forward Mapping > > - > > - > > - > > - forward mapping > > - > > - > > - automatic runtime mapping > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - automatic runtime mapping > > - > > - > > - > > -You can configure OpenJPA to automatically run the mapping tool at > runtime > > -through the > > -openjpa.jdbc.SynchronizeMappings configuration > property. Using > > -this property saves you the trouble of running the mapping tool > manually, and is > > -meant for use during rapid test/debug cycles. > > - > > - > > -In order to enable automatic runtime mapping, you must first list all > your > > -persistent classes as described in linkend="ref_guide_pc_pcclasses"/>. > > - > > - > > -OpenJPA will run the mapping tool on these classes when your > application obtains > > -its first EntityManager. > > - > > - > > -The openjpa.jdbc.SynchronizeMappings property is a > plugin > > -string (see ) where the class > > -name is the mapping tool action to invoke, and the properties are the > > -MappingTool class' JavaBean properties. These > properties > > -correspond go the long versions of the tool's command line flags. > > - > > - > > - > > - Configuring Runtime Forward Mapping > > - > > - > > -<property name="openjpa.jdbc.SynchronizeMappings" > value="buildSchema(ForeignKeys=true)"/> > > - > > - > > -The setting above corresponds to running the following command: > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool -a buildSchema -fk true > > - > > - > > -
> > -
> > -
> > - > > - Reverse Mapping > > - > > - > > - > > - reverse mapping > > - > > - > > - > > - > > - reverse mapping tool > > - > > - > > - reverse mapping > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - reverse mapping > > - > > - > > - reverse mapping > > - > > - > > - > > -OpenJPA includes a reverse mapping 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 . The reverse mapping > tool, > > -however, can give you an excellent starting point from which to grow > your > > -persistent classes. > > - > > - > > -To use the reverse mapping tool, follow the steps below: > > - > > - > > - > > - > > -Use the schema tool > 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. > > - > > - > > - > > - Reflection with the Schema Tool > > - > > - > > -java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml > > - > > - > > - > > - > > - > > -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 . > > - > > - > > -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. > > - > > - > > - > > - > > -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, > > - url="../javadoc/org/apache/openjpa/jdbc/meta/ReverseMappingTool"> > > -org.apache.openjpa.jdbc.meta.ReverseMappingTool > . > > - > > - > > - > > - Using the Reverse Mapping Tool > > - > > - > > -java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -d > ~/src -cp customizer.properties schema.xml > > - > > - > > - > > -In addition to OpenJPA's linkend="ref_guide_conf_devtools">standard > > -configuration flags, including > > -code formatting > options, > > -the reverse mapping tool recognizes the following command line > arguments: > > - > > - > > - > > - > > --schemas/-s <schema and table names>: 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 openjpa.jdbc.Schemas property described in > > -. In fact, if this flag is > > -omitted, it defaults to the value of the Schemas > property. If > > -the Schemas property is not defined, all schemas > will be > > -reverse-mapped. > > - > > - > > - > > - > > --package/-pkg <package name>: The package name > of the > > -generated classes. If no package name is given, the generated code will > not > > -contain package declarations. > > - > > - > > - > > - > > --directory/-d <output directory>: 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. > > - > > - > > - > > - > > --metadata/-md <class | package | none>: > Specify the > > -level the metadata should be generated at. Defaults to generating a > single > > -package-level metadata file. Set to none to disable > orm.xml > > -generation. > > - > > - > > - > > - > > --annotations/-ann <true/t | false/f>: Set to > true to > > -generate JPA annotations in generated java classes. > > - > > - > > - > > - > > --accessType/-access <field | property>: Change > access > > -type for generated annotations. Defaults to field access. > > - > > - > > - > > - > > --useSchemaName/-sn <true/t | false/f>: Set > this flag > > -to true 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. > > - > > - > > - > > - > > --useForeignKeyName/-fkn <true/t | false/f>: > Set this > > -flag to true 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. > > - > > - > > - > > - > > --nullableAsObject/-no <true/t | false/f>: By > default, > > -all non-foreign key columns are mapped to primitives. Set this flag to > > > -true to generate primitive wrapper fields instead for columns > that > > -allow null values. > > - > > - > > - > > - > > --blobAsObject/-bo <true/t | false/f>: By > default, all > > -binary columns are mapped to byte[] fields. Set > this flag > > -to true to map them to Object > fields > > -instead. Note that when mapped this way, the column is presumed to > contain a > > -serialized Java object. > > - > > - > > - > > - > > --primaryKeyOnJoin/-pkj <true/t | false/f>: 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 true to avoid creating > classes for > > -those tables. > > - > > - > > - > > - > > --inverseRelations/-ir <true/t | false/f>: Set > to > > -false to prevent the creation of inverse 1-many/1-1 > relations > > -for every many-1/1-1 relation detected. > > - > > - > > - > > - > > --useGenericCollections/-gc <true/t | false/f>: > Set to > > -true to use generic collections on OneToMany and ManyToMany relations > (requires > > -JDK 1.5 or higher). > > - > > - > > - > > - > > --useDatastoreIdentity/-ds <true/t | false/f>: > Set to > > -true to use datastore identity for tables that have > single > > -numeric primary key columns. The tool typically uses application > identity for > > -all generated classes. > > - > > - > > - > > - > > --useBuiltinIdentityClass/-bic <true/t | > false/f>: Set > > -to false to prevent the tool from using built-in > application > > -identity classes when possible. This will force the tool to to create > custom > > -application identity classes even when there is only one primary key > column. > > - > > - > > - > > - > > --innerIdentityClasses/-inn <true/t | false/f>: > Set to > > -true to have any generated application identity > classes be > > -created as static inner classes within the persistent classes. Defaults > to > > -false. > > - > > - > > - > > - > > --identityClassSuffix/-is <suffix>: Suffix to > append to > > -class names to form application identity class names, or for inner > identity > > -classes, the inner class name. Defaults to Id. > > - > > - > > - > > - > > --typeMap/-typ <type mapping>: A string that > specifies > > -the default Java classes to generate for each SQL type that is seen in > the > > -schema. The format is SQLTYPE1=JavaClass1,SQLTYPE2=JavaClass2 > > -. The SQL type name first looks for a customization based on > > > -SQLTYPE(SIZE,PRECISION), then > SQLTYPE(SIZE), then > > -SQLTYPE(SIZE,PRECISION). So if a column whose type > name is > > -CHAR is found, it will first look for the > > -CHAR(50,0) type name specification, then it will look for > > > -CHAR(50), and finally it will just look for > CHAR. > > -For example, to generate a char array for every CHAR > column > > -whose size is exactly 50, and to generate a short > for every > > -type name of INTEGER, you might specify: > > -CHAR(50)=char[],INTEGER=short. Note that since various > databases > > -report different type names differently, one database's type name > specification > > -might not work for another database. Enable TRACE > level > > -logging on the MetaData channel to track which type > names > > -OpenJPA is examining. > > - > > - > > - > > - > > --customizerClass/-cc <class name>: The full > class name > > -of a > > - url="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html"> > > -org.apache.openjpa.jdbc.meta.ReverseCustomizer > > > -customization plugin. If you do not specify a reverse customizer of > your own, > > -the system defaults to a > > - url="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html"> > > -PropertiesReverseCustomizer. This > customizer > > -allows you to specify simple customization options in the properties > file given > > -with the -customizerProperties flag below. We > present the > > -available property keys > > -below. > > - > > - > > - > > - > > --customizerProperties/-cp <properties file or > resource> > > -: The path or resource name of a properties file to pass to the reverse > > -customizer on initialization. > > - > > - > > - > > - > > --customizer./-c.<property name> <property > value> > > -: The given property name will be matched with the corresponding Java > bean > > -property in the specified reverse customizer, and set to the given > value. > > - > > - > > - > > - > > -Running the tool will generate .java files for > each > > -generated class (and its application identity class, if applicable), > along with > > -JPA annotations (if enabled by setting -annotations > true), > > -or an orm.xml file (if not disabled with > > --metadata none) containing the corresponding persistence > metadata. > > - > > - > > - > > - > > -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. > > - > > - > > -After you are satisfied with the generated classes and their mappings, > you > > -should first compile the classes with javac, > > > -jikes, or your favorite Java compiler. Make sure the classes > are > > -located in the directory corresponding to the > -package flag > > -you gave the reverse mapping tool. Next, if you have generated an > > > -orm.xml, move that file to a META-INF > directory > > -within a directory in your classpath. Finally, enhance the classes > > -if necessary (see ). > > - > > - > > - > > - > > -Your persistent classes are now ready to access your existing schema. > > - > > -
> > - > > - Customizing Reverse Mapping > > - > > - > > -The org.apache.openjpa.jdbc.meta.ReverseCustomizer > plugin > > -interface allows you to customze the reverse mapping process. See the > class > > - url="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html"> > > -Javadoc for details on the hooks that this interface provides. > Specify > > -the concrete plugin implementation to use with the > > --customizerClass/-cc command-line flag, described in the > preceding > > -section. > > - > > - > > -By default, the reverse mapping tool uses a > > - url="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html"> > > -org.apache.openjpa.jdbc.meta.PropertiesReverseCustomizer > > > -. This customizer allows you to perform relatively simple > > -customizations through the properties file named with the > > --customizerProperties tool flag. The customizer recognizes > the > > -following properties: > > - > > - > > - > > - > > -<table name>.table-type <type>: Override > the > > -default type of the table with name <table > name>. > > -Legal values are: > > - > > - > > - > > - > > -base: Primary table for a base class. > > - > > - > > - > > - > > -secondary: Secondary table for a class. The table > must have > > -a foreign key joining to a class table. > > - > > - > > - > > - > > -secondary-outer: Outer-joined secondary table for a > class. > > -The table must have a foreign key joining to a class table. > > - > > - > > - > > - > > -association: Association table. The table must have > two > > -foreign keys to class tables. > > - > > - > > - > > - > > -collection: Collection table. The table must have > one > > -foreign key to a class table and one data column. > > - > > - > > - > > - > > -subclass: A joined subclass table. The table must > have a > > -foreign key to the superclass' table. > > - > > - > > - > > - > > -none: The table should not be reverse-mapped. > > - > > - > > - > > - > > - > > - > > -<class name>.rename <new class name>: > Override > > -the given tool-generated name <class name> > 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 none to reject > the class > > -and leave the corresponding table unmapped. > > - > > - > > - > > - > > -<table name>.class-name <new class > name>: Assign > > -the given fully-qualified class name to the type created from the table > with > > -name <table name>. Use a value of > none > > - to prevent reverse mapping this table. This property can be > used in > > -place of the rename property. > > - > > - > > - > > - > > -<class name>.identity <datastore | builtin | identity > class > > -name>: Set this property to datastore > to use > > -datastore identity for the class <class name>, > > -builtin 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. > > - > > - > > - > > - > > -<class name>.<field name>.rename <new field > name> > > -: Override the tool-generated <field > name> in > > -class <class name> 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 > none > > -to reject the generated mapping and remove the field from the class. > > - > > - > > - > > - > > -<table name>.<column name>.field-name <new > field > > -name>: Set the generated field name for the > <table > > -name> table's <column name> > column. If > > -this is a multi-column mapping, any of the columns can be used. Use a > value of > > -none to prevent the column and its associated > columns from > > -being reverse-mapped. > > - > > - > > - > > - > > -<class name>.<field name>.type <field > type> > > -: 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. > > - > > - > > - > > - > > -<class name>.<field name>.value: 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. > > - > > - > > - > > - > > -All property keys are optional; if not specified, the customizer keeps > the > > -default value generated by the reverse mapping tool. > > - > > - > > - > > - Customizing Reverse Mapping with Properties > > - > > - > > -java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -cp > custom.properties schema.xml > > - > > - > > -Example custom.properties: > > - > > - > > -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 > > - > > - > > -
> > -
> > -
> > - > > - Meet-in-the-Middle Mapping > > - > > - > > - > > - meet-in-the-middle mapping > > - > > - > > - > > - > > - reverse mapping tool > > - > > - > > - reverse mapping > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - meet-in-the-middle mapping > > - > > - > > - meet-in-the-middle mapping > > - > > - > > - > > -In the meet-in-the-middle > > -mapping approach, you control both the relational model and the object > model. It > > -is up to you to define the mappings between these models. The mapping > > -tool's validate action is useful to > meet-in-the-middle > > -mappers. This action verifies that the mapping information for a class > matches > > -the class definition and the existing schema. It throws an informative > exception > > -when your mappings are incorrect. > > - > > - > > - > > - Validating Mappings > > - > > - > > -java org.apache.openjpa.jdbc.meta.MappingTool -a validate Magazine.java > > - > > - > > - > > -The buildSchema action we discussed in > > - is also somewhat useful > > -during meet-in-the-middle mapping. Unlike the > validate > > -action, which throws an exception if your mapping data does not match > the > > -existing schema, the buildSchema action assumes your > mapping > > -data is correct, and modifies the schema to match your mappings. This > lets you > > -modify your mapping data manually, but saves you the hassle of using > your > > -database's tools to bring the schema up-to-date. > > - > > -
> > -
> > - > > - Mapping Defaults > > - > > - > > - > > - MappingDefaults > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - defaults > > - > > - > > - MappingDefaults > > - > > - > > - > > -The previous sections showed how to use the mapping tool to generate > default > > -mappings. But how does the mapping tool know what mappings to generate? > The > > -answer lies in the > > - url="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaults.html"> > > -org.apache.openjpa.jdbc.meta.MappingDefaults > > > -interface. OpenJPA uses an instance of this interface to decide how to > name > > -tables and columns, where to put foreign keys, and generally how to > create a > > -schema that matches your object model. > > - > > - > > - > > -OpenJPA relies on foreign key constraint information at runtime to > order SQL > > -appropriately. Be sure to set your mapping defaults to reflect your > existing > > -database constraints, set the schema factory to reflect on the database > for > > -constraint information (see linkend="ref_guide_schema_info_factory"/>), > > -or use explicit foreign key mappings as described in > > -. > > - > > - > > - > > -The > > -openjpa.jdbc.MappingDefaults configuration property > controls > > -the MappingDefaults interface implementation in > use. This > > -is a plugin property (see ), so > > -you can substitute your own implementation or configure the existing > ones. > > -OpenJPA includes the following standard implementations: > > - > > - > > - > > - > > -jpa: Provides defaults in compliance with the JPA > standard. > > -This is an alias for the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/PersistenceMappingDefaults.html"> > > - > org.apache.openjpa.persistence.jdbc.PersistenceMappingDefaults > > - class. This class extends the > > -MappingDefaultsImpl class described below, so it has all > the same > > -properties (though with different default values), as well as: > > - > > - > > - > > - > > -PrependFieldNameToJoinTableInverseJoinColumns: > Whether to > > -prepend the owning field name to the names of inverse join columns in > join > > -tables. Defaults to true per the JPA specification. Set to false for > > -compatibility with older OpenJPA versions which did not prepend the > field name. > > - > > - > > - > > - > > - > > - > > -default: This is an alias for the > > - url="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaultsImpl.html"> > > -org.apache.openjpa.jdbc.meta.MappingDefaultsImpl > > > -class. This default implementation is highly configurable. It has the > following > > -properties: > > - > > - > > - > > - > > -DefaultMissingInfo: Whether to default missing > column and > > -table names rather than throw an exception. If set to false, full > explicit > > -mappings are required at runtime and when using mapping tool actions > like > > -buildSchema and validate. > > - > > - > > - > > - > > -BaseClassStrategy: The default mapping strategy for > base > > -classes. You can specify a built-in strategy alias or the full class > name of a > > -custom class > strategy. > > -You can also use OpenJPA's plugin format (see > > -) to pass arguments to the > > -strategy instance. See the > > - > > -org.apache.openjpa.jdbc.meta.strats package > for > > -available strategies. > > - > > - > > - > > - > > -SubclassStrategy: The default mapping strategy for > > -subclasses. You can specify a builtin strategy alias or the full class > name of a > > - custom class > strategy. > > -You can also use OpenJPA's plugin format (see > > -) to pass arguments to the > > -strategy instance. Common strategies are vertical > and > > -flat, the default. See the > > - > > -org.apache.openjpa.jdbc.meta.strats package > for all > > -available strategies. > > - > > - > > - > > - > > -VersionStrategy: The default version strategy for > classes > > -without a version field. You can specify a builtin strategy alias or > the full > > -class name of a > custom > > -version strategy. You can also use OpenJPA's plugin format (see > > -) to pass arguments to the > > -strategy instance. Common strategies are none, > > > -state-comparison, timestamp, and > > > -version-number, the default. See the > > - > > -org.apache.openjpa.jdbc.meta.strats package > for all > > -available strategies. > > - > > - > > - > > - > > -DiscriminatorStrategy: The default discriminator > strategy > > -when no discriminator value is given. You can specify a builtin > strategy alias > > -or the full class name of a > > - custom > discriminator > > -strategy. You can also use OpenJPA's plugin format (see > > -) to pass arguments to the > > -strategy instance. Common strategies are final for a > base > > -class without subclasses, none to use joins to > subclass > > -tables rather than a discriminator column, and > class-name, > > -the default. See the > > - > > -org.apache.openjpa.jdbc.meta.strats package > for all > > -available strategies. > > - > > - > > - > > - > > -FieldStrategies: This property associates field > types with > > -custom strategies. The format of this property is similar to that of > plugin > > -strings (see ), without the > class > > -name. It is a comma-separated list of key/value pairs, where each key > is a > > -possible field type, and each value is itself a plugin string > describing the > > -strategy for that type. We present an example below. See > > - for information on > custum > > -field strategies. > > - > > - > > - > > - > > -ForeignKeyDeleteAction: The default delete action of > foreign > > -keys representing relations to other objects. Recognized values include > > -restrict, cascade, > null > > -, default. These values correspond exactly to the > standard > > -database foreign key actions of the same names. > > - > > - > > -The value none tells OpenJPA not to create database > foreign > > -keys on relation columns. This is the default. > > - > > - > > - > > - > > -JoinForeignKeyDeleteAction: The defualt delete > action of > > -foreign keys that join join secondary, collection, map, or subclass > tables to > > -the primary table. Accepts the same values as the > > -ForeignKeyDeleteAction property above. > > - > > - > > - > > - > > -DeferConstraints: Whether to use deferred database > > -constraints if possible. Defaults to false. > > - > > - > > - > > - > > -IndexLogicalForeignKeys: Boolean property > controlling > > -whether to create indexes on logical foreign keys. Logical foreign keys > are > > -columns that represent a link between tables, but have been configured > through > > -the ForeignKey properties above not to use a > physical > > -database foreign key. Defaults to true. > > - > > - > > - > > - > > -DataStoreIdColumnName: The default name of datastore > > -identity columns. > > - > > - > > - > > - > > -DiscriminatorColumnName: The default name of > discriminator > > -columns. > > - > > - > > - > > - > > -IndexDiscriminator: Whether to index the > discriminator > > -column. Defaults to true. > > - > > - > > - > > - > > -VersionColumnName: The default name of version > columns. > > - > > - > > - > > - > > -IndexVersion: Whether to index the version column. > Defaults > > -to false. > > - > > - > > - > > - > > -AddNullIndicator: Whether to create a synthetic null > > -indicator column for embedded mappings. The null indicator column > allows OpenJPA > > -to distinguish between a null embedded object and one with default > values for > > -all persistent fields. > > - > > - > > - > > - > > -NullIndicatorColumnName: The default name of > synthetic null > > -indicator columns for embedded objects. > > - > > - > > - > > - > > -OrderLists: Whether to create a database ordering > column for > > -maintaining the order of persistent lists and arrays. > > - > > - > > - > > - > > -OrderColumnName: The default name of collection and > array > > -ordering columns. > > - > > - > > - > > - > > -StoreEnumOrdinal: Set to true to store enum fields > as > > -numeric ordinal values in the database. The default is to store the > enum value > > -name as a string, which is more robust if the Java enum declaration > might be > > -rearranged. > > - > > - > > - > > - > > -StoreUnmappedObjectIdString: Set to true to store > the > > -stringified identity of related objects when the declared related type > is > > -unmapped. By default, OpenJPA stores the related object's primary key > value(s). > > -However, this breaks down if different subclasses of the related type > use > > -incompatible primary key structures. In that case, stringifying the > identity > > -value is the better choice. > > - > > - > > - > > - > > - > > - > > -The example below turns on foreign key generation during schema > creation and > > -associates the org.mag.data.InfoStruct field > type with > > -the custom org.mag.mapping.InfoStructHandler > value > > -handler. > > - > > - > > - > > - Configuring Mapping Defaults > > - > > - > > -<property name="openjpa.jdbc.MappingDefaults" > > - value="ForeignKeyDeleteAction=restrict, > > - FieldStrategies=' > org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'"/> > > - > > - > > -
> > -
> > - > > - Mapping Factory > > - > > - > > - > > - MappingFactory > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - loading and storing > > - > > - > > - MappingFactory > > - > > - > > - > > -An important decision in the object-relational mapping process is how > and where > > -to store the data necessary to map your persistent classes to the > database > > -schema. > > - > > - > > - introduced OpenJPA's > > > -MetaDataFactory interface. OpenJPA uses this same interface > to > > -abstract the storage and retrieval of mapping information. OpenJPA > includes the > > -built-in mapping factories below, and you can create your own factory > if you > > -have custom needs. You control which mapping factory OpenJPA uses with > the > > - > > -openjpa.jdbc.MappingFactory configuration property. > > - > > - > > -The bundled mapping factories are: > > - > > - > > - > > - > > --: Leaving the openjpa.jdbc.MappingFactory > > - property unset allows your metadata factory to take over > mappings as > > -well. If you are using the default jpa metadata > factory, > > -OpenJPA will read mapping information from your annotations and > > -orm.xml when you leave the mapping factory > unspecified. > > - > > - > > - > > - > > - > > - Standard JPA Configuration > > - > > - > > -In the standard JPA configuration, the mapping factory is left unset. > > - > > - > > -<property name="openjpa.MetaDataFactory" value="jpa"/> > > - > > - > > -
> > -
> > - > > - Non-Standard Joins > > - > > - > > - > > - joins > > - > > - > > - non-standard > > - > > - > > - > > -The JPA Overview's explains join > > -mapping. All of the examples in that document, however, use "standard" > joins, in > > -that there is one foreign key column for each primary key column in the > target > > -table. OpenJPA supports additional join patterns, including partial > primary key > > -joins, non-primary key joins, and joins using constant values. > > - > > - > > - > > - > > - joins > > - > > - > > - partial primary key > > - > > - > > -In a partial primary key join, the source table only has foreign key > columns for > > -a subset of the primary key columns in the target table. So long as > this subset > > -of columns correctly identifies the proper row(s) in the referenced > table, > > -OpenJPA will function properly. There is no special syntax for > expressing a > > -partial primary key join - just do not include column definitions for > missing > > -foreign key columns. > > - > > - > > - > > - > > - joins > > - > > - > > - non-primary key > > - > > - > > -In a non-primary key join, at least one of the target columns is not a > primary > > -key. Once again, OpenJPA supports this join type with the same syntax > as a > > -primary key join. There is one restriction, however: each non-primary > key column > > -you are joining to must be controlled by a field mapping that > implements the > > - url="../javadoc/org/apache/openjpa/jdbc/meta/Joinable.html"> > > -org.apache.openjpa.jdbc.meta.Joinable interface. > All built > > -in basic mappings implement this interface, including basic fields of > embedded > > -objects. OpenJPA will also respect any custom mappings that implement > this > > -interface. See for an > > -examination of custom mappings. > > - > > - > > - > > - > > - joins > > - > > - > > - constant > > - > > - > > -Not all joins consist of only links between columns. In some cases you > might > > -have a schema in which one of the join criteria is that a column in the > source > > -or target table must have some constant value. OpenJPA calls joins > involving > > -constant values constant joins. > > - > > - > > -To form a constant join in JPA mapping, first set the > JoinColumn > > -'s name attribute to the name of the > column. If the > > -column with the constant value is the target of the join, give its > fully > > -qualified name in the form <table name>.<column > name> > > -. Next, set the referencedColumnName > attribute to > > -the constant value. If the constant value is a string, place it in > single quotes > > -to differentiate it from a column name. > > - > > - > > - > > - > > - width="285px"/> > > - > > - > > - > > - > > -Consider the tables above. First, we want to join row T1.R1 > > > -to row T2.R1. If we just join column T1.FK > > > -to T2.PK1, we will wind up matching both > T2.R1 > > - and T2.R2. So in addition to joining > > > -T1.FK to T2.PK1, we also have to specify > that > > -T2.PK2 has the value a. Here is > how we'd > > -accomplish this in mapping metadata. > > - > > - > > -@Entity > > -@Table(name="T1") > > -public class ... { > > - > > - @ManyToOne > > - @JoinColumns({ > > - @JoinColumn(name="FK" referencedColumnName="PK1"), > > - @JoinColumn(name="T2.PK2" referencedColumnName="'a'") > > - }); > > - private ...; > > -} > > - > > - > > -Notice that we had to fully qualify the name of column > PK2 > > -because it is in the target table. Also notice that we put single > quotes around > > -the constant value so that it won't be confused with a column name. You > do not > > -need single quotes for numeric constants. For example, the syntax to > join > > -T1.R2 to T2.R4 is: > > - > > - > > -@Entity > > -@Table(name="T1") > > -public class ... { > > - > > - @ManyToOne > > - @JoinColumns({ > > - @JoinColumn(name="FK" referencedColumnName="PK2"), > > - @JoinColumn(name="T2.PK1" referencedColumnName="2") > > - }); > > - private ...; > > -} > > - > > - > > -Finally, from the inverse direction, these joins would look like this: > > - > > - > > -@Entity > > -@Table(name="T2") > > -public class ... { > > - > > - @ManyToOne > > - @JoinColumns({ > > - @JoinColumn(name="T1.FK" referencedColumnName="PK1"), > > - @JoinColumn(name="PK2" referencedColumnName="'a'") > > - }); > > - private ...; > > - > > - @ManyToOne > > - @JoinColumns({ > > - @JoinColumn(name="T1.FK" referencedColumnName="PK2"), > > - @JoinColumn(name="PK1" referencedColumnName="2") > > - }); > > - private ...; > > -} > > - > > -
> > -
> > - > > - Additional JPA Mappings > > - > > - > > - > > - mapping metadata > > - > > - > > - JPA additions > > - > > - > > - > > -OpenJPA supports many persistence strategies beyond those of the JPA > > -specification. covered the logical > > -metadata for OpenJPA's additional persistence strategies. We now > demonstrate how > > -to map entities using these strategies to the database. > > - > > -
> > - > > - Datastore Identity Mapping > > - > > - > > - > > - datastore identity > > - > > - > > - mapping > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - datastore identity > > - > > - > > - identity > > - > > - > > - > > - > > - DataStoreIdColumn > > - > > - > > - mapping metadata > > - > > - > > - > > - > > - primary key > > - > > - > > - > > - describes how to use datastore > identity > > -in JPA. OpenJPA requires a single numeric primary key column to hold > datastore > > -identity values. The > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/DataStoreIdColumn.html"> > > -org.apache.openjpa.persistence.jdbc.DataStoreIdColumn > > > - annotation customizes the datastore identity column. This > annotation > > -has the following properties: > > - > > - > > - > > - > > -String name: Defaults to ID. > > - > > - > > - > > - > > -int precision > > - > > - > > - > > - > > -String columnDefinition > > - > > - > > - > > - > > -boolean insertable > > - > > - > > - > > - > > -boolean updatable > > - > > - > > - > > - > > -All properties correspond exactly to the same-named properties on the > standard > > -Column annotation, described in > > -. > > - > > - > > - > > - Datastore Identity Mapping > > - > > - > > -import org.apache.openjpa.persistence.*; > > -import org.apache.openjpa.persistence.jdbc.*; > > - > > -@Entity > > -@Table(name="LOGS") > > -@DataStoreIdColumn(name="ENTRY") > > -public class LogEntry { > > - > > - @Lob > > - private String content; > > - > > - ... > > -} > > - > > - > > -
> > -
> > - > > - Surrogate Version Mapping > > - > > - > > - > > - version > > - > > - > > - mapping > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - version > > - > > - > > - version > > - > > - > > - > > - > > - VersionColumn > > - > > - > > - mapping metadata > > - > > - > > - > > -OpenJPA supports version fields as defined by the JPA specification, > but allows > > -you to use a surrogate version column in place of a version field if > you like. > > -You map the surrogate version column with the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/VersionColumn.html"> > > -org.apache.openjpa.persistence.jdbc.VersionColumn > > > -annotation. You can also use the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/VersionColumns.html"> > > -org.apache.openjpa.persistence.jdbc.VersionColumns > > > - annotation to declare an array of > VersionColumn > > -values. Each VersionColumn has the following > properties: > > - > > - > > - > > - > > -String name: Defaults to VERSN. > > - > > - > > - > > - > > -int length > > - > > - > > - > > - > > -int precision > > - > > - > > - > > - > > -int scale > > - > > - > > - > > - > > -String columnDefinition > > - > > - > > - > > - > > -boolean nullable > > - > > - > > - > > - > > -boolean insertable > > - > > - > > - > > - > > -boolean updatable > > - > > - > > - > > - > > -All properties correspond exactly to the same-named properties on the > standard > > -Column annotation, described in > > -. > > - > > - > > -By default, OpenJPA assumes that surrogate versioning uses a version > number > > -strategy. You can choose a different strategy with the > > -VersionStrategy annotation described in > > -. > > - > > -
> > -
> > - > > - Multi-Column Mappings > > - > > - > > - > > - mapping metadata > > - > > - > > - column > > - > > - > > - > > - > > - mapping metadata > > - > > - > > - multi-column mappings > > - > > - > > - > > - > > - Columns > > - > > - > > - mapping metadata > > - > > - > > - > > -OpenJPA makes it easy to create multi-column > > -custom mappings. > The JPA > > -specification includes a Column annotation, but > is > > -missing a way to declare multiple columns for a single field. OpenJPA > remedies > > -this with the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/Columns.html"> > > -org.apache.openjpa.persistence.jdbc.Columns > > > -annotation, which contains an array of Column > values. > > - > > - > > -Remember to annotate custom field types with > Persistent, > > -as described in . > > - > > -
> > -
> > - > > - Join Column Attribute Targets > > - > > - > > - in the JPA Overview > introduced > > -you to the JoinColumn annotation. A > > -JoinColumn's referencedColumnName > property > > -declares which column in the table of the related type this join column > links > > -to. Suppose, however, that the related type is unmapped, or that it is > part of a > > -table-per-class inheritance hierarchy. Each subclass that might be > assigned to > > -the field could reside in a different table, and could use entirely > different > > -names for its primary key columns. It becomes impossible to supply a > single > > -referencedColumnName that works for all subclasses. > > - > > - > > -OpenJPA rectifies this by allowing you to declare which > attribute > > - in the related type each join column links to, rather than > which > > -column. If the attribute is mapped differently in various subclass > tables, > > -OpenJPA automatically forms the proper join for the subclass record at > hand. The > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/XJoinColumn.html"> > > -org.apache.openjpa.persistence.jdbc.XJoinColumn > > > -annotation has all the same properties as the standard > JoinColumn > > - annotation, but adds an additional > > -referencedAttributeName property for this purpose. Simply use > a > > -XJoinColumn in place of a JoinColumn > > - whenever you need to access this added functionality. > > - > > - > > -For compound keys, use the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/XJoinColumns.html"> > > -org.apache.openjpa.persistence.jdbc.XJoinColumns > > > -annotation. The value of this annotation is an array of individual > > > -XJoinColumns. > > - > > -
> > -
> > - > > - Embedded Mapping > > - > > - > > -JPA uses the AttributeOverride annotation to > override the > > -default mappings of an embeddable class. The JPA Overview details this > process > > -in . > > -AttributeOverrides suffice for simple mappings, but do not > allow > > -you to override complex mappings. Also, JPA has no way to > differentitate between > > -a null embedded object and one with default values for all of its > fields. > > - > > - > > -OpenJPA overcomes these shortcomings with the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/EmbeddedMapping.html"> > > -org.apache.openjpa.persistence.jdbc.EmbeddedMapping > > > - annotation. This annotation has the following properties: > > - > > - > > - > > - > > -String nullIndicatorColumnName: If the named > column's value > > -is NULL, then the embedded object is assumed to be > null. If > > -the named column has a non- NULL value, then the > embedded > > -object will get loaded and populated with data from the other embedded > fields. > > -This property is entirely optional. By default, OpenJPA always assumes > the > > -embedded object is non-null, just as in standard JPA mapping. > > - > > - > > -If the column you name does not belong to any fields of the embedded > object, > > -OpenJPA will create a synthetic null-indicator column with this name. > In fact, > > -you can specify a value of true to simply indicate > that you > > -want a synthetic null-indicator column, without having to come up with > a name > > -for it. A value of false signals that you explicitly > do not > > -want a null-indicator column created for this mapping (in case you have > > -configured your mapping > defaults > > - to create one by default). > > - > > - > > - > > - > > -String nullIndicatorFieldName: Rather than name a > null > > -indicator column, you can name a field of the embedded type. OpenJPA > will use > > -the column of this field as the null-indicator column. > > - > > - > > - > > - > > -MappingOverride[] overrides: This array allows you > to > > -override any mapping of the embedded object. > > - > > - > > - > > - > > -The EmbeddedMapping's > overrides array > > -serves the same purpose as standard JPA's AttributeOverride > > -s and AssociationOverride s. In > fact, you can > > -also use the MappingOverride annotation on an > entity > > -class to override a complex mapping of its mapped superclass, just as > you can > > -with AttributeOverride and > > -AssociationOverride s. The > MappingOverrides > > -annotation, whose value is an array of > MappingOverride s, > > -allows you to overide multiple mapped superclass mappings. > > - > > - > > -Each > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/MappingOverride.html"> > > -org.apache.openjpa.persistence.jdbc.MappingOverride > > > - annotation has the following properties: > > - > > - > > - > > - > > -String name: The name of the field that is being > overridden. > > - > > - > > - > > - > > -Column[] columns: Columns for the new field mapping. > > - > > - > > - > > - > > -XJoinColumn[] joinColumns: Join columns for the new > field > > -mapping, if it is a relation field. > > - > > - > > - > > - > > -ContainerTable containerTable: Table for the new > collection > > -or map field mapping. We cover collection mappings in > > -, and map mappings in > > -. > > - > > - > > - > > - > > -ElementJoinColumn[] elementJoinColumns: Element join > columns > > -for the new collection or map field mapping. You will see how to use > element > > -join columns in . > > - > > - > > - > > - > > -The following example defines an embeddable PathCoordinate > > - class with a custom mapping of a java.awt.Point > > - field to two columns. It then defines an entity which > embeds a > > - PointCoordinate and overrides the default > mapping for > > -the point field. The entity also declares that if the > PathCoordinate > > -'s siteName field column is null, it > means that > > -no PathCoordinate is stored in the embedded > record; the > > -owning field will load as null. > > - > > - > > - > > - Overriding Complex Mappings > > - > > - > > -import org.apache.openjpa.persistence.jdbc.*; > > - > > -@Embeddable > > -public class PathCoordinate { > > - > > - private String siteName; > > - > > - @Persistent > > - @Strategy("com.xyz.openjpa.PointValueHandler") > > - private Point point; > > - > > - ... > > -} > > - > > -@Entity > > -public class Path { > > - > > - @Embedded > > - @EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={ > > - @MappingOverride(name="siteName", > columns=@Column(name="START_SITE")), > > - @MappingOverride(name="point", columns={ > > - @Column(name="START_X"), > > - @Column(name="START_Y") > > - }) > > - }) > > - private PathCoordinate start; > > - > > - ... > > -} > > - > > - > > -
> > -
> > - > > - Collections > > - > > - > > - > > - mapping metadata > > - > > - > > - collections > > - > > - > > - > > -In , we explored > the > > -PersistentCollection annotation for persistent > collection > > -fields that aren't a standard OneToMany or > > -ManyToMany relation. To map these non-standard collections, > combine > > -OpenJPA's ContainerTable annotation with > > -ElementJoinColumns. > > -We explore the annotations below. > > - > > -
> > - > > - Container Table > > - > > - > > - > > - ContainerTable > > - > > - > > - mapping metadata > > - > > - > > - > > -The > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/ContainerTable.html"> > > -org.apache.openjpa.persistence.jdbc.ContainerTable > > > - annotation describes a database table that holds collection > (or map) > > -elements. This annotation has the following properties: > > - > > - > > - > > - > > -String name > > - > > - > > - > > - > > -String catalog > > - > > - > > - > > - > > -String schema > > - > > - > > - > > - > > -XJoinColumn[] joinColumns > > - > > - > > - > > - > > -ForeignKey joinForeignKey > > - > > - > > - > > - > > -Index joinIndex > > - > > - > > - > > - > > -The name, catalog, > schema > > -, and joinColumns properties describe the > container > > -table and how it joins to the owning entity's table. These properties > correspond > > -to the same-named properties on the standard > JoinTable > > -annotation, described in linkend="jpa_overview_mapping_assoccoll"/> > > -. If left unspecified, the name of the table defaults to the first five > > -characters of the entity table name, plus an underscore, plus the field > name. > > -The joinForeignKey and joinIndex > > -properties override default foreign key and index generation for the > join > > -columns. We explore foreign keys and indexes later in this chapter. > > - > > - > > -You may notice that the container table does not define how to store > the > > -collection elements. That is left to separate annotations, which are > the subject > > -of the next sections. > > - > > -
> > -
> > - > > - Element Join Columns > > - > > - > > - > > - ElementJoinColumn > > - > > - > > - mapping metadata > > - > > - > > - > > -Element join columns are equivalent to standard JPA join columns, > except that > > -they represent a join to a collection or map element entity rather than > a direct > > -relation. You represent an element join column with OpenJPA's > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/ElementJoinColumn.html"> > > -org.apache.openjpa.persistence.jdbc.ElementJoinColumn > > > - annotation. To declare a compound join, enclose an array of > > > -ElementJoinColumns in the > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/ElementJoinColumns.html"> > > -org.apache.openjpa.persistence.jdbc.ElementJoinColumns > > > - annotation. > > - > > - > > -An ElementJoinColumn always resides in a > container table, > > -so it does not have the table property of a > standard > > - JoinColumn. Like > XJoinColumns > > -above, ElementJoinColumns can reference a > linked > > -attribute rather than a static linked column. Otherwise, the > > > -ElementJoinColumn and standard > JoinColumn > > -annotations are equivalent. See linkend="jpa_overview_mapping_rel"/> > > -in the JPA Overview for a review of the > JoinColumn > > -annotation. > > - > > -
> > -
> > - > > - Order Column > > - > > - > > - > > - OrderColumn > > - > > - > > - mapping metadata > > - > > - > > - > > -Relational databases do not guarantee that records are returned in > insertion > > -order. If you want to make sure that your collection elements are > loaded in the > > -same order they were in when last stored, you must declare an order > column. > > -OpenJPA's > > - url="../javadoc/org/apache/openjpa/persistence/jdbc/OrderColumn"> > > -org.apache.openjpa.persistence.jdbc.OrderColumn > > > -annotation has the following properties: > > - > > - > > - > > - > > -String name: Defaults to ORDR. > > - > > - > > - > > - > > -boolean enabled > > - > > - > > - > > - > > > > [... 4307 lines stripped ...] > > > > > > > -- > Patrick Linskey > 202 669 5907 > ------=_Part_7391_19768266.1185564365953--