wsmapping command

The wsmapping tool is used to provide top-down mapping of the entity object model to the database relational model. Use the wsmapping tool to create database tables.

Use the wsmapping tool to create database tables.

 

Syntax

Before running the command,  have a copy of persistence.xml on the classpath, or specify  it as a properties file through the -p [path_to_persistence.xml] argument. Issue the  command from the bin subdirectory of the app_install_root directory.

The command syntax is as follows: [AIX] [HP-UX] [Linux] [Solaris]

wsmapping.sh [options][arguments]

(Windows)

wsmapping.bat [options][arguments]

 

Parameters

The mapping tool accepts the standard set of command-line arguments defined by the configuration framework with the following options:

• -schemaAction/-sa <add | refresh | drop | build | reflect | retain | createDB | import | export | none>: The action to execute against the schema. These options correspond to the actions of the schema tool. Add is the default action if none is specified. Actions can be composed in a list separated by commas.

  The wsmapping tool accepts the -action/-a flag to specify the action to take on individual classes. Unless we are running wsmapping on all of the persistent types at once, or dropping a mapping, we need to use the default add action or the build action. Otherwise, we might inadvertently drop schema components that are used by classes that we are not currently running the tool against.

• -schemaFile/-sf <true/t | false/f>: This option can be used to write the planned schema to an XML document rather than modify the database. The XML document can then be modified, manupulated and committed to the database with the schema tool.

• -sqlFile/-sql <stdout | output file>: This option can be used to write the planned schema modifications to an SQL script rather than modify the database. Combine this parameter 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>: When this option is set to true, schema drops tables that appear to be unused during retain and refresh actions. The default is true.

• -dropSequences/-dsq <true/t | false/f>: If this option is set to true, schema drops sequences that are unused during retain and refresh actions. The default is true.

• -openjpatables/-ot <true/t | false/f>: When reflecting the schema, this parameter determines whether to reflect on tables and sequences with names that start with OPENJPA_. Certain OpenJPA components can use these tables and sequences, such as the table schema factory. When using other actions, the openjpaTables parameter controls whether these tables can be dropped or not. The default setting is false.

• -ignoreErrors/-i <true/t | false/f>: If set to false, an exception is displayed if the tool encounters any database errors. The default is set to false.

• -schemas/-s <schema list>: Denotes a list of schema and table names the OpenJPA should access when running the wsschema tool. This is the equivalent to setting the openjpa.jdbc.Schemas property to run once. This parameter corresponds to the -schemas/-s parameter in the wsschema tool. This option is ignored if -readSchema/-rs is not set to true.

• -readSchema/-rs <true/t | false/f>: Set this option to true to read the entire existing schema when the mapping tool runs. Reading the existing schema ensures that OpenJPA does not generate any mappings that use the table, index, primary key or foreign key names that conflict with existing names.

  Depending on the particular JDBC driver, selecting the -readSchema/-rs function can slow down the process for large schemas.

• -primaryKeys/-pk <true/t | false/f>: This flag determines if the primary keys can be manipulated on existing tables. The default is true.

• -foreignKeys/fk <true/t | false/f>: This flag determines if foreign keys can be manipulated on existing tables. The default is true. This means that to add any new foreign key to a class that has already been mapped, explicitly set this parameter flag to true.

• -indexes/-ix <true/t | false/f>: This flag determines if indexes can be manipulated on existing tables. The default is true. This means that to add any new indexes to a class that has already been mapped, explicitly set this parameter flag to true.

• -sequences/-sq <true/t | false/f>: This flag determines if sequences can be manipulated. The default is true.

• -meta/-m <true/t | false/f>: This flag determines whether or not a mapping applies to metadata rather than, or in addition to, standard mappings.

• The wsmapping tool accepts the -action/-a flag to specify the action to take on each class. Multiple actions can be composed in a list, separated by commas. The available actions are:

  • buildSchema: This is the default action. The buildSchema action makes the database schema match the existing mappings. If the provided mappings conflict with the class definitions, OpenJPA fails with an informative exception.

  • validate: Verify the mappings for the given classes are valid and that they match the schema of the database. No mappings of tables are changed as a result of this action. An exception is occurs if any mappings are invalid.

Each additional argument to the wsmapping tool must be one of the following:

• The full name of a persistent class.

• The .java name for a persistent class.

• The .class file of a persistent class.

If we do not supply any arguments to the wsmapping tool, it runs on the classes in the persistent classes list.

 

Usage

Before running the wsmapping tool, we need to configure the datasource information, including the URL, user, and password. It is required that the wsenhancer tool is run before the wsmapping tool to insert bytecode into the entity classes. Also, the compiled class files for the entities should be on the classpath (assume entity class files can be found in target/classes) ...
[AIX] [HP-UX] [Linux]

(UNIX) [Solaris]

export CLASSPATH=${CLASSPATH}:target/classes 
 wsmapping.sh ...

(Windows)

SET CLASSPATH=%CLASSPATH%;target\classes  
 wsmapping.bat . . .

To create tables, run the wsmapping command from the ${WAS_HOME}/bin directory. When completed, the database tables are created or updated. Messages and errors are logged to the console as specified by log settings.

wsmapping.sh . . . On Windows :

Tip: By specifying the buildSchema parameter to the openjpa.jdbc.SynchronizeMappings property, the mapping tool provides the default mapping that matches with the database schema automatically. we are not required to run this mapping tool if the default mapping satisfies the necessary database schema.

 

Examples

To create the database tables needed for the Magazine.java file: [AIX] [HP-UX] [Linux] [Solaris]

${WAS_HOME}/bin/wsmapping.sh Magazine.java

(Windows)

${WAS_HOME}\bin\wsmapping.sh Magazine.java

To drop the tables for Magazine.java: [AIX] [HP-UX] [Linux] [Solaris]

C:\> %WAS_HOME%/bin/wsmapping.sh -sa dropDB Magazine.java

(Windows)

C:\> %WAS_HOME%\bin\wsmapping.bat -sa dropDB Magazine.java

To validate the mappings for all classes on the classpath: [AIX] [HP-UX] [Linux] [Solaris]

C:\> %WAS_HOME%/bin/wsmapping.sh -a validate

(Windows)

C:\> %WAS_HOME%\bin\wsmapping.bat -a validate

 

Additional information

Consult chapter 7, Mapping in the OpenJPA reference documentation for more information and examples.

---

 

Related

Develop and packaging JPA applications for a Java EE environment
Develop and packaging JPA applications for a Java SE environment

 

Related information

http://openjpa.apache.org/docs/latest/manual/manual.html#ref_guide_mapping_mappingtool