OpenJPA Logo   ASF Logo

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.
-verboseprints 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 is translated to element.
  • The name attribute of input element is translated to class attribute. The value of the attribute remained intact.
  • the table attribute of input element is translated to a new element . 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 appeared in the translated document which had no equivalent counterpart in the original document.
  • the column attribute of input element is translated to a new element . The value of the column attribute appeared as name attribute in the translated element.
  • the input element is translated to element.
  • the class attribute of input element 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.

    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.

Copyright © 2006,2013 The Apache Software Foundation. Licensed under Apache License 2.0.
Apache, the Apache feather logo and OpenJPA are trademarks of The Apache Software Foundation.
Other names may be trademarks of their respective owners.