Chapter 23.  Mapping

Table of Contents

Forward Mapping
Using the Mapping Tool
Generating DDL SQL
Runtime Forward Mapping
Reverse Mapping
Customizing Reverse Mapping
Meet-in-the-Middle Mapping
Mapping Defaults
Mapping Factory
Non-Standard Joins
Additional JPA Mappings
Datastore Identity Mapping
Surrogate Version Mapping
Multi-Column Mappings
Join Column Attribute Targets
Embedded Mapping
Collections
One-Sided One-Many Mapping
Maps
Indexes and Constraints
XML Column Mapping
LOB Streaming
Mapping Limitations
Table Per Class
Mapping Extensions
Class Extensions
Field Extensions
Custom Mappings
Custom Class Mapping
Custom Discriminator and Version Strategies
Custom Field Mapping
Orphaned Keys

The JPA Overview's Chapter 15, Mapping Metadata 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 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, org.apache.openjpa.jdbc.meta.MappingTool.

Note

the section called “ Mapping Tool Ant Task ” describes the mapping tool Ant task.

Example 23.1.  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 the section called “ Schema Tool ”. 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 section called “ Persistent Class List ”).

The mappings generated by the mapping tool are stored by the system mapping factory. the section called “ Mapping Factory ” discusses your mapping factory options.

Using the Mapping Tool

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 Chapter 15, Mapping Metadata 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.

Example 23.2.  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.

Example 23.3.  Refreshing entire schema and cleaning out tables

java org.apache.openjpa.jdbc.meta.MappingTool -schemaAction add,deleteTableContents

Example 23.4.  Dropping Mappings and Association Schema

java org.apache.openjpa.jdbc.meta.MappingTool -schemaAction drop Magazine.java

Generating DDL SQL

The examples below show how to use the mapping tool to generate DDL SQL scripts, rather than modifying the database directly.

Example 23.5.  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 -schemaAction build -sql create.sql Magazine.java

Example 23.6.  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

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 the section called “ Persistent Class List ”.

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 the section called “ Plugin Configuration ”) 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.

Example 23.7.  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 -action buildSchema -foreignKeys true