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

    <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="../apidocs/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 
      <phrase><filename>org.apache.openjpa.xml</filename></phrase>
      
      
      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 format="linespecific">
&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 format="linespecific">
&lt;mappingtool&gt;
  &lt;fileset dir="${basedir}"&gt;
    &lt;include name="**/model/*.java"/&gt;
  &lt;/fileset&gt;
  &lt;config properties="openjpa-dev.properties"/&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 format="linespecific">
&lt;mappingtool&gt;
  &lt;fileset dir="${basedir}"&gt;
    &lt;include name="**/model/*.java"/&gt;
  &lt;/fileset&gt;
  &lt;config propertiesFile="../conf/openjpa-dev.properties"/&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 format="linespecific">
&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 format="linespecific">
&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 <link linkend="ref_guide_pc_enhance"><literal>openjpac</literal></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 <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 format="linespecific">
&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 .jdo files below the current 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
      <link linkend="ref_guide_pc_appid_appidtool"><literal>appidtool</literal></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 <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 format="linespecific">
&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"><literal>
      mappingtool</literal></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 <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 format="linespecific">
&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"><literal>
      reversemappingtool</literal></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 format="linespecific">
&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"><literal>
      schematool</literal></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 format="linespecific">
&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>
      <section id="ref_guide_integration_maven">
        <title>Maven</title>
        <indexterm zone="ref_guide_integration_maven">
          <primary>Maven</primary>
        </indexterm>
      </section>
    </chapter>