3.8.1. 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

Mapping Tool Ant Task describes the mapping tool Ant task.

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

  • -sqlEncode/-se <encoding>: Use this option with -sqlFile to write the SQL script in a different Java character set encoding than the default JVM locale, such as -sqlTerminator/-st <terminal>: Use this option with -sqlFile to write the SQL terminating with a different character instead of a semicolon.

  • -dropTables/-dt <true/t | false/f>: Corresponds to the same-named option on the schema tool.

  • -rollbackBeforeDDL/-rbddl <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 Persistent Class List).

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