openjpa/openjpa-project/src/doc/manual/ref_guide_integration.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
 http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.   
-->
<chapter id="ref_guide_integration">
    <title>
        Third Party Integration
    </title>
    <para>
OpenJPA provides a number of mechanisms for integrating with third-party tools.
The following chapter will illustrate these integration features.
    </para>
    <section id="ref_guide_integration_ant">
        <title>
            Apache Ant
        </title>
        <indexterm zone="ref_guide_integration_ant">
            <primary>
                Ant
            </primary>
        </indexterm>
        <para>
Ant is a very popular tool for building Java projects. It is similar to the
<literal>make</literal> 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 <ulink url="http://jakarta.apache.org/ant/"> http://jakarta.apache.org/ant/
</ulink>. 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 <filename>build.xml</filename> files.
        </para>
        <para>
OpenJPA provides pre-built Ant task definitions for all bundled tools:
        </para>
        <itemizedlist>
            <listitem>
                <para>
<link linkend="ref_guide_integration_enhance">Enhancer Task</link>
                </para>
            </listitem>
            <listitem>
                <para>
<link linkend="ref_guide_integration_appidtool">Application Identity Tool Task
</link>
                </para>
            </listitem>
            <listitem>
                <para>
<link linkend="ref_guide_integration_mappingtool">Mapping Tool Task</link>
                </para>
            </listitem>
            <listitem>
                <para>
<link linkend="ref_guide_integration_revmappingtool">Reverse Mapping Tool Task
</link>
                </para>
            </listitem>
            <listitem>
                <para>
<link linkend="ref_guide_integration_schematool">Schema Tool Task</link>
                </para>
            </listitem>
        </itemizedlist>
        <para>
The source code for all the ant tasks is provided with the distribution under
the <filename>src</filename> directory. This allows you to customize various
aspects of the ant tasks in order to better integrate into your development
environment.
        </para>
        <section id="ref_guide_integration_conf">
            <title>
                Common Ant Configuration Options
            </title>
            <indexterm>
                <primary>
                    Ant
                </primary>
                <secondary>
                    configuration options
                </secondary>
            </indexterm>
            <para>
All OpenJPA tasks accept a nested <literal>config</literal> element, which
defines the configuration environment in which the specified task will run. The
attributes for the <literal>config</literal> tag are defined by the
<ulink url="../javadoc/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html">
<classname>JDBCConfiguration</classname></ulink> bean methods. Note that
excluding the <literal>config</literal> element will cause the Ant task to use
the default system configuration mechanism, such as the configuration defined in
the <filename>org.apache.openjpa.xml</filename> file.
            </para>
            <para>
Following is an example of how to use the nested <literal>config</literal> tag
in a <filename>build.xml</filename> file:
            </para>
            <example id="ref_guide_integration_conf_config">
                <title>
                    Using the &lt;config&gt; Ant Tag
                </title>
<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;
</programlisting>
            </example>
            <para>
It is also possible to specify a <literal>properties</literal> or <literal>
propertiesFile</literal> attribute on the <literal>config</literal> tag, which
will be used to locate a properties resource or file. The resource will be
loaded relative to the current CLASSPATH.
            </para>
            <example id="ref_guide_integration_props">
                <title>
                    Using the Properties Attribute of the &lt;config&gt; Tag
                </title>
<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;
</programlisting>
            </example>
            <example id="ref_guide_integration_propsfile">
                <title>
                    Using the PropertiesFile Attribute of the &lt;config&gt; Tag
                </title>
<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;
</programlisting>
            </example>
            <para>
Tasks also accept a nested <literal>classpath</literal> element, which you can
use in place of the default classpath. The <literal>classpath</literal> argument
behaves the same as it does for Ant's standard <literal>javac</literal> 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 <literal>classpath</literal> element that includes
the target class directory needs to be included so the enhancer and mapping tool
can locate the relevant classes.
            </para>
            <para>
Following is an example of using a <literal>classpath</literal> tag:
            </para>
            <example id="ref_guide_integration_conf_classpath">
                <title>
                    Using the &lt;classpath&gt; Ant Tag
                </title>
<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;
</programlisting>
            </example>
            <para>
Finally, tasks that invoke code-generation tools like the application identity
tool and reverse mapping tool accept a nested <literal>codeformat</literal>
element. See the code formatting documentation in
<xref linkend="ref_guide_conf_devtools_format"/> for a list of code
formatting attributes.
            </para>
            <example id="ref_guide_integration_conf_codeformat">
                <title>
                    Using the &lt;codeformat&gt; Ant Tag
                </title>
<programlisting>
&lt;reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"&gt;
  &lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
&lt;/reversemappingtool&gt;
</programlisting>
            </example>
        </section>
        <section id="ref_guide_integration_enhance">
            <title>
                Enhancer Ant Task
            </title>
            <indexterm zone="ref_guide_integration_enhance">
                <primary>
                    Ant
                </primary>
                <secondary>
                    enhancer task
                </secondary>
            </indexterm>
            <indexterm zone="ref_guide_integration_enhance">
                <primary>
                    enhancer
                </primary>
                <secondary>
                    Ant task
                </secondary>
            </indexterm>
            <para>
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 
<link linkend="ref_guide_pc_enhance"><classname>
org.apache.openjpa.enhance.PCEnhancer</classname></link>.
            </para>
            <para>
The enhancer task accepts a nested <literal>fileset</literal> tag to specify the
files that should be processed. You can specify <filename>.java</filename> or
<filename>.class</filename> files. If you do not specify any files, the task
will run on the classes listed in your <filename>persistence.xml</filename> or
<link linkend="openjpa.MetaDataFactory"><literal>
openjpa.MetaDataFactory</literal></link> property.
            </para>
            <para>
Following is an example of using the enhancer task in a <filename>build.xml
</filename> file:
            </para>
            <example id="ref_guide_integration_enhance_task">
                <title>
                    Invoking the Enhancer from Ant
                </title>
<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;
</programlisting>
            </example>
        </section>
        <section id="ref_guide_integration_appidtool">
            <title>
                Application Identity Tool Ant Task
            </title>
            <indexterm zone="ref_guide_integration_enhance">
                <primary>
                    Ant
                </primary>
                <secondary>
                    application identity tool task
                </secondary>
            </indexterm>
            <indexterm zone="ref_guide_integration_enhance">
                <primary>
                    application identity tool
                </primary>
                <secondary>
                    Ant task
                </secondary>
            </indexterm>
            <para>
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
<link linkend="ref_guide_pc_appid_appidtool"><classname>
org.apache.openjpa.enhance.ApplicationIdTool</classname></link>.
            </para>
            <para>
The application identity tool task accepts a nested <literal>fileset</literal>
tag to specify the files that should be processed. You can specify <filename>
.java</filename> or <filename>.class</filename> files. If you do not specify any
files, the task will run on the classes listed in your <filename>persistence.xml
</filename> file or <link linkend="openjpa.MetaDataFactory"><literal>
openjpa.MetaDataFactory</literal></link> property.
            </para>
            <para>
Following is an example of using the application identity tool task in a
<filename>build.xml</filename> file:
            </para>
            <example id="ref_guide_integration_appidtool_task">
                <title>
                    Invoking the Application Identity Tool from Ant
                </title>
<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;
</programlisting>
            </example>
        </section>
        <section id="ref_guide_integration_mappingtool">
            <title>
                Mapping Tool Ant Task
            </title>
            <indexterm zone="ref_guide_integration_mappingtool">
                <primary>
                    Ant
                </primary>
                <secondary>
                    mapping tool task
                </secondary>
            </indexterm>
            <indexterm zone="ref_guide_integration_mappingtool">
                <primary>
                    mapping tool
                </primary>
                <secondary>
                    Ant task
                </secondary>
            </indexterm>
            <para>
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 <link linkend="ref_guide_mapping_mappingtool">
<classname>org.apache.openjpa.jdbc.meta.MappingTool</classname></link>.
            </para>
            <para>
The mapping tool task accepts a nested <literal>fileset</literal> tag to specify
the files that should be processed. You can specify <filename>.java</filename>
or <filename>.class</filename> files. If you do not specify any files, the task
will run on the classes listed in your <filename>persistence.xml</filename> file
or <link linkend="openjpa.MetaDataFactory"><literal>
openjpa.MetaDataFactory</literal></link> property.
            </para>
            <para>
Following is an example of a <filename>build.xml</filename> target that invokes
the mapping tool:
            </para>
            <example id="ref_guide_integration_mappingtool_task">
                <title>
                    Invoking the Mapping Tool from Ant
                </title>
<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;
</programlisting>
            </example>
        </section>
        <section id="ref_guide_integration_revmappingtool">
            <title>
                Reverse Mapping Tool Ant Task
            </title>
            <indexterm zone="ref_guide_integration_revmappingtool">
                <primary>
                    Ant
                </primary>
                <secondary>
                    reverse mapping tool task
                </secondary>
            </indexterm>
            <indexterm zone="ref_guide_integration_revmappingtool">
                <primary>
                    reverse mapping tool
                </primary>
                <secondary>
                    Ant task
                </secondary>
            </indexterm>
            <para>
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
<link linkend="ref_guide_pc_reverse_reversemappingtool"><classname>
org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></link>.
            </para>
            <para>
Following is an example of a <filename>build.xml</filename> target that invokes
the reverse mapping tool:
            </para>
            <example id="ref_guide_integration_revmappingtool_task">
                <title>
                    Invoking the Reverse Mapping Tool from Ant
                </title>
<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;
</programlisting>
            </example>
        </section>
        <section id="ref_guide_integration_schematool">
            <title>
                Schema Tool Ant Task
            </title>
            <indexterm zone="ref_guide_integration_schematool">
                <primary>
                    Ant
                </primary>
                <secondary>
                    schema tool task
                </secondary>
            </indexterm>
            <indexterm zone="ref_guide_integration_schematool">
                <primary>
                    schema tool
                </primary>
                <secondary>
                    Ant task
                </secondary>
            </indexterm>
            <para>
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
<link linkend="ref_guide_schema_schematool"><classname>
org.apache.openjpa.jdbc.schema.SchemaTool</classname></link>.
            </para>
            <para>
Following is an example of a <filename>build.xml</filename> target that invokes
the schema tool:
            </para>
            <example id="ref_guide_integration_schematool_task">
                <title>
                    Invoking the Schema Tool from Ant
                </title>
<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;
</programlisting>
            </example>
        </section>
    </section>
</chapter>