Migration Tool

This command-line utility translates proprietary mapping descriptors to standard JPA mapping descriptors.

Download

The latest OpenJPA Tools JAR file can be download from the SNAPSHOT Repository or can be built from the source code in svn by using Maven 2.2.1 and Java SE 6.

Usage:

  $ java org.apache.openjpa.tools.MigrationTool -input xyz.xml [-output xyz.orm.xml] [-actions migration-actions.xml] [-verbose true]

where

-input

input location of the proprietary XML mapping descriptor resource. The resource is looked up in the current classpath. If not located as a resource, then looked up as an input file in relative to the current directory. This option is mandatory

-output

output location of the translated mapping descriptor file. This option is not mandatory. If unspecified, the output is simply printed on the standard console.

-actions

the actions to be performed on every element of the input descriptor elements. These actions are specified as XML elements compliant to a XML schema. A template of these actions for a subset of Hibernate elements is included in migration-actions.xml.
This option is not mandatory. The archetype for translating Hibernate mapping descriptor is used as a default.

-verbose

prints detailed trace of what the tool is doing. This option is not mandatory. If unspecified, detailed messages are not printed.

Discussion

This tool takes each top-level element of the input mapping descriptor and applies one or more actions to translate it to a standard JPA mapping descriptor.
For example, consider the input fragment

<class name="com.approuter.deploy.Project" table="PROJECTS" select-before-update="false">
  <id name="id" type="java.lang.Long" column="ID">
	<generator class="native" />
  </id>
</class>

This fragment will be translated by the tool as follows:

<entity class="com.approuter.deploy.Project">
    <table name="PROJECTS"/>
    <attributes>
      <id name="id">
        <column name="ID"/>
        <generated-value strategy="AUTO"/>
      </id>
    </attributes>
</entity>

The series of actions that translated this fragments are as follows:

  • The input element <class> is translated to <entity> element.
  • The name attribute of input element <class> is translated to class attribute. The value of the attribute remained intact.
  • the table attribute of input element <class> is translated to a new element <table>. The value of the table attribute appeared as name attribute in the translated element.
  • the attribute select-before-update is ignored as it does not have a direct counterpart in standard JPA mapping descriptor. Actually this attribute controls runtime behavior and it is debatable whether a mapping descriptor is the proper place for such an attribute.
  • a new element <attributes> appeared in the translated document which had no equivalent counterpart in the original document.
  • the column attribute of input element <id> is translated to a new element <column>. The value of the column attribute appeared as name attribute in the translated element.
  • the input element <generator> is translated to <generated-value> element.
  • the class attribute of input element <generator> is translated to a strategy attribute. The value of the attribute is translated from native to AUTO.

The translation was carried out by a series of generic, parameterized actions. The actions are specified in migration-actions.xml. Here is a snippet from that archetype to define those generic actions and their parameters.

<actions for="class">
        <rename-node to="entity"/>
	<rename-attr from="name" to="class"/>
	<promote-attr from="table" to="table" as="name"/>
	<ignore-attr name="select-before-update"/>
	<ignore-attr name="type"/>
	<insert-node name="attributes"/>
</actions>
<actions for="id">
    <rename-node to="id"/>
    <rename-attr from="name" to="name"/>
    <promote-attr from="column" to="column" as="name">
		<consume-attr from="length" to="length"/>
		<consume-attr from="unique" to="unique"/>
    </promote-attr>
    <ignore-attr name="type"/>
</actions>
<actions for="generator">
    <rename-node to="generated-value"/>
    <rename-attr from="class" to="strategy">
		<map-value from="native"   to="AUTO"/>
		<map-value from="assigned" to="IDENTITY"/>
     </rename-attr>
</actions>

The schema that specifies what actions are supported and their parameters are defined in a XML schema.

Work in Progress

This tool is at experimental stage of development and does not cater to all possible variations that such a translation may require. However, that is why the design allows new custom actions be defined and applied to cater to more complex use cases.

  • No labels