openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mprud...@apache.org
Subject svn commit: r433761 [12/18] - in /incubator/openjpa/trunk/openjpa-project: ./ src/doc/manual/
Date Tue, 22 Aug 2006 21:28:55 GMT
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,224 @@
+
+    <chapter id="ref_guide_deploy">
+      <title>Deployment</title>
+      <para>
+  OpenJPA deployment includes choosing a factory deployment strategy,
+  and in a managed environment, optionally integrating with your application
+  server's managed and XA transactions.  This chapter examines each aspect
+  of deployment in turn.
+  </para>
+      <section id="ref_guide_deploy_factory">
+        <title>Factory Deployment</title>
+        <para>
+    OpenJPA offers several 
+    <phrase><classname>EntityManagerFactory</classname></phrase>
+    
+    
+    deployment options.
+    </para>
+        <section id="ref_guide_deploy_factory_standalone">
+          <title>Standalone Deployment</title>
+          <indexterm zone="ref_guide_deploy_factory_standalone">
+            <primary>deployment</primary>
+            <secondary>standalone</secondary>
+            <seealso>Persistence</seealso>
+          </indexterm>
+          <para>
+      The JPA Overview describes the 
+      <classname>javax.persistence.Persistence</classname> class.  You 
+      can use <classname>Persistence</classname> to obtain 
+      <classname>EntityManagerFactory</classname> instances, as 
+      demonstrated in <xref linkend="jpa_overview_persistence"/>.
+      OpenJPA also extends <classname>Persistence</classname> to add
+      additional <classname>EntityManagerFactory</classname> 
+      creation methods.  The
+      <classname>org.apache.openjpa.persistence.OpenJPAPersistence</classname> class
+      <ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html">
+      Javadoc</ulink> details these extensions.
+      </para>
+          <para>
+      After obtaining the factory, you can cache it for all 
+      <phrase><classname>EntityManager</classname></phrase>
+       
+      
+      creation duties.
+      </para>
+        </section>
+        <section id="ref_guide_deploy_inject">
+          <title>EntityManager Injection</title>
+<!-- ### EJBDOC -->
+          <para>
+      To be decided.
+      </para>
+        </section>
+        <section id="ref_guide_deploy_jca_ejb">
+          <title>OpenJPA JCA Deployment</title>
+          <indexterm zone="ref_guide_deploy_jca_ejb">
+            <primary>deployment</primary>
+            <secondary>JCA</secondary>
+            <seealso>JCA</seealso>
+          </indexterm>
+          <indexterm zone="ref_guide_deploy_jca_ejb">
+            <primary>JCA</primary>
+            <secondary>deployment</secondary>
+          </indexterm>
+          <para>
+      OpenJPA can deploy OpenJPA through the Java Connector Architecture
+      (JCA) in any JCA-compliant application server that supports
+      JDK 1.5 (all EJB 3 implementations require JDK 1.5).  We present
+      the deployment steps for the most common servers below.
+      </para>
+          <section id="ref_guide_deploy_jca_jpa_weblogic9">
+            <title>WebLogic 9</title>
+            <indexterm zone="ref_guide_deploy_jca_jpa_weblogic9">
+              <primary>Weblogic</primary>
+            </indexterm>
+            <indexterm zone="ref_guide_deploy_jca_jpa_weblogic9">
+              <primary>JCA</primary>
+              <secondary>Weblogic 9</secondary>
+            </indexterm>
+            <para><!-- ### JDO2MIG : everything in system path for now -->
+        First, ensure that your JDBC driver is in your system classpath.
+        In addition, you will be adding the OpenJPA and specification API
+        jars to the system classpath.  You can accomplish this by
+        editing <filename>startWebLogic.sh/.cmd</filename>.
+        </para>
+            <warning>
+              <para>Currently WebLogic ships with an old version
+          of the EJB 3 libraries.  Be sure to put 
+          <filename>org.apache.openjpa.jar</filename> in the <emphasis>beginning
+          </emphasis> of the <literal>CLASSPATH</literal>.</para>
+            </warning>
+            <para>
+        The next step is to deploy 
+        <filename>openjpa-persistence.rar</filename> from the 
+        <filename>jca/persistence</filename> directory of your OpenJPA
+        installation.  Copy this file to the <filename>autodeploy
+        </filename> directory of your domain.  
+        </para>
+            <para>
+        We will now extract <filename>META-INF/ra.xml</filename>
+        and <filename>META-INF/weblogic-ra.xml</filename>
+        to edit our configuration:
+        </para>
+            <programlisting format="linespecific">
+jar xvf openjpa-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml
+</programlisting>
+            <para>
+        Now you should configure OpenJPA JCA by editing
+        <filename>META-INF/ra.xml</filename> substituting
+        <literal>config-property-value</literal> stanzas
+        with your own values.  You can comment out
+        properties (config-property stanzas) which you are
+        not using or you can leave them at their default settings.
+        Edit <filename>META-INF/weblogic-ra.xml</filename>
+        to configure the JNDI location to which you
+        want OpenJPA to be bound.
+        </para>
+            <para>
+        Now we can re-jar the manifest files back into the 
+        <filename>RAR</filename> file.
+        </para>
+            <programlisting format="linespecific">
+jar uvf openjpa-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml
+rm META-INF/ra.xml META-IN/weblogic-ra.xml
+rmdir META-INF
+</programlisting>
+            <para>
+        Now you can start WebLogic and WebLogic should
+        deploy OpenJPA for you.  If you have installed OpenJPA correctly, 
+        at this point, one should be able to see OpenJPA bound to the 
+        JNDI location which you specified earlier.
+        </para>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_enterprise_xa">
+        <title>XA Transactions</title>
+        <indexterm zone="ref_guide_enterprise_xa">
+          <primary>transactions</primary>
+          <secondary>XA</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>XA transactions</primary>
+          <see>transactions</see>
+        </indexterm>
+        <para>
+    The X/Open Distributed Transaction Processing (X/Open DTP)
+    model, designed by <ulink url="http://www.xopen.org">Open Group</ulink>
+    (a vendor consortium), defines a standard communication architecture
+    that provides the following:
+    </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+        Concurrent execution of applications on shared resources.
+        </para>
+          </listitem>
+          <listitem>
+            <para>
+        Coordination of transactions across applications.
+        </para>
+          </listitem>
+          <listitem>
+            <para>
+        Components, interfaces, and protocols that define the 
+        architecture and provide portability of applications.
+        </para>
+          </listitem>
+          <listitem>
+            <para>Atomicity of transaction systems.</para>
+          </listitem>
+          <listitem>
+            <para>
+        Single-thread control and sequential function-calling.
+        </para>
+          </listitem>
+        </itemizedlist>
+        <para>
+    The X/Open DTP XA standard defines the application programming
+    interfaces that a resource manager uses to communicate
+    with a transaction manager. The XA interfaces enable resource
+    managers to join transactions, to perform two-phase commit,
+    and to recover in-doubt transactions following a failure.
+    </para>
+        <section id="ref_guide_enterprise_xa_req">
+          <title>Using OpenJPA with XA Transactions</title>
+          <para>
+      OpenJPA supports XA-compliant transactions when used in a properly
+      configured managed environment. The following components are 
+      required:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para>
+          A managed environment that provides an XA compliant 
+          transaction manager. Examples of this are application 
+          servers such as JBoss and WebLogic.
+          </para>
+            </listitem>
+            <listitem>
+              <para>
+          Instances of a <classname>javax.sql.XADataSource</classname>
+          for each of the <classname>DataSource</classname>s that 
+          OpenJPA will use.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      Given these components, setting up OpenJPA to participate in 
+      distributed transactions is a simple two-step process:
+      </para>
+          <orderedlist>
+            <listitem>
+              <para>
+          Point OpenJPA at an enlisted 
+          <classname>XADataSource</classname>, and configure a 
+          second non-enlisted data source.
+          See <xref linkend="ref_guide_dbsetup_thirdparty_enlist"/>.
+          </para>
+            </listitem>
+          </orderedlist>
+        </section>
+      </section>
+    </chapter>

Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,419 @@
+
+    <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>

Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,28 @@
+
+    <chapter id="ref_guide_intro">
+      <title>Introduction</title>
+      <para>
+  OpenJPA <phrase>JPA</phrase> is a JDBC-based implementation of the JPA 
+  standard.  This document is a reference for the 
+  configuration and use of OpenJPA <phrase>JPA</phrase>. 
+  </para>
+      <section id="ref_guide_intro_audience">
+        <title>Intended Audience</title>
+        <para>
+    This document is intended for OpenJPA <phrase>JPA</phrase> developers.  It 
+    assumes strong knowledge of Java, familiarity with the eXtensible 
+    Markup Language (XML), and an understanding of JPA.
+    If you are not familiar with JPA, please read the
+    <link linkend="jpa_overview_intro">JPA Overview</link> 
+    before proceeding.  We also strongly recommend taking OpenJPA's hands-on 
+    <link linkend="tutorials">tutorials</link> to get comfortable 
+    with OpenJPA basics.
+    </para>
+        <para>
+    Certain sections of this guide cover advanced topics such as
+    custom object-relational mapping, enterprise integration, and using
+    OpenJPA with third-party tools.  These sections assume prior experience 
+    with the relevant subject.
+    </para>
+      </section>
+    </chapter>

Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,439 @@
+
+    <chapter id="ref_guide_logging">
+      <title>Logging</title>
+      <indexterm zone="ref_guide_logging">
+        <primary>logging</primary>
+      </indexterm>
+      <indexterm zone="ref_guide_logging">
+        <primary>Log</primary>
+      </indexterm>
+      <para>
+  Logging is an important means of gaining insight into your application's
+  runtime behavior.  OpenJPA
+  provides a flexible logging system that integrates with many
+  existing runtime systems, such as application servers and servlet
+  runners.
+  </para>
+      <para>
+  There are four built-in logging plugins: a 
+  <link linkend="ref_guide_logging_openjpa">default logging framework</link>
+  that covers most needs, a <link linkend="ref_guide_logging_log4j">
+  Log4J</link> delegate, an <link linkend="ref_guide_logging_commons">
+  Apache Commons Logging</link> delegate, and a 
+  <link linkend="ref_guide_logging_noop">no-op</link> implementation for
+  disabling logging.
+  </para>
+      <warning>
+        <para>
+    Logging can have a negative impact on performance. Disable
+    verbose logging (such as logging of SQL statements) before
+    running any performance tests. It is advisable to limit or
+    disable logging for a production system. You can
+    disable logging altogether by setting
+    the <literal>openjpa.Log</literal> property
+    to <literal>none</literal>.
+    </para>
+      </warning>
+      <section id="ref_guide_logging_channels">
+        <title>Logging Channels</title>
+        <indexterm zone="ref_guide_logging_channels">
+          <primary>logging</primary>
+          <secondary>channels</secondary>
+        </indexterm>
+        <para>
+    Logging is done over a number of <emphasis>logging channels</emphasis>,
+    each of which has a <emphasis>logging level</emphasis> which controls
+    the verbosity of log messages recorded for the channel.  OpenJPA uses
+    the following logging channels:
+    </para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>openjpa.Tool</literal>: Messages issued by the OpenJPA
+        command line and Ant tools.  Most messages
+        are basic statements detailing which classes or files the 
+        tools are running on.  Detailed output is only available via
+        the logging category the tool belongs to, such as 
+        <literal>openjpa.Enhance</literal> for the enhancer
+        (see <xref linkend="ref_guide_pc_enhance"/>) or
+        <literal>openjpa.MetaData</literal> for the mapping tool
+        (see <xref linkend="ref_guide_mapping_mappingtool"/>).
+        This logging category is provided so that you can
+        get a general idea of what a tool is doing without having to
+        manipulate logging settings that might also affect runtime
+        behavior.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>configuration</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Configuration</literal>: Messages issued
+        by the configuration framework.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>enhancement</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Enhance</literal>: Messages pertaining to
+        enhancement and runtime class generation.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>metadata</primary><secondary>log messages</secondary></indexterm><literal>openjpa.MetaData</literal>: Details about the generation 
+        of metadata and object-relational mappings.
+        </para>
+          </listitem>
+          <listitem>
+            <para><literal>openjpa.Runtime</literal>: General OpenJPA runtime messages.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Query</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Query</literal>: Messages about queries.
+        Query strings and any parameter values, if applicable, will be 
+        logged to the <literal>TRACE</literal> level at execution
+        time. Information about possible performance concerns
+        will be logged to the <literal>INFO</literal> level.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>remote</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Remote</literal>: Remote connection and execution
+        messages.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>caching</primary><secondary>log messages</secondary></indexterm><literal>openjpa.DataCache</literal>: Messages from the L2 data 
+        cache plugins.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>JDBC</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.JDBC</literal>: JDBC connection information.
+        General JDBC information will be logged to the <literal>TRACE
+        </literal> level.  Information about possible performance 
+        concerns will be logged to the <literal>INFO</literal> level.
+        </para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>SQL</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.SQL</literal>: This is the most common 
+        logging channel to use.  Detailed information about the 
+        execution of SQL statements will be sent to the 
+        <literal>TRACE</literal> level.  It is useful to enable this 
+        channel if you are curious about the exact SQL that OpenJPA 
+        issues to the datastore.
+        </para>
+            <para>
+        When using the built-in OpenJPA logging facilities, you can 
+        enable SQL logging by adding <literal>SQL=TRACE</literal> to
+        your <literal>openjpa.Log</literal> property.
+        </para>
+            <para>
+        OpenJPA can optionally reformat the logged SQL to
+        make it easier to read. To enable pretty-printing,
+        add <literal>PrettyPrint=true</literal> to the
+        <link linkend="openjpa.ConnectionFactoryProperties"><literal>
+        openjpa.ConnectionFactoryProperties</literal></link>
+        property. You can control how many columns wide the
+        pretty-printed SQL will be with the 
+        <literal>PrettyPrintLineLength</literal> property. The default 
+        line length is 60 columns.</para>
+            <para>
+        While pretty printing makes things easier to read, it can make 
+        output harder to process with tools like grep.
+        </para>
+            <para>
+        Pretty-printing properties configuration might look like so:
+        </para>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="SQL=TRACE"/&gt;
+&lt;property name="openjpa.ConnectionFactoryProperties" 
+    value="MaxActive=100, PrettyPrint=true, PrettyPrintLineLength=72"/&gt;
+</programlisting>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>schema</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.Schema</literal>: Details about operations 
+        on the database schema.
+        </para>
+          </listitem>
+        </itemizedlist>
+      </section>
+      <section id="ref_guide_logging_openjpa">
+        <title>OpenJPA Logging</title>
+        <indexterm zone="ref_guide_logging_openjpa">
+          <primary>logging</primary>
+          <secondary>default</secondary>
+        </indexterm>
+        <para>
+    By default, OpenJPA uses a basic logging framework with the following
+    output format:
+    </para>
+        <para><literal>millis</literal><literal>level</literal>  [<literal>thread name</literal>] <literal>channel</literal> - <literal>message</literal></para>
+        <para>
+    For example, when loading an application that uses OpenJPA, a message 
+    like the following will be sent to the <literal>openjpa.Runtime</literal>
+    channel:
+    </para>
+        <programlisting format="linespecific">
+2107  INFO   [main] openjpa.Runtime - Starting OpenJPA 4.0.0
+</programlisting>
+        <para>
+    The default logging system accepts the following parameters:
+    </para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>File</literal>: The name of the file to log to, or
+        <literal>stdout</literal> or <literal>stderr</literal> to send
+        messages to standard out and standard error, respectively.
+        By default, OpenJPA sends log messages to standard error.
+        </para>
+          </listitem>
+          <listitem>
+            <para><literal>DefaultLevel</literal>: The default logging level of
+        unconfigured channels.  Recognized values are <literal>
+        TRACE, DEBUG, INFO, WARN,</literal> and <literal>ERROR
+        </literal>.  Defaults to <literal>INFO</literal>.
+        </para>
+          </listitem>
+          <listitem>
+            <para><literal>DiagnosticContext</literal>: A string that will 
+        be prepended to all log messages.
+        </para>
+          </listitem>
+          <listitem>
+            <para><literal>&lt;channel&gt;</literal>: Using the last token of
+        the <link linkend="ref_guide_logging_channels">logging channel 
+        </link> name, you can configure the log level to
+        use for that channel.  See the examples below.
+        </para>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_logging_openjpa_std_ex">
+          <title>Standard OpenJPA Log Configuration</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_logging_openjpa_sql_ex">
+          <title>Standard OpenJPA Log Configuration + All SQL Statements</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO, SQL=TRACE"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_logging_openjpa_file">
+          <title>Logging to a File</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_logging_noop">
+        <title>Disabling Logging</title>
+        <indexterm zone="ref_guide_logging_noop">
+          <primary>logging</primary>
+          <secondary>disabling</secondary>
+        </indexterm>
+        <para>
+    Disabling logging can be useful to analyze performance without
+    any I/O overhead or to reduce verbosity at the console. To do
+    this, set the <literal>openjpa.Log</literal> property
+    to <literal>none</literal>.
+    </para>
+        <para>
+    Disabling logging permanently, however, will cause all warnings
+    to be consumed.  We recommend using one of the
+    more sophisticated mechanisms described in this chapter.
+    </para>
+      </section>
+      <section id="ref_guide_logging_log4j">
+        <title>Log4J</title>
+        <indexterm zone="ref_guide_logging_log4j">
+          <primary>logging</primary>
+          <secondary>Log4j</secondary>
+        </indexterm>
+        <para>
+    When <literal>openjpa.Log</literal> is set
+    to <literal>log4j</literal>, OpenJPA will delegate to Log4J for logging.
+    In a standalone application, Log4J logging levels are
+    controlled by a resource named <filename>log4j.properties</filename>, 
+    which should be available as a top-level resource (either at the top 
+    level of a jar file, or in the root of one of
+    the <literal>CLASSPATH</literal> directories). When deploying to
+    a web or EJB application server, Log4J configuration is often
+    performed in a <filename>log4j.xml</filename> file instead of a
+    properties file. For further details on configuring Log4J,
+    please see the 
+    <ulink url="http://jakarta.apache.org/log4j/docs/manual.html">Log4J
+    Manual</ulink>. We present an example 
+    <filename>log4j.properties</filename> file below.
+    </para>
+        <example id="ref_guide_logging_log4j_ex">
+          <title>Standard Log4J Logging</title>
+          <programlisting format="linespecific">
+log4j.rootCategory=WARN, console
+log4j.category.openjpa.Tool=INFO
+log4j.category.openjpa.Runtime=INFO
+log4j.category.openjpa.Remote=WARN
+log4j.category.openjpa.DataCache=WARN
+log4j.category.openjpa.MetaData=WARN
+log4j.category.openjpa.Enhance=WARN
+log4j.category.openjpa.Query=WARN
+log4j.category.openjpa.jdbc.SQL=WARN
+log4j.category.openjpa.jdbc.JDBC=WARN
+log4j.category.openjpa.jdbc.Schema=WARN
+
+log4j.appender.console=org.apache.log4j.ConsoleAppender
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_logging_commons">
+        <title>Apache Commons Logging</title>
+        <indexterm zone="ref_guide_logging_commons">
+          <primary>logging</primary>
+          <secondary>Apache Commons</secondary>
+        </indexterm>
+        <para>
+    Set the <literal>openjpa.Log</literal> property to <literal>commons
+    </literal> to use the
+    <ulink url="http://jakarta.apache.org/commons/logging.html">
+    Apache Jakarta Commons Logging</ulink> thin library for issuing
+    log messages. The Commons Logging libraries act as a wrapper
+    around a number of popular logging APIs, including the
+    <ulink url="http://jakarta.apache.org/log4j/docs/index.html">
+    Jakarta Log4J</ulink> project, and the native
+    <ulink url="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
+    java.util.logging</ulink> package in JDK 1.4.  If neither of these
+    libraries are available, then logging will fall back to using simple 
+    console logging.
+    </para>
+        <para>
+    When using the Commons Logging framework in conjunction with
+    Log4J, configuration will be the same as was discussed in the
+    Log4J section above.
+    </para>
+        <section id="ref_guide_logging_jdk14">
+          <title>JDK 1.4 java.util.logging</title>
+          <indexterm zone="ref_guide_logging_jdk14">
+            <primary>logging</primary>
+            <secondary>JDK 1.4</secondary>
+          </indexterm>
+          <para>
+      When using JDK 1.4 or higher in conjunction with OpenJPA's
+      Commons Logging support, logging will proceed through Java's
+      built-in logging provided by the
+      <ulink url="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
+      java.util.logging</ulink> package. For details on
+      configuring the built-in logging system, please see the
+      <ulink url="http://java.sun.com/j2se/1.4/docs/guide/util/logging/overview.html">
+      Java Logging Overview</ulink>.
+      </para>
+          <para>
+      By default, JDK 1.4's logging package looks in
+      the <filename> JAVA_HOME/lib/logging.properties</filename>
+      file for logging configuration. This can be overridden with
+      the <literal> java.util.logging.config.file</literal> system
+      property. For example:
+      </para>
+          <programlisting format="linespecific">
+java -Djava.util.logging.config.file=mylogging.properties com.company.MyClass
+</programlisting>
+          <example id="ref_guide_logging_jdk14_propfile">
+            <title>JDK 1.4 Log Properties</title>
+            <programlisting format="linespecific">
+# specify the handlers to create in the root logger
+# (all loggers are children of the root logger)
+# the following creates two handlers
+handlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandler
+    
+# set the default logging level for the root logger
+.level=ALL
+    
+# set the default logging level for new ConsoleHandler instances
+java.util.logging.ConsoleHandler.level=INFO
+
+# set the default logging level for new FileHandler instances
+java.util.logging.FileHandler.level=ALL
+
+# set the default formatter for new ConsoleHandler instances
+java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter
+
+# set the default logging level for all OpenJPA logs
+openjpa.Tool.level=INFO
+openjpa.Runtime.level=INFO
+openjpa.Remote.level=INFO
+openjpa.DataCache.level=INFO
+openjpa.MetaData.level=INFO
+openjpa.Enhance.level=INFO
+openjpa.Query.level=INFO
+openjpa.jdbc.SQL.level=INFO
+openjpa.jdbc.JDBC.level=INFO
+openjpa.jdbc.Schema.level=INFO
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_logging_custom">
+        <title>Custom Log</title>
+        <indexterm zone="ref_guide_logging_custom">
+          <primary>logging</primary>
+          <secondary>custom</secondary>
+        </indexterm>
+        <para>
+    If none of available logging systems meet your needs, you can configure
+    the logging system with a custom logger.  You might use
+    custom logging to integrate with a proprietary logging framework used 
+    by some applications servers, or for logging to a graphical component 
+    for GUI applications.
+    </para>
+        <para>
+    A custom logging framework must include an implementation of the
+    <ulink url="../apidocs/org/apache/openjpa/lib/log/LogFactory.html"><classname>org.apache.openjpa.lib.log.LogFactory</classname></ulink> interface.
+    We present a custom <classname>LogFactory</classname> below.
+    </para>
+        <example id="ref_guide_logging_custom_ex">
+          <title>Custom Logging Class</title>
+          <programlisting format="linespecific">
+package com.xyz;
+
+import org.apache.openjpa.lib.log.*;
+
+public class CustomLogFactory
+    implements LogFactory
+{   
+    private String _prefix = "CUSTOM LOG";
+
+    public void setPrefix (String prefix)
+    {
+        _prefix = prefix;
+    }
+ 
+    public Log getLog (String channel)
+    {
+        // Return a simple extension of AbstractLog that will log
+        // everything to the System.err stream. Note that this is 
+        // roughly equivalent to OpenJPA's default logging behavior.
+        return new AbstractLog ()
+        {
+            protected boolean isEnabled (short logLevel)
+            {
+                // log all levels
+                return true;
+            }
+
+            protected void log (short type, String message, Throwable t)
+            {
+                // just send everything to System.err
+                System.err.println (_prefix + ": " + type + ": "
+                    + message + ": " + t);
+            }
+        };
+    }
+}</programlisting>
+        </example>
+        <para>
+    To make OpenJPA use your custom log factory, set the 
+    <link linkend="openjpa.Log"><literal>openjpa.Log</literal></link> 
+    configuration property to your factory's full class name.  Because
+    this property is a plugin property (see 
+    <xref linkend="ref_guide_conf_plugins"/>), you can also pass parameters
+    to your factory.  For example, to use the example factory above and
+    set its prefix to "LOG MSG", you would set the 
+    <literal>openjpa.Log</literal> property to the following string:
+    </para>
+        <programlisting format="linespecific">
+com.xyz.CustomLogFactory(Prefix="LOG MSG")
+</programlisting>
+      </section>
+    </chapter>



Mime
View raw message