You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [16/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml Thu Aug 24 13:41:12 2006
@@ -1,224 +1,156 @@
-
- <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.
+<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>
+ <title>
+ Standalone Deployment
+ </title>
+ <indexterm zone="ref_guide_deploy_factory_standalone">
+ <primary>
+ deployment
+ </primary>
+ <secondary>
+ standalone
+ </secondary>
+ <seealso>
+ Persistence
+ </seealso>
</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>
+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"></xref>. 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>
+ <!-- ### -->
<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>
+TBD
+ </para>
</section>
- </section>
- <section id="ref_guide_enterprise_xa">
- <title>XA Transactions</title>
+ </section>
+ <section id="ref_guide_enterprise_xa">
+ <title>
+ XA Transactions
+ </title>
<indexterm zone="ref_guide_enterprise_xa">
- <primary>transactions</primary>
- <secondary>XA</secondary>
+ <primary>
+ transactions
+ </primary>
+ <secondary>
+ XA
+ </secondary>
</indexterm>
<indexterm>
- <primary>XA transactions</primary>
- <see>transactions</see>
+ <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.
+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>
- </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>
+ <itemizedlist>
+ <listitem>
+ <para>
+Concurrent execution of applications on shared resources.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Coordination of transactions across applications.
+ </para>
+ </listitem>
<listitem>
- <para>
- A managed environment that provides an XA compliant
- transaction manager. Examples of this are application
- servers such as JBoss and WebLogic.
- </para>
+ <para>
+Components, interfaces, and protocols that define the architecture and provide
+portability of applications.
+ </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>
+ <para>
+Atomicity of transaction systems.
+ </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>
+ <para>
+Single-thread control and sequential function-calling.
+ </para>
</listitem>
- </orderedlist>
+ </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"></xref>.
+ </para>
+ </listitem>
+ </orderedlist>
</section>
- </section>
- </chapter>
+ </section>
+</chapter>
Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml Thu Aug 24 13:41:12 2006
@@ -1,97 +1,99 @@
-
- <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>
+<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>
+ <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>
+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>
+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>
+ <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>
- <link linkend="ref_guide_integration_revmappingtool">Reverse
- Mapping Tool Task</link>
+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>
- </listitem>
- <listitem>
<para>
- <link linkend="ref_guide_integration_schematool">Schema Tool
- Task</link>
+Following is an example of how to use the nested <literal>config</literal> tag
+in a <filename>build.xml</filename> file:
</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 <config> Ant Tag</title>
- <programlisting format="linespecific">
+ <example id="ref_guide_integration_conf_config">
+ <title>
+ Using the <config> Ant Tag
+ </title>
+<programlisting>
<mappingtool>
<fileset dir="${basedir}">
<include name="**/model/*.java" />
@@ -101,18 +103,19 @@
connectionDriverName="oracle.jdbc.driver.OracleDriver" />
</mappingtool>
</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 <config>
- Tag</title>
- <programlisting format="linespecific">
+ </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 <config>
+ Tag
+ </title>
+<programlisting>
<mappingtool>
<fileset dir="${basedir}">
<include name="**/model/*.java"/>
@@ -120,11 +123,13 @@
<config properties="openjpa-dev.properties"/>
</mappingtool>
</programlisting>
- </example>
- <example id="ref_guide_integration_propsfile">
- <title>Using the PropertiesFile Attribute of the <config>
- Tag</title>
- <programlisting format="linespecific">
+ </example>
+ <example id="ref_guide_integration_propsfile">
+ <title>
+ Using the PropertiesFile Attribute of the <config>
+ Tag
+ </title>
+<programlisting>
<mappingtool>
<fileset dir="${basedir}">
<include name="**/model/*.java"/>
@@ -132,25 +137,25 @@
<config propertiesFile="../conf/openjpa-dev.properties"/>
</mappingtool>
</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 <classpath> Ant Tag</title>
- <programlisting format="linespecific">
+ </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 <classpath> Ant Tag
+ </title>
+<programlisting>
<openjpac>
<fileset dir="${basedir}/source">
<include name="**/model/*.java" />
@@ -162,60 +167,73 @@
</classpath>
</openjpac>
</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 <codeformat> Ant Tag</title>
- <programlisting format="linespecific">
+ </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"></xref> for a list of code
+formatting attributes.
+ </para>
+ <example id="ref_guide_integration_conf_codeformat">
+ <title>
+ Using the <codeformat> Ant Tag
+ </title>
+<programlisting>
<reversemappingtool package="com.xyz.jdo" directory="${basedir}/src">
<codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/>
</reversemappingtool>
</programlisting>
- </example>
+ </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">
+ <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>
<target name="enhance">
<!-- define the openjpac task; this can be done at the top of the -->
<!-- build.xml file, so it will be available for all targets -->
<taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask"/>
- <!-- invoke enhancer on all .jdo files below the current directory -->
+ <!-- invoke enhancer on all .java files below the model directory -->
<openjpac>
<fileset dir=".">
<include name="**/model/*.java" />
@@ -223,41 +241,52 @@
</openjpac>
</target>
</programlisting>
- </example>
+ </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">
+ <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>
<target name="appids">
<!-- define the appidtool task; this can be done at the top of -->
<!-- the build.xml file, so it will be available for all targets -->
@@ -272,45 +301,53 @@
</appidtool>
</target>
</programlisting>
- </example>
+ </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">
+ <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>
<target name="refresh">
<!-- define the mappingtool task; this can be done at the top of -->
<!-- the build.xml file, so it will be available for all targets -->
@@ -325,34 +362,45 @@
</mappingtool>
</target>
</programlisting>
- </example>
+ </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">
+ <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>
<target name="reversemap">
<!-- define the reversemappingtool task; this can be done at the top of -->
<!-- the build.xml file, so it will be available for all targets -->
@@ -366,33 +414,44 @@
</reversemappingtool>
</target>
</programlisting>
- </example>
+ </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">
+ <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>
<target name="schema">
<!-- define the schematool task; this can be done at the top of -->
<!-- the build.xml file, so it will be available for all targets -->
@@ -407,13 +466,17 @@
</schematool>
</target>
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="ref_guide_integration_maven">
- <title>Maven</title>
+ </section>
+ <section id="ref_guide_integration_maven">
+ <title>
+ Maven
+ </title>
<indexterm zone="ref_guide_integration_maven">
- <primary>Maven</primary>
+ <primary>
+ Maven
+ </primary>
</indexterm>
- </section>
- </chapter>
+ </section>
+</chapter>
Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml Thu Aug 24 13:41:12 2006
@@ -1,28 +1,30 @@
-
- <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.
+<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>
- 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>
+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>
Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml Thu Aug 24 13:41:12 2006
@@ -1,267 +1,371 @@
-
- <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>
+<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>
+ <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:
+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>
- <programlisting format="linespecific">
+ <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"></xref>) or <literal>
+openjpa.MetaData</literal> for the mapping tool (see
+<xref linkend="ref_guide_mapping_mappingtool"></xref> ). 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>
<property name="openjpa.Log" value="SQL=TRACE"/>
<property name="openjpa.ConnectionFactoryProperties"
value="MaxActive=100, PrettyPrint=true, PrettyPrintLineLength=72"/>
</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>
+ </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>
+ </section>
+ <section id="ref_guide_logging_openjpa">
+ <title>
+ OpenJPA Logging
+ </title>
<indexterm zone="ref_guide_logging_openjpa">
- <primary>logging</primary>
- <secondary>default</secondary>
+ <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>
+By default, OpenJPA uses a basic logging framework with the following output
+format:
+ </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">
+<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>
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><channel></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.
+The default logging system accepts the following parameters:
</para>
- </listitem>
+ <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><channel></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">
+ <title>
+ Standard OpenJPA Log Configuration
+ </title>
+<programlisting>
<property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/>
</programlisting>
</example>
<example id="ref_guide_logging_openjpa_sql_ex">
- <title>Standard OpenJPA Log Configuration + All SQL Statements</title>
- <programlisting format="linespecific">
+ <title>
+ Standard OpenJPA Log Configuration + All SQL Statements
+ </title>
+<programlisting>
<property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO, SQL=TRACE"/>
</programlisting>
</example>
<example id="ref_guide_logging_openjpa_file">
- <title>Logging to a File</title>
- <programlisting format="linespecific">
+ <title>
+ Logging to a File
+ </title>
+<programlisting>
<property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/>
</programlisting>
</example>
- </section>
- <section id="ref_guide_logging_noop">
- <title>Disabling Logging</title>
+ </section>
+ <section id="ref_guide_logging_noop">
+ <title>
+ Disabling Logging
+ </title>
<indexterm zone="ref_guide_logging_noop">
- <primary>logging</primary>
- <secondary>disabling</secondary>
+ <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>
+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>
+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>
+ <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>
+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">
+ <title>
+ Standard Log4J Logging
+ </title>
+<programlisting>
log4j.rootCategory=WARN, console
log4j.category.openjpa.Tool=INFO
log4j.category.openjpa.Runtime=INFO
@@ -277,61 +381,70 @@
log4j.appender.console=org.apache.log4j.ConsoleAppender
</programlisting>
</example>
- </section>
- <section id="ref_guide_logging_commons">
- <title>Apache Commons Logging</title>
+ </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>
+ <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>
+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>
+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">
+ <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>
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">
+ <example id="ref_guide_logging_jdk14_propfile">
+ <title>
+ JDK 1.4 Log Properties
+ </title>
+<programlisting>
# specify the handlers to create in the root logger
# (all loggers are children of the root logger)
# the following creates two handlers
@@ -361,30 +474,38 @@
openjpa.jdbc.JDBC.level=INFO
openjpa.jdbc.Schema.level=INFO
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="ref_guide_logging_custom">
- <title>Custom Log</title>
+ </section>
+ <section id="ref_guide_logging_custom">
+ <title>
+ Custom Log
+ </title>
<indexterm zone="ref_guide_logging_custom">
- <primary>logging</primary>
- <secondary>custom</secondary>
+ <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>
+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>
+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">
+ <title>
+ Custom Logging Class
+ </title>
+<programlisting>
package com.xyz;
import org.apache.openjpa.lib.log.*;
@@ -420,20 +541,20 @@
}
};
}
-}</programlisting>
+}
+</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">
+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"></xref> ), 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>
com.xyz.CustomLogFactory(Prefix="LOG MSG")
</programlisting>
- </section>
- </chapter>
+ </section>
+</chapter>