Google Git
Sign in
apache / openjpa-site / f4f8b894b02554a0a851bbf380ef41d45c445062 / . / content / builds / 1.0.3 / apache-openjpa-1.0.3 / docs / manual / ref_guide_integration.html
blob: b2e957963839c12f1e89d77d10bd7087fba27383 [file] [log] [blame]
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter&nbsp;12.&nbsp; Third Party Integration</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA User's Guide"><link rel="up" href="ref_guide.html" title="Part&nbsp;3.&nbsp;Reference Guide"><link rel="prev" href="ref_guide_event.html" title="2.&nbsp; Remote Event Notification Framework"><link rel="next" href="ref_guide_optimization.html" title="Chapter&nbsp;13.&nbsp; Optimization Guidelines"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;12.&nbsp;
Third Party Integration
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_event.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;3.&nbsp;Reference Guide</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_optimization.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en" id="ref_guide_integration"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_integration"></a>Chapter&nbsp;12.&nbsp;
Third Party Integration
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_ant">1.
Apache Ant
</a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_conf">1.1.
Common Ant Configuration Options
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_enhance">1.2.
Enhancer Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_appidtool">1.3.
Application Identity Tool Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_mappingtool">1.4.
Mapping Tool Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_revmappingtool">1.5.
Reverse Mapping Tool Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_schematool">1.6.
Schema Tool Ant Task
</a></span></dt></dl></dd></dl></div><p>
OpenJPA provides a number of mechanisms for integrating with third-party tools.
The following chapter will illustrate these integration features.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_integration_ant"></a>1.&nbsp;
Apache Ant
</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_conf">1.1.
Common Ant Configuration Options
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_enhance">1.2.
Enhancer Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_appidtool">1.3.
Application Identity Tool Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_mappingtool">1.4.
Mapping Tool Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_revmappingtool">1.5.
Reverse Mapping Tool Ant Task
</a></span></dt><dt><span class="section"><a href="ref_guide_integration.html#ref_guide_integration_schematool">1.6.
Schema Tool Ant Task
</a></span></dt></dl></div><a class="indexterm" name="d0e29633"></a><p>
Ant is a very popular tool for building Java projects. It is similar to the
<code class="literal">make</code> command, but is Java-centric and has more modern
features. Ant is open source, and can be downloaded from Apache's Ant web page
at <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jakarta.apache.org/ant/" target="_top"> http://jakarta.apache.org/ant/
</a>. Ant has become the de-facto standard build tool for Java, and many
commercial integrated development environments provide some support for using
ant build files. The remainder of this section assumes familiarity with writing
Ant <code class="filename">build.xml</code> files.
</p><p>
OpenJPA provides pre-built Ant task definitions for all bundled tools:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="ref_guide_integration.html#ref_guide_integration_enhance" title="1.2.&nbsp; Enhancer Ant Task">Enhancer Task</a>
</p></li><li><p>
<a href="ref_guide_integration.html#ref_guide_integration_appidtool" title="1.3.&nbsp; Application Identity Tool Ant Task">Application Identity Tool Task
</a>
</p></li><li><p>
<a href="ref_guide_integration.html#ref_guide_integration_mappingtool" title="1.4.&nbsp; Mapping Tool Ant Task">Mapping Tool Task</a>
</p></li><li><p>
<a href="ref_guide_integration.html#ref_guide_integration_revmappingtool" title="1.5.&nbsp; Reverse Mapping Tool Ant Task">Reverse Mapping Tool Task
</a>
</p></li><li><p>
<a href="ref_guide_integration.html#ref_guide_integration_schematool" title="1.6.&nbsp; Schema Tool Ant Task">Schema Tool Task</a>
</p></li></ul></div><p>
The source code for all the ant tasks is provided with the distribution under
the <code class="filename">src</code> directory. This allows you to customize various
aspects of the ant tasks in order to better integrate into your development
environment.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_conf"></a>1.1.&nbsp;
Common Ant Configuration Options
</h3></div></div></div><a class="indexterm" name="d0e29688"></a><p>
All OpenJPA tasks accept a nested <code class="literal">config</code> element, which
defines the configuration environment in which the specified task will run. The
attributes for the <code class="literal">config</code> tag are defined by the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html" target="_top">
<code class="classname">JDBCConfiguration</code></a> bean methods. Note that
excluding the <code class="literal">config</code> element will cause the Ant task to use
the default system configuration mechanism, such as the configuration defined in
the <code class="filename">org.apache.openjpa.xml</code> file.
</p><p>
Following is an example of how to use the nested <code class="literal">config</code> tag
in a <code class="filename">build.xml</code> file:
</p><div class="example"><a name="ref_guide_integration_conf_config"></a><p class="title"><b>Example&nbsp;12.1.&nbsp;
Using the &lt;config&gt; Ant Tag
</b></p><div class="example-contents"><pre class="programlisting">
&lt;mappingtool&gt;
&lt;fileset dir="${basedir}"&gt;
&lt;include name="**/model/*.java" /&gt;
&lt;/fileset&gt;
&lt;config connectionUserName="scott" connectionPassword="tiger"
connectionURL="jdbc:oracle:thin:@saturn:1521:solarsid"
connectionDriverName="oracle.jdbc.driver.OracleDriver" /&gt;
&lt;/mappingtool&gt;
</pre></div></div><br class="example-break"><p>
It is also possible to specify a <code class="literal">properties</code> or <code class="literal">
propertiesFile</code> attribute on the <code class="literal">config</code> tag, which
will be used to locate a properties resource or file. The resource will be
loaded relative to the current CLASSPATH.
</p><div class="example"><a name="ref_guide_integration_props"></a><p class="title"><b>Example&nbsp;12.2.&nbsp;
Using the Properties Attribute of the &lt;config&gt; Tag
</b></p><div class="example-contents"><pre class="programlisting">
&lt;mappingtool&gt;
&lt;fileset dir="${basedir}"&gt;
&lt;include name="**/model/*.java"/&gt;
&lt;/fileset&gt;
&lt;config properties="openjpa-dev.xml"/&gt;
&lt;/mappingtool&gt;
</pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_integration_propsfile"></a><p class="title"><b>Example&nbsp;12.3.&nbsp;
Using the PropertiesFile Attribute of the &lt;config&gt; Tag
</b></p><div class="example-contents"><pre class="programlisting">
&lt;mappingtool&gt;
&lt;fileset dir="${basedir}"&gt;
&lt;include name="**/model/*.java"/&gt;
&lt;/fileset&gt;
&lt;config propertiesFile="../conf/openjpa-dev.xml"/&gt;
&lt;/mappingtool&gt;
</pre></div></div><br class="example-break"><p>
Tasks also accept a nested <code class="literal">classpath</code> element, which you can
use in place of the default classpath. The <code class="literal">classpath</code> argument
behaves the same as it does for Ant's standard <code class="literal">javac</code> element.
It is sometimes the case that projects are compiled to a separate directory than
the source tree. If the target path for compiled classes is not included in the
project's classpath, then a <code class="literal">classpath</code> element that includes
the target class directory needs to be included so the enhancer and mapping tool
can locate the relevant classes.
</p><p>
Following is an example of using a <code class="literal">classpath</code> tag:
</p><div class="example"><a name="ref_guide_integration_conf_classpath"></a><p class="title"><b>Example&nbsp;12.4.&nbsp;
Using the &lt;classpath&gt; Ant Tag
</b></p><div class="example-contents"><pre class="programlisting">
&lt;openjpac&gt;
&lt;fileset dir="${basedir}/source"&gt;
&lt;include name="**/model/*.java" /&gt;
&lt;/fileset&gt;
&lt;classpath&gt;
&lt;pathelement location="${basedir}/classes"/&gt;
&lt;pathelement location="${basedir}/source"/&gt;
&lt;pathelement path="${java.class.path}"/&gt;
&lt;/classpath&gt;
&lt;/openjpac&gt;
</pre></div></div><br class="example-break"><p>
Finally, tasks that invoke code-generation tools like the application identity
tool and reverse mapping tool accept a nested <code class="literal">codeformat</code>
element. See the code formatting documentation in
<a href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format" title="3.1.&nbsp; Code Formatting">Section&nbsp;3.1, &#8220;
Code Formatting
&#8221;</a> for a list of code
formatting attributes.
</p><div class="example"><a name="ref_guide_integration_conf_codeformat"></a><p class="title"><b>Example&nbsp;12.5.&nbsp;
Using the &lt;codeformat&gt; Ant Tag
</b></p><div class="example-contents"><pre class="programlisting">
&lt;reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"&gt;
&lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
&lt;/reversemappingtool&gt;
</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_enhance"></a>1.2.&nbsp;
Enhancer Ant Task
</h3></div></div></div><a class="indexterm" name="d0e29785"></a><a class="indexterm" name="d0e29790"></a><p>
The enhancer task allows you to invoke the OpenJPA enhancer directly from within
the Ant build process. The task's parameters correspond exactly to the long
versions of the command-line arguments to the
<a href="ref_guide_pc_enhance.html" title="2.&nbsp; Enhancement"><code class="classname">
org.apache.openjpa.enhance.PCEnhancer</code></a>.
</p><p>
The enhancer task accepts a nested <code class="literal">fileset</code> tag to specify the
files that should be processed. You can specify <code class="filename">.java</code> or
<code class="filename">.class</code> files. If you do not specify any files, the task
will run on the classes listed in your <code class="filename">persistence.xml</code> or
<a href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.42.&nbsp; openjpa.MetaDataFactory"><code class="literal">
openjpa.MetaDataFactory</code></a> property.
</p><p>
Following is an example of using the enhancer task in a <code class="filename">build.xml
</code> file:
</p><div class="example"><a name="ref_guide_integration_enhance_task"></a><p class="title"><b>Example&nbsp;12.6.&nbsp;
Invoking the Enhancer from Ant
</b></p><div class="example-contents"><pre class="programlisting">
&lt;target name="enhance"&gt;
&lt;!-- define the openjpac task; this can be done at the top of the --&gt;
&lt;!-- build.xml file, so it will be available for all targets --&gt;
&lt;taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask"/&gt;
&lt;!-- invoke enhancer on all .java files below the model directory --&gt;
&lt;openjpac&gt;
&lt;fileset dir="."&gt;
&lt;include name="**/model/*.java" /&gt;
&lt;/fileset&gt;
&lt;/openjpac&gt;
&lt;/target&gt;
</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_appidtool"></a>1.3.&nbsp;
Application Identity Tool Ant Task
</h3></div></div></div><a class="indexterm" name="d0e29832"></a><a class="indexterm" name="d0e29837"></a><p>
The application identity tool task allows you to invoke the application identity
tool directly from within the Ant build process. The task's parameters
correspond exactly to the long versions of the command-line arguments to the
<a href="ref_guide_pc_oid.html#ref_guide_pc_appid_appidtool" title="Example&nbsp;5.7.&nbsp; Using the Application Identity Tool"><code class="classname">
org.apache.openjpa.enhance.ApplicationIdTool</code></a>.
</p><p>
The application identity tool task accepts a nested <code class="literal">fileset</code>
tag to specify the files that should be processed. You can specify <code class="filename">
.java</code> or <code class="filename">.class</code> files. If you do not specify any
files, the task will run on the classes listed in your <code class="filename">persistence.xml
</code> file or <a href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.42.&nbsp; openjpa.MetaDataFactory"><code class="literal">
openjpa.MetaDataFactory</code></a> property.
</p><p>
Following is an example of using the application identity tool task in a
<code class="filename">build.xml</code> file:
</p><div class="example"><a name="ref_guide_integration_appidtool_task"></a><p class="title"><b>Example&nbsp;12.7.&nbsp;
Invoking the Application Identity Tool from Ant
</b></p><div class="example-contents"><pre class="programlisting">
&lt;target name="appids"&gt;
&lt;!-- define the appidtool task; this can be done at the top of --&gt;
&lt;!-- the build.xml file, so it will be available for all targets --&gt;
&lt;taskdef name="appidtool" classname="org.apache.openjpa.ant.ApplicationIdToolTask"/&gt;
&lt;!-- invoke tool on all .jdo files below the current directory --&gt;
&lt;appidtool&gt;
&lt;fileset dir="."&gt;
&lt;include name="**/model/*.java" /&gt;
&lt;/fileset&gt;
&lt;codeformat spaceBeforeParen="true" braceOnSameLine="false"/&gt;
&lt;/appidtool&gt;
&lt;/target&gt;
</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_mappingtool"></a>1.4.&nbsp;
Mapping Tool Ant Task
</h3></div></div></div><a class="indexterm" name="d0e29879"></a><a class="indexterm" name="d0e29884"></a><p>
The mapping tool task allows you to directly invoke the mapping tool from within
the Ant build process. It is useful for making sure that the database schema and
object-relational mapping data is always synchronized with your persistent class
definitions, without needing to remember to invoke the mapping tool manually.
The task's parameters correspond exactly to the long versions of the
command-line arguments to the <a href="ref_guide_mapping.html#ref_guide_mapping_mappingtool" title="1.&nbsp; Forward Mapping">
<code class="classname">org.apache.openjpa.jdbc.meta.MappingTool</code></a>.
</p><p>
The mapping tool task accepts a nested <code class="literal">fileset</code> tag to specify
the files that should be processed. You can specify <code class="filename">.java</code>
or <code class="filename">.class</code> files. If you do not specify any files, the task
will run on the classes listed in your <code class="filename">persistence.xml</code> file
or <a href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.42.&nbsp; openjpa.MetaDataFactory"><code class="literal">
openjpa.MetaDataFactory</code></a> property.
</p><p>
Following is an example of a <code class="filename">build.xml</code> target that invokes
the mapping tool:
</p><div class="example"><a name="ref_guide_integration_mappingtool_task"></a><p class="title"><b>Example&nbsp;12.8.&nbsp;
Invoking the Mapping Tool from Ant
</b></p><div class="example-contents"><pre class="programlisting">
&lt;target name="refresh"&gt;
&lt;!-- define the mappingtool task; this can be done at the top of --&gt;
&lt;!-- the build.xml file, so it will be available for all targets --&gt;
&lt;taskdef name="mappingtool" classname="org.apache.openjpa.jdbc.ant.MappingToolTask"/&gt;
&lt;!-- add the schema components for all .jdo files below the --&gt;
&lt;!-- current directory --&gt;
&lt;mappingtool action="buildSchema"&gt;
&lt;fileset dir="."&gt;
&lt;include name="**/*.jdo" /&gt;
&lt;/fileset&gt;
&lt;/mappingtool&gt;
&lt;/target&gt;
</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_revmappingtool"></a>1.5.&nbsp;
Reverse Mapping Tool Ant Task
</h3></div></div></div><a class="indexterm" name="d0e29927"></a><a class="indexterm" name="d0e29932"></a><p>
The reverse mapping tool task allows you to directly invoke the reverse mapping
tool from within Ant. While many users will only run the reverse mapping process
once, others will make it part of their build process. The task's parameters
correspond exactly to the long versions of the command-line arguments to the
<a href="ref_guide_pc_reverse.html#ref_guide_pc_reverse_reversemappingtool" title="Example&nbsp;7.9.&nbsp; Using the Reverse Mapping Tool"><code class="classname">
org.apache.openjpa.jdbc.meta.ReverseMappingTool</code></a>.
</p><p>
Following is an example of a <code class="filename">build.xml</code> target that invokes
the reverse mapping tool:
</p><div class="example"><a name="ref_guide_integration_revmappingtool_task"></a><p class="title"><b>Example&nbsp;12.9.&nbsp;
Invoking the Reverse Mapping Tool from Ant
</b></p><div class="example-contents"><pre class="programlisting">
&lt;target name="reversemap"&gt;
&lt;!-- define the reversemappingtool task; this can be done at the top of --&gt;
&lt;!-- the build.xml file, so it will be available for all targets --&gt;
&lt;taskdef name="reversemappingtool"
classname="org.apache.openjpa.jdbc.ant.ReverseMappingToolTask"/&gt;
&lt;!-- reverse map the entire database --&gt;
&lt;reversemappingtool package="com.xyz.model" directory="${basedir}/src"
customizerProperties="${basedir}/conf/reverse.properties"&gt;
&lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
&lt;/reversemappingtool&gt;
&lt;/target&gt;
</pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_integration_schematool"></a>1.6.&nbsp;
Schema Tool Ant Task
</h3></div></div></div><a class="indexterm" name="d0e29956"></a><a class="indexterm" name="d0e29961"></a><p>
The schema tool task allows you to directly invoke the schema tool from within
the Ant build process. The task's parameters correspond exactly to the long
versions of the command-line arguments to the
<a href="ref_guide_schema_schematool.html" title="12.&nbsp; Schema Tool"><code class="classname">
org.apache.openjpa.jdbc.schema.SchemaTool</code></a>.
</p><p>
Following is an example of a <code class="filename">build.xml</code> target that invokes
the schema tool:
</p><div class="example"><a name="ref_guide_integration_schematool_task"></a><p class="title"><b>Example&nbsp;12.10.&nbsp;
Invoking the Schema Tool from Ant
</b></p><div class="example-contents"><pre class="programlisting">
&lt;target name="schema"&gt;
&lt;!-- define the schematool task; this can be done at the top of --&gt;
&lt;!-- the build.xml file, so it will be available for all targets --&gt;
&lt;taskdef name="schematool" classname="org.apache.openjpa.jdbc.ant.SchemaToolTask"/&gt;
&lt;!-- add the schema components for all .schema files below the --&gt;
&lt;!-- current directory --&gt;
&lt;schematool action="add"&gt;
&lt;fileset dir="."&gt;
&lt;include name="**/*.schema" /&gt;
&lt;/fileset&gt;
&lt;/schematool&gt;
&lt;/target&gt;
</pre></div></div><br class="example-break"></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_event.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_optimization.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;
Remote Event Notification Framework
&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;13.&nbsp;
Optimization Guidelines
</td></tr></table></div></body></html>