openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] OpenJPA > Migration Tool
Date Wed, 11 Aug 2010 17:21:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/5/_/styles/combined.css?spaceKey=openjpa&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/openjpa/Migration+Tool">Migration
Tool</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~drwoods">Donald
Woods</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        added links to prebuilt jar and source code<br />
    </div>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >This command-line utility translates
proprietary mapping descriptors to standard JPA mapping descriptors. <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Download <br> <br>The latest OpenJPA Tools JAR file can be download from the [SNAPSHOT
Repository|https://repository.apache.org/content/repositories/snapshots/org/apache/openjpa/tools/openjpa-tools/0.1.0-SNAPSHOT/]
or can be built from the source code in [svn|https://svn.apache.org/repos/asf/openjpa/tools/trunk]
by using Maven 2.2.1 and Java SE 6. <br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3.Usage: <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="MigrationTool-MigrationTool"></a>Migration Tool</h1>

<p>This command-line utility translates proprietary mapping descriptors to standard
JPA mapping descriptors.</p>

<h3><a name="MigrationTool-Download"></a>Download</h3>

<p>The latest OpenJPA Tools JAR file can be download from the <a href="https://repository.apache.org/content/repositories/snapshots/org/apache/openjpa/tools/openjpa-tools/0.1.0-SNAPSHOT/"
class="external-link" rel="nofollow">SNAPSHOT Repository</a> or can be built from
the source code in <a href="https://svn.apache.org/repos/asf/openjpa/tools/trunk" class="external-link"
rel="nofollow">svn</a> by using Maven 2.2.1 and Java SE 6.</p>


<h3><a name="MigrationTool-Usage%3A"></a>Usage:</h3>

<blockquote><p>$ <tt>java org.apache.openjpa.tools.MigrationTool -input
xyz.xml -output xyz.orm.xml -error error.txt+ -actions migration-actions.xml -verbose</tt></p></blockquote>
<p>where</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'>-input </td>
<td class='confluenceTd'> 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</td>
</tr>
<tr>
<td class='confluenceTd'>-output</td>
<td class='confluenceTd'> output location of the translated mapping descriptor file.
This option is not mandatory. If unspecified, the output is simply printed on the standard
console. </td>
</tr>
<tr>
<td class='confluenceTd'>-error </td>
<td class='confluenceTd'> output location of the non-translatable attributes or elements.
Adding a + sign at the end of the file name will append the warning messages to an existing
file. This option is not mandatory. If unspecified, the output is printed on the standard
error console. </td>
</tr>
<tr>
<td class='confluenceTd'>-actions</td>
<td class='confluenceTd'> the actions to be performed on every element of the input
descriptor elements. These actions are specified as XML elements compliant to a <a href="http://fisheye6.atlassian.com/browse/openjpa/tools/trunk/openjpa-tools/src/main/resources/META-INF/migration-actions.xsd?r=HEAD"
class="external-link" rel="nofollow">XML schema</a>. A template of these actions
for a <em>subset</em> of Hibernate elements is included in <a href="http://fisheye6.atlassian.com/browse/openjpa/tools/trunk/openjpa-tools/src/main/resources/META-INF/migration-actions.xml?r=HEAD"
class="external-link" rel="nofollow">migration-actions.xml</a>. <br/>
This option is not mandatory. The archetype for translating Hibernate mapping descriptor is
used as a default.</td>
</tr>
<tr>
<td class='confluenceTd'>-verbose</td>
<td class='confluenceTd'>prints detailed trace of what the tool is doing. This option
is not mandatory. If unspecified,  detailed messages are not printed.</td>
</tr>
</tbody></table>
</div>



<h2><a name="MigrationTool-Discussion"></a>Discussion</h2>

<p>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.<br/>
For example, consider the input fragment</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;class name=<span class="code-quote">"com.approuter.deploy.Project"</span>
table=<span class="code-quote">"PROJECTS"</span> select-before-update=<span
class="code-quote">"false"</span>&gt;</span>
  <span class="code-tag">&lt;id name=<span class="code-quote">"id"</span>
type=<span class="code-quote">"java.lang.Long"</span> column=<span class="code-quote">"ID"</span>&gt;</span>
	<span class="code-tag">&lt;generator class=<span class="code-quote">"native"</span>
/&gt;</span>
  <span class="code-tag">&lt;/id&gt;</span>
<span class="code-tag">&lt;/class&gt;</span>
</pre>
</div></div>

<p>This fragment will be translated by the tool as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;entity class=<span class="code-quote">"com.approuter.deploy.Project"</span>&gt;</span>
    <span class="code-tag">&lt;table name=<span class="code-quote">"PROJECTS"</span>/&gt;</span>
    <span class="code-tag">&lt;attributes&gt;</span>
      <span class="code-tag">&lt;id name=<span class="code-quote">"id"</span>&gt;</span>
        <span class="code-tag">&lt;column name=<span class="code-quote">"ID"</span>/&gt;</span>
        <span class="code-tag">&lt;generated-value strategy=<span class="code-quote">"AUTO"</span>/&gt;</span>
      <span class="code-tag">&lt;/id&gt;</span>
    <span class="code-tag">&lt;/attributes&gt;</span>
<span class="code-tag">&lt;/entity&gt;</span>
</pre>
</div></div>

<p>The series of actions that translated this fragments are as follows:</p>
<ul>
	<li>The input element <tt>&lt;class&gt;</tt> is translated to <tt>&lt;entity&gt;</tt>
element.</li>
	<li>The <tt>name</tt> attribute of input element <tt>&lt;class&gt;</tt>
is translated to <tt>class</tt> attribute. The value of the attribute remained
intact.</li>
	<li>the <tt>table</tt> attribute of input element <tt>&lt;class&gt;</tt>
is translated to a new element <tt>&lt;table&gt;</tt>. The value of the
<tt>table</tt> attribute appeared as <tt>name</tt> attribute in the
translated element.</li>
	<li>the attribute <tt>select-before-update</tt> 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.</li>
	<li>a new element <tt>&lt;attributes&gt;</tt> appeared in the translated
document which had no equivalent counterpart in the original document.</li>
	<li>the <tt>column</tt> attribute of input element <tt>&lt;id&gt;</tt>
is translated to a new element <tt>&lt;column&gt;</tt>. The value of the
<tt>column</tt> attribute appeared as <tt>name</tt> attribute in the
translated element.</li>
	<li>the input element <tt>&lt;generator&gt;</tt> is translated
to <tt>&lt;generated-value&gt;</tt> element.</li>
	<li>the <tt>class</tt> attribute of input element <tt>&lt;generator&gt;</tt>
is translated to a <tt>strategy</tt> attribute. The value of the attribute is
translated from <tt>native</tt> to <tt>AUTO</tt>.</li>
</ul>



<p>The translation was carried out by a series of <em>generic</em>, <em>parameterized</em>
<em>actions</em>. The actions are specified in <a href="http://fisheye6.atlassian.com/browse/openjpa/tools/trunk/openjpa-tools/src/main/resources/META-INF/migration-actions.xml?r=HEAD"
class="external-link" rel="nofollow">migration-actions.xml</a>. Here is a snippet
from that archetype to define those generic actions and their parameters.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;actions for=<span class="code-quote">"class"</span>&gt;</span>
        <span class="code-tag">&lt;rename-node to=<span class="code-quote">"entity"</span>/&gt;</span>
	<span class="code-tag">&lt;rename-attr from=<span class="code-quote">"name"</span>
to=<span class="code-quote">"class"</span>/&gt;</span>
	<span class="code-tag">&lt;promote-attr from=<span class="code-quote">"table"</span>
to=<span class="code-quote">"table"</span> as=<span class="code-quote">"name"</span>/&gt;</span>
	<span class="code-tag">&lt;ignore-attr name=<span class="code-quote">"select-before-update"</span>/&gt;</span>
	<span class="code-tag">&lt;ignore-attr name=<span class="code-quote">"type"</span>/&gt;</span>
	<span class="code-tag">&lt;insert-node name=<span class="code-quote">"attributes"</span>/&gt;</span>
<span class="code-tag">&lt;/actions&gt;</span>
<span class="code-tag">&lt;actions for=<span class="code-quote">"id"</span>&gt;</span>
    <span class="code-tag">&lt;rename-node to=<span class="code-quote">"id"</span>/&gt;</span>
    <span class="code-tag">&lt;rename-attr from=<span class="code-quote">"name"</span>
to=<span class="code-quote">"name"</span>/&gt;</span>
    <span class="code-tag">&lt;promote-attr from=<span class="code-quote">"column"</span>
to=<span class="code-quote">"column"</span> as=<span class="code-quote">"name"</span>&gt;</span>
		<span class="code-tag">&lt;consume-attr from=<span class="code-quote">"length"</span>
to=<span class="code-quote">"length"</span>/&gt;</span>
		<span class="code-tag">&lt;consume-attr from=<span class="code-quote">"unique"</span>
to=<span class="code-quote">"unique"</span>/&gt;</span>
    <span class="code-tag">&lt;/promote-attr&gt;</span>
    <span class="code-tag">&lt;ignore-attr name=<span class="code-quote">"type"</span>/&gt;</span>
<span class="code-tag">&lt;/actions&gt;</span>
<span class="code-tag">&lt;actions for=<span class="code-quote">"generator"</span>&gt;</span>
    <span class="code-tag">&lt;rename-node to=<span class="code-quote">"generated-value"</span>/&gt;</span>
    <span class="code-tag">&lt;rename-attr from=<span class="code-quote">"class"</span>
to=<span class="code-quote">"strategy"</span>&gt;</span>
		<span class="code-tag">&lt;map-value from=<span class="code-quote">"native"</span>
  to=<span class="code-quote">"AUTO"</span>/&gt;</span>
		<span class="code-tag">&lt;map-value from=<span class="code-quote">"assigned"</span>
to=<span class="code-quote">"IDENTITY"</span>/&gt;</span>
     <span class="code-tag">&lt;/rename-attr&gt;</span>
<span class="code-tag">&lt;/actions&gt;</span>
</pre>
</div></div>

<p>The schema that specifies what actions are supported and their parameters are defined
in a <a href="http://fisheye6.atlassian.com/browse/openjpa/tools/trunk/openjpa-tools/src/main/resources/META-INF/migration-actions.xsd?r=HEAD"
class="external-link" rel="nofollow">XML schema</a>.</p>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Work in Progress</b><br
/>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.</td></tr></table></div>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/openjpa/Migration+Tool">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=23333898&revisedVersion=5&originalVersion=4">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/openjpa/Migration+Tool?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message