Apache
/
openjpa
mirror of https://github.com/apache/openjpa.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Formatted our documentation XML files. 

git-svn-id: https://svn.apache.org/repos/asf/incubator/openjpa/trunk@434517 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
A. Abram White 2006-08-24 20:41:12 +00:00
parent 746ebdfdc9
commit fe71475a59
35 changed files with 32453 additions and 25533 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java
View File

@ -83,11 +83,11 @@ public class MetaDataRepository
public static final int VALIDATE_RUNTIME = 8;
protected static final Class[] EMPTY_CLASSES = new Class[0];
protected static final PersistenceAwareClass[] EMPTY_PAWARE_CLASSES =
new PersistenceAwareClass[0];
protected final ClassMetaData[] EMPTY_METAS;
protected final FieldMetaData[] EMPTY_FIELDS;
protected final Order[] EMPTY_ORDERS;
protected static final PersistenceAwareClass[] EMPTY_PAWARE_CLASSES =
new PersistenceAwareClass[0];
private static final Localizer _loc = Localizer.forPackage
(MetaDataRepository.class);
@ -699,19 +699,6 @@ public class MetaDataRepository
public ClassMetaData getCachedMetaData(Class cls) {
return (ClassMetaData) _metas.get(cls);
}
/**
* Gets all the registered persistence-aware classes.
*
* @return empty array if no class has been registered.
*
*/
public PersistenceAwareClass[] getPersistenceAwareClasses() {
if (_pawares.isEmpty())
return EMPTY_PAWARE_CLASSES;
return (PersistenceAwareClass[])_pawares.values().toArray
(new PersistenceAwareClass[_pawares.size()]);
}
/**
* Create a new metadata, populate it with default information, add it to
@ -737,32 +724,13 @@ public class MetaDataRepository
// synchronize on this rather than the map, because all other methods
// that access _metas are synchronized on this
synchronized (this) {
if (_pawares.containsKey(cls))
throw new MetaDataException(_loc.get("pc-and-aware", cls));
_metas.put(cls, meta);
_count++;
}
return meta;
}
/**
* Add the given class as persitence-aware.
*
* @param cls non-null and must not alreaddy be added as persitence-capable.
*/
public PersistenceAwareClass addPersistenceAware(Class cls) {
if (cls == null)
return null;
if (_pawares.containsKey(cls))
return (PersistenceAwareClass)_pawares.get(cls);
if (getCachedMetaData(cls) == null) {
synchronized(this) {
PersistenceAwareClass result = newPersistenceAwareClass(cls);
_pawares.put(cls,result);
return result;
}
}
else
throw new MetaDataException(_loc.get("pc-and-aware", cls));
}
/**
* Create a new class metadata instance.
@ -770,10 +738,6 @@ public class MetaDataRepository
protected ClassMetaData newClassMetaData(Class type) {
return new ClassMetaData(type, this);
}
protected PersistenceAwareClass newPersistenceAwareClass(Class type) {
return new PersistenceAwareClass(type, this);
}
/**
* Create a new array of the proper class metadata subclass.
@ -887,25 +851,6 @@ public class MetaDataRepository
return false;
}
/**
* Remove a persitence-aware class from this receiver.
*
* @param cls a class possibly added earlier as persitence-aware.
*
* @return true if removed, false if not contained in this receiver
*/
public synchronized boolean removePersistenceAware(Class cls) {
return _pawares.remove(cls) != null;
}
/**
* Removes all persitence-aware classes from this receiver.
*
*/
public synchronized void removeAllPersistenceAware() {
_pawares.clear();
}
/**
* Return the least-derived class metadata for the given application
* identity object.
@ -1044,6 +989,57 @@ public class MetaDataRepository
return (ClassMetaData[]) mapped.toArray(newClassMetaDataArray
(mapped.size()));
}
/**
* Gets the persistence-aware class corresponding to the given class. Can
* be null, if the given class is not registered as persistence-aware with
* this receiver.
*/
public PersistenceAwareClass getPersistenceAware(Class cls) {
return (PersistenceAwareClass)_pawares.get(cls);
}
/**
* Gets all the registered persistence-aware classes.
*
* @return empty array if no class has been registered
*/
public PersistenceAwareClass[] getPersistenceAwares() {
synchronized (_pawares) {
if (_pawares.isEmpty())
return EMPTY_PAWARE_CLASSES;
return (PersistenceAwareClass[])_pawares.values().toArray
(new PersistenceAwareClass[_pawares.size()]);
}
}
/**
* Add the given class as persitence-aware.
*
* @param cls non-null and must not alreaddy be added as persitence-capable
*/
public PersistenceAwareClass addPersistenceAware(Class cls) {
if (cls == null)
return null;
synchronized(this) {
if (_pawares.containsKey(cls))
return (PersistenceAwareClass)_pawares.get(cls);
if (getCachedMetaData(cls) != null)
throw new MetaDataException(_loc.get("pc-and-aware", cls));
PersistenceAwareClass result = new PersistenceAwareClass(cls, this);
_pawares.put(cls, result);
return result;
}
}
/**
* Remove a persitence-aware class from this receiver.
*
* @return true if removed, false if not contained in this receiver
*/
public boolean removePersistenceAware(Class cls) {
return _pawares.remove(cls) != null;
}
/**
* Clear the cache of parsed metadata. This method also clears the
@ -1062,6 +1058,7 @@ public class MetaDataRepository
_registered.clear();
_factory.clear();
_aliases.clear();
_pawares.clear();
}
/**
@ -1560,18 +1557,6 @@ public class MetaDataRepository
(new SequenceMetaData[_seqs.size()]);
}
/**
* Gets the persistence-aware class corresponding to the given class. Can
* be null, if the given class is not registered as persistence-aware with
* this receiver.
*
* @param cls a Java class possibly registered as persistence-aware earlier
* with this receiver.
*/
public synchronized PersistenceAwareClass getPersistenceAware(Class cls) {
return (PersistenceAwareClass)_pawares.get(cls);
}
/**
* Return the cached a sequence metadata for the given name.
*/

87
openjpa-kernel/src/main/java/org/apache/openjpa/meta/PersistenceAwareClass.java
View File

@ -5,9 +5,13 @@ import java.io.File;
import org.apache.openjpa.lib.meta.SourceTracker;
import org.apache.openjpa.lib.xml.Commentable;
/**
* Metadata about a persistence-aware type.
*
* @author Pinaki Poddar
*/
public class PersistenceAwareClass
implements Comparable, SourceTracker,Commentable,MetaDataContext,
MetaDataModes {
implements Comparable, SourceTracker, Commentable, MetaDataContext {
private final MetaDataRepository _repos;
private final Class _class;
@ -16,25 +20,42 @@ public class PersistenceAwareClass
private int _srcType = SRC_OTHER;
private String[] _comments = null;
private int _listIndex = -1;
private int _srcMode = MODE_META | MODE_MAPPING;
public PersistenceAwareClass(Class cls, MetaDataRepository repos) {
protected PersistenceAwareClass(Class cls, MetaDataRepository repos) {
_repos = repos;
_class = cls;
}
public String getName() {
return _class.getName();
}
/**
* Owning repository.
*/
public MetaDataRepository getRepository() {
return _repos;
}
/**
* Persistence-aware type.
*/
public Class getDescribedType() {
return _class;
}
/**
* The index in which this class was listed in the metadata. Defaults to
* <code>-1</code> if this class was not listed in the metadata.
*/
public int getListingIndex() {
return _listIndex;
}
/**
* The index in which this field was listed in the metadata. Defaults to
* <code>-1</code> if this class was not listed in the metadata.
*/
public void setListingIndex(int index) {
_listIndex = index;
}
public File getSourceFile() {
return _srcFile;
}
@ -56,52 +77,6 @@ public class PersistenceAwareClass
return _class.getName();
}
/**
* The source mode this metadata has been loaded under.
*/
public int getSourceMode() {
return _srcMode;
}
/**
* The source mode this metadata has been loaded under.
*/
public void setSourceMode(int mode) {
_srcMode = mode;
}
/**
* The source mode this metadata has been loaded under.
*/
public void setSourceMode(int mode, boolean on) {
if (mode == MODE_NONE)
_srcMode = mode;
else if (on)
_srcMode |= mode;
else
_srcMode &= ~mode;
}
/**
* The index in which this class was listed in the metadata. Defaults to
* <code>-1</code> if this class was not listed in the metadata.
*/
public int getListingIndex() {
return _listIndex;
}
/**
* The index in which this field was listed in the metadata. Defaults to
* <code>-1</code> if this class was not listed in the metadata.
*/
public void setListingIndex(int index) {
_listIndex = index;
}
///////////////
// Commentable
///////////////
public String[] getComments() {
return (_comments == null) ? ClassMetaData.EMPTY_COMMENTS : _comments;
}
@ -113,9 +88,9 @@ public class PersistenceAwareClass
public int compareTo(Object other) {
if (other == this)
return 0;
if (other instanceof PersistenceAwareClass)
if (!(other instanceof PersistenceAwareClass))
return 1;
return _class.getName().compareTo(((ClassMetaData) other).
return _class.getName().compareTo(((PersistenceAwareClass) other).
getDescribedType().getName());
}

5
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/XMLMetaDataParser.java
View File

@ -338,9 +338,8 @@ public abstract class XMLMetaDataParser extends DefaultHandler
_log.info(_loc.get("parser-schema-bug"));
schemaSource = null;
}
boolean validating = _validating &&
(getDocType() != null || schemaSource != null);
boolean validating = _validating && (getDocType() != null
|| schemaSource != null);
// parse the metadata with a SAX parser
try {

373
openjpa-project/src/doc/manual/jpa_overview_arch.xml
View File

@ -1,100 +1,181 @@
<chapter id="jpa_overview_arch">
<title>EJB Persistence Architecture</title>
<indexterm zone="jpa_overview_arch">
<primary>EJB</primary>
<secondary>architecture</secondary>
</indexterm>
<para>
The diagram below illustrates the relationships between the primary
components of the EJB architecture.
</para>
<mediaobject>
<chapter id="jpa_overview_arch">
<title>
Java Persistence API Architecture
</title>
<indexterm zone="jpa_overview_arch">
<primary>
JPA
</primary>
<secondary>
architecture
</secondary>
</indexterm>
<para>
The diagram below illustrates the relationships between the primary components
of the JPA architecture.
</para>
<mediaobject>
<imageobject>
<!-- PNG image data 400 x 256 (see README) -->
<imagedata fileref="img/jpa-arch.png" width="267px"/>
<!-- PNG image data 400 x 256 (see README) -->
<imagedata fileref="img/jpa-arch.png" width="267px">
</imagedata>
</imageobject>
<textobject>
<phrase>EJB architecture</phrase>
<phrase>
JPA architecture
</phrase>
</textobject>
</mediaobject>
<note>
</mediaobject>
<note>
<para>
A number of the depicted interfaces are only required outside of
an EJB3-compliant application server. In an application server,
<classname>EntityManager</classname> instances are typically injected,
rendering the <classname>EntityManagerFactory</classname> unnecessary.
Also, transactions within an application server
are handled using standard application server transaction controls.
Thus, the <classname>EntityTransaction</classname> also goes unused.
A number of the depicted interfaces are only required outside of an
EJB3-compliant application server. In an application server, <classname>
EntityManager</classname> instances are typically injected, rendering the
<classname>EntityManagerFactory</classname> unnecessary. Also, transactions
within an application server are handled using standard application server
transaction controls. Thus, the <classname>EntityTransaction</classname> also
goes unused.
</para>
</note>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
Persistence
</primary>
</indexterm>
<emphasis role="bold"><link linkend="jpa_overview_persistence"><classname>
Persistence</classname></link></emphasis>: The <classname>
javax.persistence.Persistence</classname> class contains static helper methods
to obtain <classname>EntityManagerFactory</classname> instances in a
vendor-neutral fashion.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
EntityManagerFactory
</primary>
</indexterm>
<emphasis role="bold"><link linkend="jpa_overview_emfactory"><classname>
EntityManagerFactory</classname></link></emphasis>: The <classname>
javax.persistence.EntityManagerFactory</classname> class is a factory for
<classname> EntityManager</classname> s.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
EntityManager
</primary>
</indexterm>
<emphasis role="bold"><link linkend="jpa_overview_em"><classname>EntityManager
</classname></link></emphasis>: The <classname>javax.persistence.EntityManager
</classname> is the primary JPA interface used by applications. Each
<classname>EntityManager</classname> manages a set of persistent objects, and
has APIs to insert new objects and delete existing ones. When used outside the
container, there is a one-to-one relationship between an <classname>
EntityManager</classname> and an <classname> EntityTransaction</classname>.
<classname> EntityManager</classname>s also act as factories for <classname>
Query</classname> instances.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
entity
</primary>
</indexterm>
<emphasis role="bold"><link linkend="jpa_overview_pc"><classname>Entity
</classname></link></emphasis>: Entites are persistent objects that represent
datastore records.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
EntityTransaction
</primary>
</indexterm>
<emphasis role="bold"><link linkend="jpa_overview_trans"><classname>
EntityTransaction</classname></link></emphasis>: Each <classname>EntityManager
</classname> has a one-to-one relation with a single <classname>
javax.persistence.EntityTransaction</classname>. <classname>EntityTransaction
</classname>s allow operations on persistent data to be grouped into units of
work that either completely succeed or completely fail, leaving the datastore in
its original state. These all-or-nothing operations are important for
maintaining data integrity.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Query
</primary>
</indexterm>
<indexterm>
<primary>
Java Persistence Query Language
</primary>
<see>
JPQL
</see>
</indexterm>
<indexterm>
<primary>
JPQL
</primary>
</indexterm>
<indexterm>
<primary>
JPA
</primary>
<secondary>
query language
</secondary>
<see>
JPQL
</see>
</indexterm>
<indexterm>
<primary>
Structured Query Language
</primary>
<see>
SQL
</see>
</indexterm>
<indexterm>
<primary>
SQL
</primary>
</indexterm>
<emphasis role="bold"><link linkend="jpa_overview_query"><classname>Query
</classname></link></emphasis>: The <classname>javax.persistence.Query
</classname> interface is implemented by each JPA vendor to find persistent
objects that meet certain criteria. JPA standardizes support for queries using
both the Java Persistence Query Language (JPQL) and the Structured Query
Language (SQL). You obtain <classname>Query</classname> instances from an
<classname>EntityManager</classname>.
</para>
</listitem>
</itemizedlist>
<para>
The example below illustrates how the JPA interfaces interact to execute a JPQL
query and update persistent objects. The example assumes execution outside a
container.
</para>
</note>
<itemizedlist>
<listitem>
<para><indexterm><primary>Persistence</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_persistence"><classname>Persistence</classname></link></emphasis>:
The <classname>javax.persistence.Persistence</classname> class
contains static helper methods to obtain
<classname>EntityManagerFactory</classname> instances in a
vendor-neutral fashion.
</para>
</listitem>
<listitem>
<para><indexterm><primary>EntityManagerFactory</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_emfactory"><classname>EntityManagerFactory</classname></link></emphasis>: The <classname>javax.persistence.EntityManagerFactory
</classname> class is a factory for <classname>
EntityManager</classname>s.
</para>
</listitem>
<listitem>
<para><indexterm><primary>EntityManager</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_em"><classname>EntityManager</classname></link></emphasis>:
The <classname>javax.persistence.EntityManager</classname> is the
primary EJB persistence interface used by applications.
Each <classname>EntityManager</classname> manages a set of
persistent objects, and has APIs to insert new objects and delete
existing ones. When used outside the container, there is a
one-to-one relationship between an
<classname>EntityManager</classname> and an <classname>
EntityTransaction</classname>. <classname>
EntityManager</classname>s also act as factories for
<classname>Query</classname> instances.
</para>
</listitem>
<listitem>
<para><indexterm><primary>entity</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_pc"><classname>Entity</classname></link></emphasis>:
Entites are persistent objects that represent datastore records.
</para>
</listitem>
<listitem>
<para><indexterm><primary>EntityTransaction</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_trans"><classname>EntityTransaction</classname></link></emphasis>:
Each <classname>EntityManager</classname> has a one-to-one
relation with a single
<classname>javax.persistence.EntityTransaction</classname>.
<classname>EntityTransaction</classname>s allow operations on
persistent data to be grouped into units of work that either
completely succeed or completely fail, leaving the datastore
in its original state. These all-or-nothing operations are
important for maintaining data integrity.
</para>
</listitem>
<listitem>
<para><indexterm><primary>Query</primary></indexterm><indexterm><primary>EJB3 Persistence Query Language</primary><see>JPQL</see></indexterm><indexterm><primary>JPQL</primary></indexterm><indexterm><primary>EJB</primary><secondary>query language</secondary><see>JPQL</see></indexterm><indexterm><primary>Structured Query Language</primary><see>SQL</see></indexterm><indexterm><primary>SQL</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_query"><classname>Query</classname></link></emphasis>: The
<classname>javax.persistence.Query</classname> interface is
implemented by each EJB vendor to find persistent objects
that meet certain criteria. EJB standardizes support
for queries using both the EJB Query Language (JPQL) and
the Structured Query Language (SQL). You obtain
<classname>Query</classname> instances from an
<classname>EntityManager</classname>.
</para>
</listitem>
</itemizedlist>
<para>
The example below illustrates how the EJB interfaces interact to
execute an JPQL query and update persistent objects. The example
assumes execution outside a container.
</para>
<example id="jpa_overview_arch_interact_outside">
<title>Interaction of Interfaces Outside Container</title>
<programlisting format="linespecific">
<example id="jpa_overview_arch_interact_outside">
<title>
Interaction of Interfaces Outside Container
</title>
<programlisting>
// get an EntityManagerFactory using the Persistence class; typically
// the factory is cached for easy repeated use
EntityManagerFactory factory = Persistence.createEntityManagerFactory (null);
@ -124,15 +205,17 @@ tx.commit ();
em.close ();
factory.close ();
</programlisting>
</example>
<para>
Within a container, the <classname>EntityManager</classname> will be
injected and transactional handled declaratively. Thus, the in-container
version of the example consists entirely of business logic:
</para>
<example id="jpa_overview_arch_interact_inside">
<title>Interaction of Interfaces Inside Container</title>
<programlisting format="linespecific">
</example>
<para>
Within a container, the <classname>EntityManager</classname> will be injected
and transactional handled declaratively. Thus, the in-container version of the
example consists entirely of business logic:
</para>
<example id="jpa_overview_arch_interact_inside">
<title>
Interaction of Interfaces Inside Container
</title>
<programlisting>
// query for all employees who work in our research division
// and put in over 40 hours a week average - note that the EntityManager em
// is injected using a @Resource annotation
@ -147,50 +230,64 @@ for (Object res : results)
emp.setSalary (emp.getSalary () * 1.1);
}
</programlisting>
</example>
<para>
The remainder of this document explores the EJB interfaces in
detail. We present them in roughly the order that you will use them as you
develop your application.
</para>
<section id="jpa_overview_arch_exceptions">
<title>EJB Exceptions</title>
</example>
<para>
The remainder of this document explores the JPA interfaces in detail. We present
them in roughly the order that you will use them as you develop your
application.
</para>
<section id="jpa_overview_arch_exceptions">
<title>
JPA Exceptions
</title>
<indexterm zone="jpa_overview_arch_exceptions">
<primary>EJB</primary>
<secondary>exceptions</secondary>
<seealso>exceptions</seealso>
<primary>
JPA
</primary>
<secondary>
exceptions
</secondary>
<seealso>
exceptions
</seealso>
</indexterm>
<indexterm>
<primary>exceptions</primary>
<secondary>EJB</secondary>
<primary>
exceptions
</primary>
<secondary>
JPA
</secondary>
</indexterm>
<mediaobject>
<imageobject>
<!-- PNG image data, 427 x 355 (see README) -->
<imagedata fileref="img/jpa-exceptions.png" width="285px"/>
</imageobject>
<textobject>
<phrase>EJB persistence exception architecture</phrase>
</textobject>
<imageobject>
<!-- PNG image data, 427 x 355 (see README) -->
<imagedata fileref="img/jpa-exceptions.png" width="285px">
</imagedata>
</imageobject>
<textobject>
<phrase>
JPA exception architecture
</phrase>
</textobject>
</mediaobject>
<para>
The diagram above depicts the EJB persistence exception architecture.
All exceptions are unchecked. EJB persistence uses
standard exceptions where appropriate, most notably <classname>
IllegalArgumentException</classname>s and <classname>
IllegalStateException</classname>s. The specification also provides
a few EJB-specific exceptions in the <literal>javax.persistence
</literal> package. These exceptions should be self-explanatory. See
the <ulink url="http://java.sun.com/javaee/5/docs/api">Javadoc</ulink> for
additional details on EJB exceptions.
</para>
The diagram above depicts the JPA exception architecture. All
exceptions are unchecked. JPA uses standard exceptions where
appropriate, most notably <classname> IllegalArgumentException</classname>s and
<classname> IllegalStateException</classname> s. The specification also provides
a few JPA-specific exceptions in the <literal>javax.persistence</literal>
package. These exceptions should be self-explanatory. See the
<ulink url="http://java.sun.com/javaee/5/docs/api">Javadoc</ulink> for
additional details on JPA exceptions.
</para>
<note>
<para>
All exceptions thrown by OpenJPA implement
<ulink url="../apidocs/org/apache/openjpa/util/ExceptionInfo.html"><classname>
org.apache.openjpa.util.ExceptionInfo</classname></ulink> to provide you with
additional error information.
</para>
<para>
All exceptions thrown by OpenJPA implement
<ulink url="../apidocs/org/apache/openjpa/util/ExceptionInfo.html"><classname>
org.apache.openjpa.util.ExceptionInfo</classname></ulink> to provide you with
additional error information.
</para>
</note>
</section>
</chapter>
</section>
</chapter>

31
openjpa-project/src/doc/manual/jpa_overview_conclusion.xml
View File

@ -1,18 +1,13 @@
<chapter id="jpa_overview_conclusion">
<title>Conclusion</title>
<para>
This concludes our overview of the EJB persistence specification. The
<link linkend="jpa_tutorials_intro">OpenJPA EJB Tutorials</link>
continue your EJB education with step-by-step instructions for
building simple EJB persistence applications. The
<link linkend="ref_guide_intro">OpenJPA Reference Guide</link> contains
detailed documentation on all aspects of the OpenJPA EJB persistence
implementation and core development tools.
<!-- ### JDO2MIG
Finally,
the <link linkend="gui_intro">Workbench Guide</link> teaches you how to
use the OpenJPA Development Workbench for GUI-driven development.
-->
</para>
</chapter>
<chapter id="jpa_overview_conclusion">
<title>
Conclusion
</title>
<para>
This concludes our overview of the JPA specification. The
<link linkend="jpa_tutorials_intro">OpenJPA Tutorials</link> continue your
JPA education with step-by-step instructions for building simple JPA
applications. The <link linkend="ref_guide_intro">OpenJPA Reference Guide</link>
contains detailed documentation on all aspects of the OpenJPA implementation
and core development tools.
</para>
</chapter>

1353
openjpa-project/src/doc/manual/jpa_overview_em.xml
View File

File diff suppressed because it is too large Load Diff

565
openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
View File

@ -1,248 +1,274 @@
<chapter id="jpa_overview_emfactory">
<title>EntityManagerFactory</title>
<indexterm zone="jpa_overview_emfactory">
<primary>EntityManagerFactory</primary>
</indexterm>
<mediaobject>
<chapter id="jpa_overview_emfactory">
<title>
EntityManagerFactory
</title>
<indexterm zone="jpa_overview_emfactory">
<primary>
EntityManagerFactory
</primary>
</indexterm>
<mediaobject>
<imageobject>
<!-- PNG image data, 418 x 274 (see README) -->
<imagedata fileref="img/entitymanagerfactory.png" width="279px"/>
<!-- PNG image data, 418 x 274 (see README) -->
<imagedata fileref="img/entitymanagerfactory.png" width="279px">
</imagedata>
</imageobject>
</mediaobject>
<para>
The <classname>EntityManagerFactory</classname> creates
<classname>EntityManager</classname> instances for application
use.
</para>
<note>
<para>
OpenJPA extends the standard <classname>EntityManagerFactory</classname>
interface with the
<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html"><classname>OpenJPAEntityManagerFactory</classname></ulink> to provide
additional functionality.
</mediaobject>
<para>
The <classname>EntityManagerFactory</classname> creates <classname>
EntityManager</classname> instances for application use.
</para>
</note>
<section id="jpa_overview_emfactory_obtain">
<title>Obtaining an EntityManagerFactory</title>
<note>
<para>
OpenJPA extends the standard <classname>EntityManagerFactory</classname>
interface with the
<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html">
<classname>OpenJPAEntityManagerFactory</classname></ulink> to provide additional
functionality.
</para>
</note>
<section id="jpa_overview_emfactory_obtain">
<title>
Obtaining an EntityManagerFactory
</title>
<indexterm zone="jpa_overview_emfactory_obtain">
<primary>EntityManagerFactory</primary>
<secondary>construction</secondary>
<primary>
EntityManagerFactory
</primary>
<secondary>
construction
</secondary>
</indexterm>
<indexterm>
<primary>Java Connector Architecture</primary>
<see>JCA</see>
<primary>
Java Connector Architecture
</primary>
<see>
JCA
</see>
</indexterm>
<indexterm>
<primary>JCA</primary>
<primary>
JCA
</primary>
</indexterm>
<para>
Within a container, you will typically use <emphasis>injection
</emphasis> to access an <classname>EntityManagerFactory</classname>.
There are, however, alternative mechanisms for
<classname>EntityManagerFactory</classname> construction.
</para>
Within a container, you will typically use <emphasis>injection</emphasis> to
access an <classname>EntityManagerFactory</classname>. There are, however,
alternative mechanisms for <classname>EntityManagerFactory</classname>
construction.
</para>
<para>
Some vendors may supply public constructors for their
<classname>EntityManagerFactory</classname> implementations, but
we recommend using the Java Connector Architecture (JCA) in a managed
environment, or the <classname>Persistence</classname> class'
<methodname>createEntityManagerFactory</methodname> methods in an
unmanaged environment, as described in
<xref linkend="jpa_overview_persistence"/>. These strategies allow
vendors to pool factories, cutting down on resource utilization.
</para>
<para><indexterm><primary>JNDI</primary></indexterm>
JPA allows you to create and configure an
<classname>EntityManagerFactory</classname>, then store it in a
Java Naming and Directory Interface (JNDI) tree for later retrieval
and use.
</para>
</section>
<section id="jpa_overview_emfactory_em">
<title>Obtaining EntityManagers</title>
Some vendors may supply public constructors for their <classname>
EntityManagerFactory</classname> implementations, but we recommend using the
Java Connector Architecture (JCA) in a managed environment, or the <classname>
Persistence</classname> class' <methodname>createEntityManagerFactory
</methodname> methods in an unmanaged environment, as described in
<xref linkend="jpa_overview_persistence"></xref>. These strategies allow
vendors to pool factories, cutting down on resource utilization.
</para>
<para>
<indexterm>
<primary>
JNDI
</primary>
</indexterm>
JPA allows you to create and configure an <classname>EntityManagerFactory
</classname>, then store it in a Java Naming and Directory Interface (JNDI)
tree for later retrieval and use.
</para>
</section>
<section id="jpa_overview_emfactory_em">
<title>
Obtaining EntityManagers
</title>
<indexterm zone="jpa_overview_emfactory_em">
<primary>EntityManager</primary>
<secondary>obtaining</secondary>
<seealso>EntityManagerFactory</seealso>
<primary>
EntityManager
</primary>
<secondary>
obtaining
</secondary>
<seealso>
EntityManagerFactory
</seealso>
</indexterm>
<indexterm zone="jpa_overview_emfactory_em">
<primary>EntityManagerFactory</primary>
<secondary>obtaining EntityManagers</secondary>
<primary>
EntityManagerFactory
</primary>
<secondary>
obtaining EntityManagers
</secondary>
</indexterm>
<programlisting format="linespecific">
<programlisting>
public EntityManager createEntityManager ();
public EntityManager createEntityManager (Map map);
</programlisting>
<para>
The two <methodname>createEntityManager</methodname> methods above
create a new <classname>EntityManager</classname> each time they are
invoked. The optional <classname>Map</classname> is used to to supply
vendor-specific settings. If you have configured your implementation
for JTA transactions and a JTA transaction is active, the returned
<classname>EntityManager</classname> will be synchronized with that
transaction.
<!--
<classname>EntityManager</classname> with a persistence context type of
<literal>TRANSACTION</literal>. The second version allows you to
specify the persistence context type. We relate the differences
between persistence context types
<link linkend="jpa_overview_emfactory_perscontext">below</link>.
-->
</para>
The two <methodname>createEntityManager</methodname> methods above create a new
<classname>EntityManager</classname> each time they are invoked. The optional
<classname>Map</classname> is used to to supply vendor-specific settings. If you
have configured your implementation for JTA transactions and a JTA transaction
is active, the returned <classname>EntityManager</classname> will be
synchronized with that transaction.
</para>
<note>
<para>
OpenJPA recognizes the following string keys in the map supplied to
<methodname>createEntityManager</methodname>:
</para>
<itemizedlist>
<listitem>
<para>
<literal>openjpa.ConnectionUserName</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.ConnectionPassword</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.ConnectionRetainMode</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.TransactionMode</literal>
</para>
</listitem>
<listitem>
<para><literal>openjpa.&lt;property&gt;</literal>, where
<emphasis>&lt;property&gt;</emphasis> is any JavaBean
property of the
<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"><classname>
org.apache.openjpa.persistence.OpenJPAEntityManager</classname></ulink>.
</para>
</listitem>
</itemizedlist>
<para>
The last option uses reflection to configure any property of OpenJPA's
<classname>EntityManager</classname> implementation with the value
supplied in your map. The first options correspond exactly to
the same-named OpenJPA configuration keys described in
<xref linkend="ref_guide_conf"/> of the Reference Guide.
</para>
<para>
OpenJPA recognizes the following string keys in the map supplied to <methodname>
createEntityManager</methodname>:
</para>
<itemizedlist>
<listitem>
<para>
<literal>openjpa.ConnectionUserName</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.ConnectionPassword</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.ConnectionRetainMode</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.TransactionMode</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.&lt;property&gt;</literal>, where <emphasis>&lt;property&gt;
</emphasis> is any JavaBean property of the
<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<classname> org.apache.openjpa.persistence.OpenJPAEntityManager</classname>
</ulink>.
</para>
</listitem>
</itemizedlist>
<para>
The last option uses reflection to configure any property of OpenJPA's
<classname>EntityManager</classname> implementation with the value supplied in
your map. The first options correspond exactly to the same-named OpenJPA
configuration keys described in <xref linkend="ref_guide_conf"></xref> of the
Reference Guide.
</para>
</note>
</section>
<section id="jpa_overview_emfactory_perscontext">
<title>Persistence Context</title>
</section>
<section id="jpa_overview_emfactory_perscontext">
<title>
Persistence Context
</title>
<indexterm zone="jpa_overview_emfactory_perscontext">
<primary>persistence context</primary>
<primary>
persistence context
</primary>
</indexterm>
<indexterm>
<primary>PersistenceContextType</primary>
<see>persistence context</see>
<primary>
PersistenceContextType
</primary>
<see>
persistence context
</see>
</indexterm>
<para>
A persistence context is a set of entities such that for any persistent
identity there is a unique entity instance. Within a persistence
context, entities are <emphasis>managed</emphasis>. The <classname>
EntityManager</classname> controls their lifecycle, and they can access
datastore resources.
</para>
A persistence context is a set of entities such that for any persistent identity
there is a unique entity instance. Within a persistence context, entities are
<emphasis>managed</emphasis>. The <classname> EntityManager</classname> controls
their lifecycle, and they can access datastore resources.
</para>
<para>
When a persistence context ends, previously-managed entities become
<emphasis>detached</emphasis>. A detached entity is no longer under
the control of the <classname>EntityManager</classname>, and no longer
has access to datastore resources. We discuss detachment is detail in
<xref linkend="jpa_overview_em_lifecycle"/>. For now, it is sufficient
to know that detachment as has two obvious consequences:
</para>
When a persistence context ends, previously-managed entities become <emphasis>
detached</emphasis>. A detached entity is no longer under the control of the
<classname>EntityManager</classname>, and no longer has access to datastore
resources. We discuss detachment is detail in
<xref linkend="jpa_overview_em_lifecycle"></xref>. For now, it is sufficient to
know that detachment as has two obvious consequences:
</para>
<orderedlist>
<listitem>
<para>
The detached entity cannot load any additional persistent
state.
</para>
</listitem>
<listitem>
<para>
The <classname>EntityManager</classname> will not return the
detached entity from <methodname>find</methodname>, nor will
queries include the detached entity in their results. Instead,
<methodname>find</methodname> method invocations and query
executions that would normally incorporate the detached entity
will create a new managed entity with the same identity.
</para>
</listitem>
<listitem>
<para>
The detached entity cannot load any additional persistent state.
</para>
</listitem>
<listitem>
<para>
The <classname>EntityManager</classname> will not return the detached entity
from <methodname>find</methodname>, nor will queries include the detached
entity in their results. Instead, <methodname>find</methodname> method
invocations and query executions that would normally incorporate the detached
entity will create a new managed entity with the same identity.
</para>
</listitem>
</orderedlist>
<note>
<para>
OpenJPA offers several features related to detaching entities. See
<xref linkend="ref_guide_detach"/> in the Reference Guide.
<xref linkend="ref_guide_detach_graph"/> in particular describes
how to use the <literal>DetachState</literal> setting to boost
the performance of merging detached entities.
</para>
</note>
<para>
Injected <classname>EntityManager</classname>s have use a
<emphasis>transaction</emphasis>, while <classname>
EntityManager</classname>s obtained through the
<classname>EntityManagerFactory</classname> have an <emphasis>
extended</emphasis> persistence context. We describe these persistence
context types below.
</para>
<section id="jpa_overview_emfactory_perscontext_trans">
<title>Transaction Persistence Context</title>
<para>
Under the transaction persistence context model, an <classname>
EntityManager</classname> begins a new persistence context
with each transaction, and ends the context when the transaction
commits or rolls back. Within the transaction, entities you
retrieve through the <classname>EntityManager</classname> or via
<classname>Queries</classname> are managed entities. They
can access datastore resources to lazy-load additional
persistent state as needed, and only one entity may exist for any
persistent identity.
</para>
<para>
When the transaction completes, all entities lose their
association with the <classname>EntityManager</classname> and
become detached. Traversing a persistent field that wasn't
already loaded now has undefined results. And using the <classname>
EntityManager</classname> or a <classname>Query</classname> to
retrieve additional objects may now create new instances with the
same persistent identities as detached instances.
</para>
<para>
If you use an <classname>EntityManager</classname> with a
transaction persistence context model outside of
an active transaction, each method invocation creates a new
persistence context, performs the method action, and ends the
persistence context. For example, consider using the
<methodname>EntityManager.find</methodname> method outside
of a transaction. The <classname>EntityManager</classname> will
create a temporary persistence context, perform the find operation,
end the persistence context, and return the detached result object
to you. A second call with the same id will return a second
detached object.
</para>
<para>
When the next transaction begins, the <classname>EntityManager
</classname> will begin a new persistence context, and will again
start returning managed entities. As you'll see in
<xref linkend="jpa_overview_em"/>, you can also merge the
previously-detached entites back into the new persistence context.
</para>
<example id="jpa_overview_emfactory_perscontext_transex">
<title>Behavior of Transaction Persistence Context</title>
<para>
The following code illustrates the behavior of entites under
an <classname>EntityManager</classname> using a transaction
persistence context.
OpenJPA offers several features related to detaching entities. See
<xref linkend="ref_guide_detach"></xref> in the Reference Guide.
<xref linkend="ref_guide_detach_graph"></xref> in particular describes how to
use the <literal>DetachState</literal> setting to boost the performance of
merging detached entities.
</para>
</note>
<para>
Injected <classname>EntityManager</classname>s have use a <emphasis>transaction
</emphasis>, while <classname> EntityManager</classname>s obtained through the
<classname>EntityManagerFactory</classname> have an <emphasis> extended
</emphasis> persistence context. We describe these persistence context types
below.
</para>
<programlisting format="linespecific">
<section id="jpa_overview_emfactory_perscontext_trans">
<title>
Transaction Persistence Context
</title>
<para>
Under the transaction persistence context model, an <classname> EntityManager
</classname> begins a new persistence context with each transaction, and ends
the context when the transaction commits or rolls back. Within the transaction,
entities you retrieve through the <classname>EntityManager</classname> or via
<classname>Queries</classname> are managed entities. They can access datastore
resources to lazy-load additional persistent state as needed, and only one
entity may exist for any persistent identity.
</para>
<para>
When the transaction completes, all entities lose their association with the
<classname>EntityManager</classname> and become detached. Traversing a
persistent field that wasn't already loaded now has undefined results. And using
the <classname> EntityManager</classname> or a <classname>Query</classname> to
retrieve additional objects may now create new instances with the same
persistent identities as detached instances.
</para>
<para>
If you use an <classname>EntityManager</classname> with a transaction
persistence context model outside of an active transaction, each method
invocation creates a new persistence context, performs the method action, and
ends the persistence context. For example, consider using the <methodname>
EntityManager.find</methodname> method outside of a transaction. The <classname>
EntityManager</classname> will create a temporary persistence context, perform
the find operation, end the persistence context, and return the detached result
object to you. A second call with the same id will return a second detached
object.
</para>
<para>
When the next transaction begins, the <classname>EntityManager</classname> will
begin a new persistence context, and will again start returning managed
entities. As you'll see in <xref linkend="jpa_overview_em"></xref>, you can
also merge the previously-detached entites back into the new persistence
context.
</para>
<example id="jpa_overview_emfactory_perscontext_transex">
<title>
Behavior of Transaction Persistence Context
</title>
<para>
The following code illustrates the behavior of entites under an <classname>
EntityManager</classname> using a transaction persistence context.
</para>
<programlisting>
EntityManager em; // injected
...
@ -273,29 +299,30 @@ assertTrue (mag4 == mag3);
Magazine mag5 = em.find (Magazine.class, magId);
assertTrue (mag5 != mag3);
</programlisting>
</example>
</example>
</section>
<section id="jpa_overview_emfactory_perscontext_extend">
<title>Extended Persistence Context</title>
<para>
An <classname>EntityManager</classname> using an extended
persistence context maintains the same persistence context for
its entire lifecycle. Whether inside a transaction or not, all
entities returned from the <classname>EntityManager</classname>
are managed, and the <classname>EntityManager</classname> never
creates two entity instances to represent the same persistent
identity. Entities only become detached when you finally close
the <classname>EntityManager</classname> (or when they are
serialized).
</para>
<example id="jpa_overview_emfactory_perscontext_extendex">
<title>Behavior of Extended Persistence Context</title>
<title>
Extended Persistence Context
</title>
<para>
The following code illustrates the behavior of entites under
an <classname>EntityManager</classname> using an extended
persistence context.
</para>
<programlisting format="linespecific">
An <classname>EntityManager</classname> using an extended persistence context
maintains the same persistence context for its entire lifecycle. Whether inside
a transaction or not, all entities returned from the <classname>EntityManager
</classname> are managed, and the <classname>EntityManager</classname> never
creates two entity instances to represent the same persistent identity. Entities
only become detached when you finally close the <classname>EntityManager
</classname> (or when they are serialized).
</para>
<example id="jpa_overview_emfactory_perscontext_extendex">
<title>
Behavior of Extended Persistence Context
</title>
<para>
The following code illustrates the behavior of entites under an <classname>
EntityManager</classname> using an extended persistence context.
</para>
<programlisting>
EntityManagerFactory emf = ...
EntityManager em = emf.createEntityManager (PersistenceContextType.EXTENDED);
@ -322,44 +349,48 @@ assertTrue (mag5 == mag1);
// instance finally becomes detached when EM closes
em.close ();
</programlisting>
</example>
</example>
</section>
</section>
<section id="jpa_overview_emfactory_close">
<title>Closing the EntityManagerFactory</title>
</section>
<section id="jpa_overview_emfactory_close">
<title>
Closing the EntityManagerFactory
</title>
<indexterm zone="jpa_overview_emfactory_close">
<primary>EntityManagerFactory</primary>
<secondary>closing</secondary>
<primary>
EntityManagerFactory
</primary>
<secondary>
closing
</secondary>
</indexterm>
<programlisting format="linespecific">
<programlisting>
public boolean isOpen ();
public void close ();
</programlisting>
<para><classname>EntityManagerFactory</classname> instances are
heavyweight objects. Each factory might maintain a metadata cache,
object state cache, <classname>EntityManager</classname> pool,
connection pool, and more. If your application no longer needs an
<classname>EntityManagerFactory</classname>, you should close it
to free these resources. When an <classname>EntityManagerFactory
</classname> closes, all <classname>EntityManager</classname>s
from that factory, and by extension all entities managed
by those <classname>EntityManager</classname>s, become invalid.
Attempting to close an <classname>EntityManagerFactory</classname>
while one or more of its <classname>EntityManager</classname>s
has an active transaction may result in an
<classname>IllegalStateException</classname>.
</para>
<para>
Closing an <classname>EntityManagerFactory</classname> should not
be taken lightly. It is much better to keep a factory open for a long
period of time than to repeatedly create and close new factories. Thus,
most applications will never close the factory, or only close it when
the application is exiting. Only applications that require multiple
factories with different configurations have an obvious reason to
create and close multiple <classname>EntityManagerFactory
</classname> instances. Once a factory is closed, all methods except
<methodname>isOpen</methodname> throw an <classname>
IllegalStateException</classname>.
</para>
</section>
</chapter>
<classname>EntityManagerFactory</classname> instances are heavyweight objects.
Each factory might maintain a metadata cache, object state cache, <classname>
EntityManager</classname> pool, connection pool, and more. If your application
no longer needs an <classname>EntityManagerFactory</classname>, you should
close it to free these resources. When an <classname>EntityManagerFactory
</classname> closes, all <classname>EntityManager</classname>s from that
factory, and by extension all entities managed by those <classname>
EntityManager</classname> s, become invalid. Attempting to close an <classname>
EntityManagerFactory</classname> while one or more of its <classname>
EntityManager</classname>s has an active transaction may result in an
<classname>IllegalStateException</classname>.
</para>
<para>
Closing an <classname>EntityManagerFactory</classname> should not be taken
lightly. It is much better to keep a factory open for a long period of time than
to repeatedly create and close new factories. Thus, most applications will never
close the factory, or only close it when the application is exiting. Only
applications that require multiple factories with different configurations have
an obvious reason to create and close multiple <classname>EntityManagerFactory
</classname> instances. Once a factory is closed, all methods except
<methodname>isOpen</methodname> throw an <classname> IllegalStateException
</classname>.
</para>
</section>
</chapter>

127
openjpa-project/src/doc/manual/jpa_overview_intro.xml
View File

@ -1,57 +1,80 @@
<chapter id="jpa_overview_intro">
<title>Introduction</title>
<para><indexterm><primary>EJB3 Persistence</primary><see>EJB</see></indexterm><indexterm><primary>EJB</primary></indexterm>
Enterprise Java Beans 3.0 Persistence (EJB persistence) is a specification
from Sun Microsystems for the persistence of Java objects to any relational
datastore. EJB persistence requires J2SE 1.5 (also referred to as "Java 5")
or higher, as it makes heavy use of new Java language features such as
annotations and generics. This document provides an overview of EJB
persistence. Unless otherwise noted, the information presented
applies to all EJB persistence implementations.
</para>
<note>
<para>
This document describes the Public Draft of the EJB 3.0
persistence specification.
<chapter id="jpa_overview_intro">
<title>
Introduction
</title>
<para>
<indexterm>
<primary>
EJB3 Persistence
</primary>
<see>
JPA
</see>
</indexterm>
<indexterm>
<primary>
JPA
</primary>
</indexterm>
The Java Persistence API (JPA) is a specification from
Sun Microsystems for the persistence of Java objects to any relational
datastore. JPA requires J2SE 1.5 (also referred to as "Java 5") or
higher, as it makes heavy use of new Java language features such as annotations
and generics. This document provides an overview of JPA. Unless
otherwise noted, the information presented applies to all JPA implementations.
</para>
<note>
<para>
For coverage of OpenJPA's many extensions to the EJB persistence
specification, see the <link linkend="ref_guide_intro">Reference
Guide</link>.
</para>
</note>
<section id="jpa_overview_intro_audience">
<title>Intended Audience</title>
For coverage of OpenJPA's many extensions to the JPA specification,
see the <link linkend="ref_guide_intro">Reference Guide</link>.
</para>
</note>
<section id="jpa_overview_intro_audience">
<title>
Intended Audience
</title>
<para>
This document is intended for developers who want to learn about
EJB persistence in order to use it in their applications.
It assumes that you have a strong knowledge of object-oriented concepts
and Java, including Java 5 annotations and generics. It also assumes
some experience with relational databases and the
Structured Query Language (SQL).
</para>
</section>
<section id="jpa_overview_intro_transpers">
<title>Lightweight Persistence</title>
This document is intended for developers who want to learn about JPA
in order to use it in their applications. It assumes that you have a strong
knowledge of object-oriented concepts and Java, including Java 5 annotations and
generics. It also assumes some experience with relational databases and the
Structured Query Language (SQL).
</para>
</section>
<section id="jpa_overview_intro_transpers">
<title>
Lightweight Persistence
</title>
<indexterm zone="jpa_overview_intro_transpers">
<primary>lightweight persistence</primary>
<primary>
lightweight persistence
</primary>
</indexterm>
<para><indexterm><primary>persistent data</primary></indexterm><emphasis>Persistent data</emphasis> is information that can
outlive the program that creates it. The majority of complex
programs use persistent data: GUI applications need to store user
preferences across program invocations, web applications track
user movements and orders over long periods of time, etc.
</para>
<para><emphasis>Lightweight persistence</emphasis> is the storage and
retrieval of persistent data with little or no work from you, the
developer. For example, Java serialization<indexterm><primary>serialization</primary></indexterm> is a form of
lightweight persistence because it can be used to persist Java
objects directly to a file with very little effort. Serialization's
capabilities as a lightweight persistence mechanism pale in
comparison to those provided by EJB, however. The next
chapter compares EJB to serialization and other available
persistence mechanisms.
</para>
</section>
</chapter>
<para>
<indexterm>
<primary>
persistent data
</primary>
</indexterm>
<emphasis>Persistent data</emphasis> is information that can outlive the program
that creates it. The majority of complex programs use persistent data: GUI
applications need to store user preferences across program invocations, web
applications track user movements and orders over long periods of time, etc.
</para>
<para>
<emphasis>Lightweight persistence</emphasis> is the storage and retrieval of
persistent data with little or no work from you, the developer. For example,
Java serialization
<indexterm>
<primary>
serialization
</primary>
</indexterm>
is a form of lightweight persistence because it can be used to persist Java
objects directly to a file with very little effort. Serialization's capabilities
as a lightweight persistence mechanism pale in comparison to those provided by
JPA, however. The next chapter compares JPA to serialization and other available
persistence mechanisms.
</para>
</section>
</chapter>

4457
openjpa-project/src/doc/manual/jpa_overview_mapping.xml
View File

File diff suppressed because it is too large Load Diff

3214
openjpa-project/src/doc/manual/jpa_overview_meta.xml
View File

File diff suppressed because it is too large Load Diff

1948
openjpa-project/src/doc/manual/jpa_overview_pc.xml
View File

File diff suppressed because it is too large Load Diff

340
openjpa-project/src/doc/manual/jpa_overview_persistence.xml
View File

@ -1,69 +1,89 @@
<chapter id="jpa_overview_persistence">
<title>Persistence</title>
<indexterm zone="jpa_overview_persistence">
<primary>Persistence</primary>
</indexterm>
<indexterm zone="jpa_overview_persistence">
<primary>EntityManagerFactory</primary>
<secondary>construction</secondary>
</indexterm>
<indexterm zone="jpa_overview_persistence">
<primary>Persistence</primary>
<secondary>getEntityManagerFactory</secondary>
</indexterm>
<indexterm zone="jpa_overview_persistence">
<primary>getEntityManagerFactory</primary>
<seealso>Persistence</seealso>
</indexterm>
<mediaobject>
<chapter id="jpa_overview_persistence">
<title>
Persistence
</title>
<indexterm zone="jpa_overview_persistence">
<primary>
Persistence
</primary>
</indexterm>
<indexterm zone="jpa_overview_persistence">
<primary>
EntityManagerFactory
</primary>
<secondary>
construction
</secondary>
</indexterm>
<indexterm zone="jpa_overview_persistence">
<primary>
Persistence
</primary>
<secondary>
getEntityManagerFactory
</secondary>
</indexterm>
<indexterm zone="jpa_overview_persistence">
<primary>
getEntityManagerFactory
</primary>
<seealso>
Persistence
</seealso>
</indexterm>
<mediaobject>
<imageobject>
<!-- PNG image data, 427 x 121 (see README) -->
<imagedata fileref="img/persistence.png" width="285px"/>
<!-- PNG image data, 427 x 121 (see README) -->
<imagedata fileref="img/persistence.png" width="285px">
</imagedata>
</imageobject>
</mediaobject>
<note>
</mediaobject>
<note>
<para>
OpenJPA also includes the
<ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"><classname>OpenJPAPersistence</classname></ulink> helper class to provide
additional utility methods.
OpenJPA also includes the
<ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"><classname>
OpenJPAPersistence</classname></ulink> helper class to provide additional
utility methods.
</para>
</note>
<para>
Within a container, you will typically use <emphasis>injection</emphasis> to
access an <classname>EntityManagerFactory</classname>. Applications operating
of a container, however, can use the
<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Persistence.html">
<classname>Persistence</classname></ulink> class to obtain <classname>
EntityManagerFactory</classname> objects in a vendor-neutral fashion.
</para>
</note>
<para>
Within a container, you will typically use <emphasis>injection
</emphasis> to access an <classname>EntityManagerFactory</classname>.
Applications operating of a container, however, can use the
<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Persistence.html"><classname>Persistence</classname></ulink> class to obtain
<classname>EntityManagerFactory</classname> objects in a vendor-neutral
fashion.
</para>
<programlisting format="linespecific">
<programlisting>
public static EntityManagerFactory createEntityManagerFactory (String name);
public static EntityManagerFactory createEntityManagerFactory (String name, Map props);
</programlisting>
<para>
Each <methodname>createEntityManagerFactory</methodname> method searches
the system for an <classname>EntityManagerFactory</classname> definition
with the given name. Use <literal>null</literal> for an unnamed factory.
The optional map contains vendor-specific property settings used to further
configure the factory.
</para>
<para><filename>persistence.xml</filename> files define <classname>
EntityManagerFactories</classname>. The <methodname>
createEntityManagerFactory</methodname> methods search for <filename>
persistence.xml</filename> files within the <filename>META-INF</filename>
directory of any <literal>CLASSPATH</literal> element. For example, if
your <literal>CLASSPATH</literal> contains the <filename>conf</filename>
directory, you could place an <classname>EntityManagerFactory</classname>
definition in <filename>conf/META-INF/persistence.xml</filename>.
</para>
<section id="jpa_overview_persistence_xml">
<title>persistence.xml</title>
<para>
The <filename>persistence.xml</filename> file format obeys the following
Document Type Descriptor (DTD):
<para>
Each <methodname>createEntityManagerFactory</methodname> method searches the
system for an <classname>EntityManagerFactory</classname> definition with the
given name. Use <literal>null</literal> for an unnamed factory. The optional map
contains vendor-specific property settings used to further configure the
factory.
</para>
<programlisting format="linespecific">
<para>
<filename>persistence.xml</filename> files define <classname>
EntityManagerFactories</classname>. The <methodname> createEntityManagerFactory
</methodname> methods search for <filename> persistence.xml</filename> files
within the <filename>META-INF</filename> directory of any <literal>CLASSPATH
</literal> element. For example, if your <literal>CLASSPATH</literal> contains
the <filename>conf</filename> directory, you could place an <classname>
EntityManagerFactory</classname> definition in <filename>
conf/META-INF/persistence.xml</filename>.
</para>
<section id="jpa_overview_persistence_xml">
<title>
persistence.xml
</title>
<para>
The <filename>persistence.xml</filename> file format obeys the following
Document Type Descriptor (DTD):
</para>
<programlisting>
&lt;!ELEMENT persistence (persistence-unit*)&gt;
&lt;!ELEMENT persistence-unit (description?,provider?,jta-datasource?,
non-jta-datasource?,(class|jar-file|mapping-file)*,
@ -84,95 +104,98 @@ public static EntityManagerFactory createEntityManagerFactory (String name, Map
&lt;!ATTLIST property value CDATA #REQUIRED&gt;
</programlisting>
<para>
The root element of a <filename>persistence.xml</filename> file is
<literal>persistence</literal>, which then contains one or more
<literal>persistence-unit</literal> definitions.
Each persistence unit describes the configuration for the entity
managers created by the persistence unit's entity manager factory.
The persistence unit can specify these elements and attribtues.
</para>
The root element of a <filename>persistence.xml</filename> file is <literal>
persistence</literal>, which then contains one or more <literal>
persistence-unit</literal> definitions. Each persistence unit describes the
configuration for the entity managers created by the persistence unit's entity
manager factory. The persistence unit can specify these elements and attribtues.
</para>
<itemizedlist>
<listitem>
<para><literal>name</literal>: This is the name you pass to the
<methodname>Persistence.createEntityManagerFactory</methodname>
methods described above. The name attribute is required.
</para>
</listitem>
<listitem>
<para><literal>transaction-type</literal>: Whether to use managed
(<literal>JTA</literal>) or local
(<literal>RESOURCE_LOCAL</literal>) transaction management.
Defaults to <literal>JTA</literal>.
</para>
</listitem>
<listitem>
<para><literal>provider</literal>: If you are using a third-party
JPA vendor, this element names its implementation of the
<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/spi/PersistenceProvider.html"><classname>PersistenceProvider</classname></ulink> bootstrapping
interface.
</para>
<note>
<para>
Set the <literal>provider</literal> to <classname>
org.apache.openjpa.persistence.PersistenceProviderImpl</classname>
to use OpenJPA.
</para>
</note>
</listitem>
<listitem>
<para><literal>jta-data-source</literal>: The JNDI name of a JDBC
<classname>DataSource</classname> that is automatically enlisted
in JTA transactions. This may be an XA <classname>
DataSource</classname>.
</para>
</listitem>
<listitem>
<para><literal>non-jta-data-source</literal>: The JNDI name of a JDBC
<classname>DataSource</classname> that is not enlisted
in JTA transactions.
</para>
</listitem>
<listitem>
<para><literal>mapping-file</literal>*: The resource names of
XML mapping files for entities and embeddable classes.
You can also specify mapping information in an <filename>
orm.xml</filename> file in your <filename>META-INF</filename>
directory. If present, the <filename>orm.xml</filename>
mapping file will be read automatically.
</para>
</listitem>
<listitem>
<para><literal>jar-file</literal>*: The names of jar files containing
entities and embeddable classes. The implementation will scan
the jar for annotated classes.
</para>
</listitem>
<listitem>
<para><literal>class</literal>*: The class names of entities and
embeddable classes.
</para>
</listitem>
<listitem>
<para><literal>properties</literal>: This element contains nested
<literal>property</literal> elements used to specify
vendor-specific settings. Each <literal>property</literal>
has a name attribute and a value attribute.
</para>
<note>
<para>
The Reference Guide's <xref linkend="ref_guide_conf"/>
describes OpenJPA's configuration properties.
</para>
</note>
</listitem>
<listitem>
<para>
<literal>name</literal>: This is the name you pass to the <methodname>
Persistence.createEntityManagerFactory</methodname> methods described above. The
name attribute is required.
</para>
</listitem>
<listitem>
<para>
<literal>transaction-type</literal>: Whether to use managed ( <literal>JTA
</literal>) or local ( <literal>RESOURCE_LOCAL</literal>) transaction
management. Defaults to <literal>JTA</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>provider</literal>: If you are using a third-party JPA vendor, this
element names its implementation of the
<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/spi/PersistenceProvider.html">
<classname>PersistenceProvider</classname></ulink> bootstrapping interface.
</para>
<note>
<para>
Set the <literal>provider</literal> to <classname>
org.apache.openjpa.persistence.PersistenceProviderImpl</classname> to use
OpenJPA.
</para>
</note>
</listitem>
<listitem>
<para>
<literal>jta-data-source</literal>: The JNDI name of a JDBC <classname>
DataSource</classname> that is automatically enlisted in JTA transactions. This
may be an XA <classname> DataSource</classname>.
</para>
</listitem>
<listitem>
<para>
<literal>non-jta-data-source</literal>: The JNDI name of a JDBC <classname>
DataSource</classname> that is not enlisted in JTA transactions.
</para>
</listitem>
<listitem>
<para>
<literal>mapping-file</literal> *: The resource names of XML mapping files for
entities and embeddable classes. You can also specify mapping information in an
<filename> orm.xml</filename> file in your <filename>META-INF</filename>
directory. If present, the <filename>orm.xml</filename> mapping file will be
read automatically.
</para>
</listitem>
<listitem>
<para>
<literal>jar-file</literal> *: The names of jar files containing entities and
embeddable classes. The implementation will scan the jar for annotated classes.
</para>
</listitem>
<listitem>
<para>
<literal>class</literal> *: The class names of entities and embeddable classes.
</para>
</listitem>
<listitem>
<para>
<literal>properties</literal>: This element contains nested <literal>property
</literal> elements used to specify vendor-specific settings. Each <literal>
property</literal> has a name attribute and a value attribute.
</para>
<note>
<para>
The Reference Guide's <xref linkend="ref_guide_conf"></xref> describes OpenJPA's
configuration properties.
</para>
</note>
</listitem>
</itemizedlist>
<para>
Here is a typical <filename>persistence.xml</filename> file for a
non-EE environment:
</para>
Here is a typical <filename>persistence.xml</filename> file for a non-EE
environment:
</para>
<example id="jpa_overview_persistence_xmlex">
<title>persistence.xml</title>
<programlisting format="linespecific">
<title>
persistence.xml
</title>
<programlisting>
&lt;?xml version="1.0"?&gt;
&lt;persistence&gt;
&lt;persistence-unit name="openjpa"&gt;
@ -192,20 +215,23 @@ public static EntityManagerFactory createEntityManagerFactory (String name, Map
&lt;/persistence&gt;
</programlisting>
</example>
</section>
<section id="jpa_overview_persistence_use">
<title>Non-EE Use</title>
</section>
<section id="jpa_overview_persistence_use">
<title>
Non-EE Use
</title>
<para>
The example below demonstrates the <classname>Persistence</classname>
class in action. You will typically execute code like this on
application startup, then cache the resulting factory for future use.
This bootstrapping code is only necessary in non-EE environments; in
an EE environment <classname>EntityManagerFactories</classname> are
typically injected.
</para>
The example below demonstrates the <classname>Persistence</classname> class in
action. You will typically execute code like this on application startup, then
cache the resulting factory for future use. This bootstrapping code is only
necessary in non-EE environments; in an EE environment <classname>
EntityManagerFactories</classname> are typically injected.
</para>
<example id="jpa_overview_persistence_getemfactory">
<title>Obtaining an EntityManagerFactory</title>
<programlisting format="linespecific">
<title>
Obtaining an EntityManagerFactory
</title>
<programlisting>
// if your persistence.xml file does not contain all settings already, you
// can add vendor settings to a map
Properties props = new Properties ();
@ -215,5 +241,5 @@ Properties props = new Properties ();
EntityManagerFactory emf = Persistence.createEntityManagerFactory ("openjpa", props);
</programlisting>
</example>
</section>
</chapter>
</section>
</chapter>

5433
openjpa-project/src/doc/manual/jpa_overview_query.xml
View File

File diff suppressed because it is too large Load Diff

491
openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml
View File

@ -1,135 +1,195 @@
<chapter id="jpa_overview_sqlquery">
<title>SQL Queries</title>
<indexterm zone="jpa_overview_sqlquery">
<primary>SQL queries</primary>
<seealso>Query</seealso>
</indexterm>
<indexterm>
<primary>Query</primary>
<secondary>SQL</secondary>
<see>SQL queries</see>
</indexterm>
<indexterm>
<primary>SQL</primary>
<secondary>queries</secondary>
<see>SQL queries</see>
</indexterm>
<indexterm>
<primary>Native</primary>
<secondary>queries</secondary>
<see>SQL queries</see>
</indexterm>
<para>
JPQL is a powerful query language, but there are times when it is
not enough. Maybe you're migrating a JDBC application to JPA
on a strict deadline, and you don't have time to translate your existing
SQL selects to JPQL. Or maybe a certain query requires
database-specific SQL your JPA implementation doesn't support.
Or maybe your DBA has spent hours crafting the perfect select statement
for a query in your application's critical path. Whatever the reason, SQL
queries can remain an essential part of an application.
</para>
<para>
You are probably familiar with executing SQL queries by obtaining a
<classname>java.sql.Connection</classname>, using the JDBC APIs to create
a <classname>Statement</classname>, and executing that <classname>Statement
</classname> to obtain a <classname>ResultSet</classname>. And of course,
you are free to continue using this low-level approach to SQL execution in
your JPA applications. However, JPA also supports executing SQL queries
through the <classname>javax.persistence.Query</classname>
interface introduced in <xref linkend="jpa_overview_query"/>.
Using a JPA SQL query, you can retrieve either persistent objects
or projections of column values. The following sections detail each use.
</para>
<section id="jpa_overview_sqlquery_create">
<title>Creating SQL Queries</title>
<chapter id="jpa_overview_sqlquery">
<title>
SQL Queries
</title>
<indexterm zone="jpa_overview_sqlquery">
<primary>
SQL queries
</primary>
<seealso>
Query
</seealso>
</indexterm>
<indexterm>
<primary>
Query
</primary>
<secondary>
SQL
</secondary>
<see>
SQL queries
</see>
</indexterm>
<indexterm>
<primary>
SQL
</primary>
<secondary>
queries
</secondary>
<see>
SQL queries
</see>
</indexterm>
<indexterm>
<primary>
Native
</primary>
<secondary>
queries
</secondary>
<see>
SQL queries
</see>
</indexterm>
<para>
JPQL is a powerful query language, but there are times when it is not enough.
Maybe you're migrating a JDBC application to JPA on a strict deadline, and you
don't have time to translate your existing SQL selects to JPQL. Or maybe a
certain query requires database-specific SQL your JPA implementation doesn't
support. Or maybe your DBA has spent hours crafting the perfect select statement
for a query in your application's critical path. Whatever the reason, SQL
queries can remain an essential part of an application.
</para>
<para>
You are probably familiar with executing SQL queries by obtaining a <classname>
java.sql.Connection</classname>, using the JDBC APIs to create a <classname>
Statement</classname>, and executing that <classname>Statement</classname> to
obtain a <classname>ResultSet</classname>. And of course, you are free to
continue using this low-level approach to SQL execution in your JPA
applications. However, JPA also supports executing SQL queries through the
<classname>javax.persistence.Query</classname> interface introduced in
<xref linkend="jpa_overview_query"></xref>. Using a JPA SQL query, you can
retrieve either persistent objects or projections of column values. The
following sections detail each use.
</para>
<section id="jpa_overview_sqlquery_create">
<title>
Creating SQL Queries
</title>
<indexterm zone="jpa_overview_sqlquery_create">
<primary>SQL queries</primary>
<secondary>creating</secondary>
<primary>
SQL queries
</primary>
<secondary>
creating
</secondary>
</indexterm>
<para>
The <classname>EntityManager</classname> has two factory methods
suitable for creating SQL queries:
</para>
<programlisting format="linespecific">
The <classname>EntityManager</classname> has two factory methods suitable for
creating SQL queries:
</para>
<programlisting>
public Query createNativeQuery (String sqlString, Class resultClass);
public Query createNativeQuery (String sqlString, String resultSetMapping);
</programlisting>
<para>
The first method is used to create a new <classname>Query</classname>
instance that will return instances of the specified class.
</para>
The first method is used to create a new <classname>Query</classname> instance
that will return instances of the specified class.
</para>
<para>
The second method uses a <literal>SqlResultSetMapping</literal>
to determine the type of object or objects to return.
The example below shows these methods in action.
</para>
The second method uses a <literal>SqlResultSetMapping</literal> to determine the
type of object or objects to return. The example below shows these methods in
action.
</para>
<example id="jpa_overview_sqlquery_createex">
<title>Creating a SQL Query</title>
<programlisting format="linespecific">
<title>
Creating a SQL Query
</title>
<programlisting>
EntityManager em = ...;
Query query = em.createNativeQuery ("SELECT * FROM MAG", Magazine.class);
processMagazines (query.getResultList ());
</programlisting>
</example>
<note>
<para><indexterm><primary>SQL queries</primary><secondary>stored procedures</secondary></indexterm><indexterm><primary>stored procedures</primary><secondary>as queries</secondary><seealso>Query</seealso></indexterm>
In addition to SELECT statements, OpenJPA supports stored procedure
invocations as SQL queries. OpenJPA will assume any SQL that does
not begin with the <literal>SELECT</literal> keyword (ignoring
case) is a stored procedure call, and invoke it as such at the
JDBC level.
</para>
<para>
<indexterm>
<primary>
SQL queries
</primary>
<secondary>
stored procedures
</secondary>
</indexterm>
<indexterm>
<primary>
stored procedures
</primary>
<secondary>
as queries
</secondary>
<seealso>
Query
</seealso>
</indexterm>
In addition to SELECT statements, OpenJPA supports stored procedure invocations
as SQL queries. OpenJPA will assume any SQL that does not begin with the
<literal>SELECT</literal> keyword (ignoring case) is a stored procedure call,
and invoke it as such at the JDBC level.
</para>
</note>
</section>
<section id="jpa_overview_sqlquery_obj">
<title>Retrieving Persistent Objects with SQL</title>
</section>
<section id="jpa_overview_sqlquery_obj">
<title>
Retrieving Persistent Objects with SQL
</title>
<indexterm zone="jpa_overview_sqlquery_obj">
<primary>SQL queries</primary>
<secondary>retrieving persistent objects</secondary>
<primary>
SQL queries
</primary>
<secondary>
retrieving persistent objects
</secondary>
</indexterm>
<indexterm zone="jpa_overview_sqlquery_obj">
<primary>persistent objects</primary>
<secondary>retrieving with SQL</secondary>
<seealso>SQL queries</seealso>
<primary>
persistent objects
</primary>
<secondary>
retrieving with SQL
</secondary>
<seealso>
SQL queries
</seealso>
</indexterm>
<para>
When you give a SQL <classname>Query</classname> a candidate class, it
will return persistent instances of that class. At a minimum, your
SQL must select the
class' primary key columns, discriminator column (if mapped), and
version column (also if mapped). The JPA runtime uses the values
of the primary key columns to construct each result object's identity,
and possibly to match it with a persistent object already in the
<classname>EntityManager</classname>'s cache. When an object is
not already cached, the
implementation creates a new object to represent the current result
row. It might use the discriminator column value to make sure it
constructs an object of the correct subclass. Finally, the query
records available version column data for use in optimistic concurrency
checking, should you later change the result object and flush it back
to the database.
</para>
When you give a SQL <classname>Query</classname> a candidate class, it will
return persistent instances of that class. At a minimum, your SQL must select
the class' primary key columns, discriminator column (if mapped), and version
column (also if mapped). The JPA runtime uses the values of the primary key
columns to construct each result object's identity, and possibly to match it
with a persistent object already in the <classname>EntityManager</classname>'s
cache. When an object is not already cached, the implementation creates a new
object to represent the current result row. It might use the discriminator
column value to make sure it constructs an object of the correct subclass.
Finally, the query records available version column data for use in optimistic
concurrency checking, should you later change the result object and flush it
back to the database.
</para>
<para>
Aside from the primary key, discriminator, and version columns, any
columns you select are used to populate the persistent fields of each
result object. JPA implementations will compete on how effectively
they map your selected data to your persistent instance fields.
</para>
Aside from the primary key, discriminator, and version columns, any columns you
select are used to populate the persistent fields of each result object. JPA
implementations will compete on how effectively they map your selected data to
your persistent instance fields.
</para>
<para>
Let's make the discussion above concrete with an example. It uses
the following simple mapping between a class and the database:
</para>
Let's make the discussion above concrete with an example. It uses the following
simple mapping between a class and the database:
</para>
<mediaobject>
<imageobject>
<!-- PNG image data, 320 x 149 (see README) -->
<imagedata fileref="img/sqlquery-model.png" width="213px"/>
</imageobject>
<imageobject>
<!-- PNG image data, 320 x 149 (see README) -->
<imagedata fileref="img/sqlquery-model.png" width="213px">
</imagedata>
</imageobject>
</mediaobject>
<example id="jpa_overview_sqlquery_objex">
<title>Retrieving Persistent Objects</title>
<programlisting format="linespecific">
<title>
Retrieving Persistent Objects
</title>
<programlisting>
Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, "
+ "VERS FROM MAG WHERE PRICE &gt; 5 AND PRICE &lt; 10", Magazine.class);
List&lt;Magazine&gt; results = query.getResultList ();
@ -138,13 +198,15 @@ for (Magazine mag : results)
</programlisting>
</example>
<para>
The query above works as advertised, but isn't very flexible. Let's
update it to take in parameters for the minimum and maximum price,
so we can reuse it to find magazines in any price range:
</para>
The query above works as advertised, but isn't very flexible. Let's update it to
take in parameters for the minimum and maximum price, so we can reuse it to find
magazines in any price range:
</para>
<example id="jpa_overview_sqlquery_obj_paramex">
<title>SQL Query Parameters</title>
<programlisting format="linespecific">
<title>
SQL Query Parameters
</title>
<programlisting>
Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, "
+ "VERS FROM MAG WHERE PRICE &gt; ?1 AND PRICE &lt; ?2", Magazine.class);
@ -156,183 +218,28 @@ for (Magazine mag : results)
processMagazine (mag);
</programlisting>
</example>
<para><indexterm><primary>SQL queries</primary><secondary>parameters</secondary></indexterm><indexterm><primary>parameters</primary><secondary>in SQL queries</secondary><seealso>SQL queries</seealso></indexterm>
Like JDBC prepared statements, SQL queries represent parameters with
question marks, but are followed by an integer to represent its
index.
</para>
</section>
<!--
<section id="jpa_overview_sqlquery_proj">
<title>SQL Projections</title>
<indexterm zone="jpa_overview_sqlquery_proj">
<primary>SQL queries</primary>
<secondary>projections</secondary>
</indexterm>
<indexterm zone="jpa_overview_sqlquery_proj">
<primary>projections</primary>
<secondary>of column data</secondary>
<seealso>SQL queries</seealso>
</indexterm>
<para>
SQL queries without a candidate class are treated as projections of
column data. If you select a single column, the query returns
a list of <classname>Object</classname>s. If you select multiple
columns, it returns a list of <classname>Object[]</classname>s.
In either case, each column value is obtained using the
<methodname>java.sql.ResultSet.getObject</methodname> method. The
following example demonstrates a query for the values of the
<literal>ISBN</literal> and <literal>VERS</literal> columns of all
<literal>MAG</literal> table records, using the data model we
defined in <xref linkend="jpa_overview_sqlquery_obj"/>.
</para>
<example id="jpa_overview_sqlquery_projex">
<title>Column Projection</title>
<programlisting>
Query query = em.newQuery ("javax.persistence.query.SQL",
"SELECT ISBN, VERS FROM MAG");
List results = query.getResultList ();
for (Iterator itr = results.iterator (); itr.hasNext ();)
{
Object[] data = (Object[]) results.next ();
processISBNAndVersion (data[0], data[1]);
}
</programlisting>
<para>
Notice that in the code above, we did not set a candidate class.
Therefore, the query is treated as a projection.
</para>
</example>
<para>
<indexterm>
<primary>SQL queries</primary>
<secondary>result class</secondary>
</indexterm>
Our discussion of JPQL query result classes in
<xref linkend="jpa_overview_query_resultcls"/> also
applies to SQL queries. As with JPQL queries, SQL queries can
automatically pack their results into objects of a specified type.
JPA uses the <methodname>java.sql.ResultSetMetaData.getColumnLabel
</methodname> method to match each column alias to the result class'
public fields and JavaBean setter methods. Here is a modification of
our example above that packs the selected column values into JavaBean
instances.
</para>
<example id="jpa_overview_sqlquery_proj_labelex">
<title>Result Class</title>
<programlisting>
public class Identity
{
private String id;
private int versionNumber;
public void setId (String id)
{
this.id = id;
}
public String getId ()
{
return id;
}
public void setVersionNumber (int versionNumber)
{
this.versionNumber = versionNumber;
}
public int getVersionNumber ()
{
return versionNumber;
}
}
Query query = em.createNativeQuery ("javax.persistence.query.SQL",
"SELECT ISBN AS id, VERS AS versionNumber FROM MAG", Identity.class);
List results = query.getResultList ();
for (Iterator itr = results.iterator (); itr.hasNext ();)
processIdentity ((Identity) itr.next ());
</programlisting>
</example>
</section>
<section id="jpa_overview_sqlquery_named">
<title>Named SQL Queries</title>
<indexterm zone="jpa_overview_sqlquery_named">
<primary>SQL queries</primary>
<secondary>named</secondary>
<see>named queries</see>
</indexterm>
<indexterm zone="jpa_overview_sqlquery_named">
<primary>named queries</primary>
<secondary>SQL</secondary>
</indexterm>
<para>
We discussed how to write named JPQL queries in
<xref linkend="jpa_overview_query_named"/>. Named queries, however,
are not limited to JPQL. By setting the <literal>query</literal>
element's <literal>language</literal> attribute to <literal>
javax.persistence.query.SQL</literal>, you can define a named SQL query. A
named SQL query within a <literal>class</literal> element queries for
instances of that class; a named SQL query outside of a <literal>class
</literal> element acts as a column data projection.
</para>
<example id="jpa_overview_sqlquery_namedex">
<title>Named SQL Queries</title>
<programlisting>
<![CDATA[<?xml version="1.0"?>
<jdoquery>
<query name="salesReport" language="javax.persistence.query.SQL">
SELECT TITLE, PRICE * COPIES FROM MAG
</query>
<package name="org.mag">
<class name="Magazine">
<query name="findByTitle" language="javax.persistence.query.SQL">
SELECT * FROM MAG WHERE TITLE = ?
</query>
</class>
</package>
</jdoquery>]]>
</programlisting>
<para>
The <literal>salesReport</literal> query above returns the title
and revenue generated for each <classname>Magazine</classname>.
Because it is a projection, it does not have a candidate class, and
so we specify it at the root level.
</para>
<para>
The <literal>findByTitle</literal> query returns the <classname>
Magazine</classname> with the title given on execution. The code
below executes both queries.
</para>
<programlisting>
EntityManager em = ...;
Query query = em.newNamedQuery (null, "salesReport");
List sales = query.getResultList ();
for (Iterator itr = sales.iterator (); itr.hasNext ();)
{
Object[] salesData = (Object[]) itr.next ();
processSalesData ((String) salesData[0], (Number) salesData[1]);
}
query = em.newNamedQuery (Magazine.class, "findByTitle");
query.setUnique (true);
Magazine jdj = (Magazine) query.execute ("JDJ");
</programlisting>
</example>
</section>
<section id="jpa_overview_sqlquery_conclusion">
<title>Conclusion</title>
<para>
If you've used relational databases extensively, you might be tempted
to perform all your JPA queries with SQL. Try to resist this
temptation. SQL queries tie your application to the particulars of
your current table model and database vendor. If you stick with JPQL,
on the other hand, you can port your application to other schemas and
database vendors without any changes to your code. Additionally,
most JPA implementations already produce highly optimized SQL from
your JPQL filters, and many are able to cache JPQL query results
for added performance.
</para>
</section>
-->
</chapter>
<para>
<indexterm>
<primary>
SQL queries
</primary>
<secondary>
parameters
</secondary>
</indexterm>
<indexterm>
<primary>
parameters
</primary>
<secondary>
in SQL queries
</secondary>
<seealso>
SQL queries
</seealso>
</indexterm>
Like JDBC prepared statements, SQL queries represent parameters with question
marks, but are followed by an integer to represent its index.
</para>
</section>
</chapter>

551
openjpa-project/src/doc/manual/jpa_overview_trans.xml
View File

@ -1,214 +1,403 @@
<chapter id="jpa_overview_trans">
<title>Transaction</title>
<indexterm zone="jpa_overview_trans">
<primary>transactions</primary>
<seealso>Transaction</seealso>
</indexterm>
<para>
Transactions are critical to maintaining data integrity. They are
used to group operations into units of work that act in an
all-or-nothing fashion. Transactions have the following qualities:
</para>
<itemizedlist>
<chapter id="jpa_overview_trans">
<title>
Transaction
</title>
<indexterm zone="jpa_overview_trans">
<primary>
transactions
</primary>
<seealso>
Transaction
</seealso>
</indexterm>
<para>
Transactions are critical to maintaining data integrity. They are used to group
operations into units of work that act in an all-or-nothing fashion.
Transactions have the following qualities:
</para>
<itemizedlist>
<listitem>
<para><indexterm><primary>atomicity</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>atomicity</secondary></indexterm><emphasis>Atomicity</emphasis>. Atomicity refers to the
all-or-nothing property of transactions. Either every
data update in the transaction completes successfully, or they
all fail, leaving the datastore in its original state. A
transaction cannot be only partially successful.
</para>
<para>
<indexterm>
<primary>
atomicity
</primary>
<seealso>
transactions
</seealso>
</indexterm>
<indexterm>
<primary>
transactions
</primary>
<secondary>
atomicity
</secondary>
</indexterm>
<emphasis>Atomicity</emphasis>. Atomicity refers to the all-or-nothing property
of transactions. Either every data update in the transaction completes
successfully, or they all fail, leaving the datastore in its original state. A
transaction cannot be only partially successful.
</para>
</listitem>
<listitem>
<para><indexterm><primary>consistency</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>consistency</secondary></indexterm><emphasis>Consistency</emphasis>. Each transaction takes the
datastore from one consistent state to another consistent
state.
</para>
<para>
<indexterm>
<primary>
consistency
</primary>
<seealso>
transactions
</seealso>
</indexterm>
<indexterm>
<primary>
transactions
</primary>
<secondary>
consistency
</secondary>
</indexterm>
<emphasis>Consistency</emphasis>. Each transaction takes the datastore from one
consistent state to another consistent state.
</para>
</listitem>
<listitem>
<para><indexterm><primary>isolation</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>isolation</secondary></indexterm><emphasis>Isolation</emphasis>. Transactions are isolated from
each other. When you are reading persistent data in one
transaction, you cannot "see" the changes that are being made
to that data in other transactions. Similarly,
the updates you make in one transaction cannot conflict with
updates made in concurrent transactions. The form of
conflict resolution employed depends on whether you are using
pessimistic or optimistic transactions. Both types are
described later in this chapter.
</para>
<para>
<indexterm>
<primary>
isolation
</primary>
<seealso>
transactions
</seealso>
</indexterm>
<indexterm>
<primary>
transactions
</primary>
<secondary>
isolation
</secondary>
</indexterm>
<emphasis>Isolation</emphasis>. Transactions are isolated from each other. When
you are reading persistent data in one transaction, you cannot "see" the changes
that are being made to that data in other transactions. Similarly, the updates
you make in one transaction cannot conflict with updates made in concurrent
transactions. The form of conflict resolution employed depends on whether you
are using pessimistic or optimistic transactions. Both types are described later
in this chapter.
</para>
</listitem>
<listitem>
<para><indexterm><primary>durability</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>durability</secondary></indexterm><emphasis>Durability</emphasis>. The effects of successful
transactions are durable; the updates made to persistent data
last for the lifetime of the datastore.
</para>
<para>
<indexterm>
<primary>
durability
</primary>
<seealso>
transactions
</seealso>
</indexterm>
<indexterm>
<primary>
transactions
</primary>
<secondary>
durability
</secondary>
</indexterm>
<emphasis>Durability</emphasis>. The effects of successful transactions are
durable; the updates made to persistent data last for the lifetime of the
datastore.
</para>
</listitem>
</itemizedlist>
<para><indexterm><primary>ACID</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>ACID</secondary></indexterm>
Together, these qualities are called the ACID properties of
transactions. To understand why these properties are so important
to maintaining data integrity, consider the following example:
</para>
<para>
Suppose you create an application to manage bank accounts. The
application includes a method to transfer funds from one user to
another, and it looks something like this:
</para>
<programlisting format="linespecific">
</itemizedlist>
<para>
<indexterm>
<primary>
ACID
</primary>
<seealso>
transactions
</seealso>
</indexterm>
<indexterm>
<primary>
transactions
</primary>
<secondary>
ACID
</secondary>
</indexterm>
Together, these qualities are called the ACID properties of transactions. To
understand why these properties are so important to maintaining data integrity,
consider the following example:
</para>
<para>
Suppose you create an application to manage bank accounts. The application
includes a method to transfer funds from one user to another, and it looks
something like this:
</para>
<programlisting>
public void transferFunds (User from, User to, double amnt)
{
from.decrementAccount (amnt);
to.incrementAccount (amnt);
}
</programlisting>
<para>
Now suppose that user Alice wants to transfer 100 dollars to user Bob.
No problem; you simply invoke your
<methodname>transferFunds</methodname> method, supplying Alice in the
<literal>from</literal> parameter, Bob in the <literal>to</literal>
parameter, and <literal>100.00</literal> as the <literal>amnt</literal>.
The first line of the method is executed, and 100 dollars is subtracted
from Alice's account. But then, something goes wrong. An unexpected
exception occurs, or the hardware fails, and your method never
completes.
</para>
<para>
You are left with a situation in which the 100 dollars has simply
disappeared. Thanks to the first line of your method, it is no longer
in Alice's account, and yet it was never transferred to Bob's account
either. The datastore is in an inconsistent state.
</para>
<para>
The importance of transactions should now be clear. If the two lines
of the <methodname>transferFunds</methodname> method had been placed
together in a transaction, it would be impossible for only the
first line to succeed. Either the funds would be transferred
properly or they would not be transferred at all, and an exception
would be thrown. Money could never vanish into thin air, and the data
store could never get into an inconsistent state.
</para>
<section id="jpa_overview_trans_types">
<title>Transaction Types</title>
<para>
Now suppose that user Alice wants to transfer 100 dollars to user Bob. No
problem; you simply invoke your <methodname>transferFunds</methodname> method,
supplying Alice in the <literal>from</literal> parameter, Bob in the <literal>
to</literal> parameter, and <literal>100.00</literal> as the <literal>amnt
</literal>. The first line of the method is executed, and 100 dollars is
subtracted from Alice's account. But then, something goes wrong. An unexpected
exception occurs, or the hardware fails, and your method never completes.
</para>
<para>
You are left with a situation in which the 100 dollars has simply disappeared.
Thanks to the first line of your method, it is no longer in Alice's account, and
yet it was never transferred to Bob's account either. The datastore is in an
inconsistent state.
</para>
<para>
The importance of transactions should now be clear. If the two lines of the
<methodname>transferFunds</methodname> method had been placed together in a
transaction, it would be impossible for only the first line to succeed. Either
the funds would be transferred properly or they would not be transferred at all,
and an exception would be thrown. Money could never vanish into thin air, and
the data store could never get into an inconsistent state.
</para>
<section id="jpa_overview_trans_types">
<title>
Transaction Types
</title>
<indexterm zone="jpa_overview_trans_types">
<primary>transactions</primary>
<secondary>types</secondary>
<primary>
transactions
</primary>
<secondary>
types
</secondary>
</indexterm>
<para>
There are two major types of transactions: pessimistic transactions
and optimistic transactions. Each type has both advantages and
disadvantages.
</para>
<para><indexterm><primary>transactions</primary><secondary>pessimistic</secondary></indexterm><indexterm><primary>pessimistic transactions</primary><see>transactions, pessimistic</see></indexterm><indexterm><primary>deadlock</primary><seealso>transactions</seealso></indexterm>
Pessimistic transactions generally lock the datastore records they
act on, preventing other concurrent transactions from using the
same data. This avoids conflicts between transactions, but
consumes database resources. Additionally, locking records
can result in <emphasis>deadlock</emphasis>, a situation in which two
transactions are both waiting for the other to release its locks before
completing. The results of a deadlock are datastore-dependent;
usually one transaction is forcefully rolled back after some specified
timeout interval, and an exception is thrown.
</para>
<para><indexterm><primary>transactions</primary><secondary>datastore</secondary></indexterm><indexterm><primary>datastore transactions</primary><see>transactions, datastore</see></indexterm>
This document will often use the term <emphasis>datastore</emphasis>
transaction in place of <emphasis>pessimistic</emphasis> transaction.
This is to acknowledge that some datastores do not support pessimistic
semantics, and that the exact meaning of a non-optimistic JPA
transaction is dependent on the datastore. Most of the
time, a datastore transaction is equivalent to a pessimistic
transaction.
</para>
<para><indexterm><primary>transactions</primary><secondary>optimistic</secondary></indexterm><indexterm><primary>optimistic transactions</primary><see>transactions, optimistic</see></indexterm>
Optimistic transactions consume less resources than
pessimistic/datastore transactions, but only at the expense of
reliability. Because optimistic transactions do not lock datastore
records, two transactions might change the same persistent information
at the same time, and the conflict will not be detected until
the second transaction attempts to flush or commit. At this time, the
second transaction will realize that another transaction has
concurrently modified the same records (usually through a timestamp
or versioning system), and will throw an appropriate exception.
Note that optimistic transactions still maintain data integrity;
they are simply more likely to fail in heavily concurrent
situations.
</para>
There are two major types of transactions: pessimistic transactions and
optimistic transactions. Each type has both advantages and disadvantages.
</para>
<para>
Despite their drawbacks, optimistic transactions are the best choice
for most applications. They offer better performance, better
scalability, and lower risk of hanging due to deadlock.
</para>
<indexterm>
<primary>
transactions
</primary>
<secondary>
pessimistic
</secondary>
</indexterm>
<indexterm>
<primary>
pessimistic transactions
</primary>
<see>
transactions, pessimistic
</see>
</indexterm>
<indexterm>
<primary>
deadlock
</primary>
<seealso>
transactions
</seealso>
</indexterm>
Pessimistic transactions generally lock the datastore records they act on,
preventing other concurrent transactions from using the same data. This avoids
conflicts between transactions, but consumes database resources. Additionally,
locking records can result in <emphasis>deadlock</emphasis>, a situation in
which two transactions are both waiting for the other to release its locks
before completing. The results of a deadlock are datastore-dependent; usually
one transaction is forcefully rolled back after some specified timeout interval,
and an exception is thrown.
</para>
<para>
<indexterm>
<primary>
transactions
</primary>
<secondary>
datastore
</secondary>
</indexterm>
<indexterm>
<primary>
datastore transactions
</primary>
<see>
transactions, datastore
</see>
</indexterm>
This document will often use the term <emphasis>datastore</emphasis> transaction
in place of <emphasis>pessimistic</emphasis> transaction. This is to acknowledge
that some datastores do not support pessimistic semantics, and that the exact
meaning of a non-optimistic JPA transaction is dependent on the datastore. Most
of the time, a datastore transaction is equivalent to a pessimistic transaction.
</para>
<para>
<indexterm>
<primary>
transactions
</primary>
<secondary>
optimistic
</secondary>
</indexterm>
<indexterm>
<primary>
optimistic transactions
</primary>
<see>
transactions, optimistic
</see>
</indexterm>
Optimistic transactions consume less resources than pessimistic/datastore
transactions, but only at the expense of reliability. Because optimistic
transactions do not lock datastore records, two transactions might change the
same persistent information at the same time, and the conflict will not be
detected until the second transaction attempts to flush or commit. At this time,
the second transaction will realize that another transaction has concurrently
modified the same records (usually through a timestamp or versioning system),
and will throw an appropriate exception. Note that optimistic transactions still
maintain data integrity; they are simply more likely to fail in heavily
concurrent situations.
</para>
<para>
Despite their drawbacks, optimistic transactions are the best choice for most
applications. They offer better performance, better scalability, and lower risk
of hanging due to deadlock.
</para>
<note>
<para>
OpenJPA uses optimistic semantics by default, but supports both
optimistic and datastore transactions.
OpenJPA also offers advanced locking and versioning APIs for
fine-grained control over database resource allocation and object
versioning. See <xref linkend="ref_guide_locking"/> and
<xref linkend="ref_guide_lock_groups"/> of the Reference Guide for
details on locking. <xref linkend="jpa_overview_meta_version"/>
of this document covers standard object versioning.
<!-- ### EJBDOC : link additional strats when available from JPA -->
</para>
<para>
OpenJPA uses optimistic semantics by default, but supports both optimistic and
datastore transactions. OpenJPA also offers advanced locking and versioning APIs
for fine-grained control over database resource allocation and object
versioning. See <xref linkend="ref_guide_locking"></xref> and
<xref linkend="ref_guide_lock_groups"></xref> of the Reference Guide for details
on locking. <xref linkend="jpa_overview_meta_version"></xref>
of this document covers standard object versioning, while
<xref linkend="ref_guide_mapping_jpa"/> of the Reference Guide discusses
additional versioning strategies available in OpenJPA.
</para>
</note>
</section>
<section id="jpa_overview_trans_ejb3">
<title>The EntityTransaction Interface</title>
<indexterm zone="jpa_overview_trans_ejb3">
<primary>Transaction</primary>
<seealso>transactions</seealso>
</section>
<section id="jpa_overview_trans_local">
<title>
The EntityTransaction Interface
</title>
<indexterm zone="jpa_overview_trans_local">
<primary>
Transaction
</primary>
<seealso>
transactions
</seealso>
</indexterm>
<mediaobject>
<imageobject>
<!-- PNG image data, 193 x 157 (see README) -->
<imagedata fileref="img/jpa-transaction.png" width="129px"/>
</imageobject>
<imageobject>
<!-- PNG image data, 193 x 157 (see README) -->
<imagedata fileref="img/jpa-transaction.png" width="129px">
</imagedata>
</imageobject>
</mediaobject>
<para>
JPA integrates with your container's <emphasis>managed
</emphasis> transactions, allowing you to use the container's
declarative transaction demarcation and its Java Transaction API (JTA)
implementation for transaction management.
Outside of a container, though, you must demarcate transactions
manually through JPA. The <classname>
EntityTransaction</classname> interface controls unmanaged transactions
in JPA.
</para>
<programlisting format="linespecific">
JPA integrates with your container's <emphasis>managed</emphasis> transactions,
allowing you to use the container's declarative transaction demarcation and its
Java Transaction API (JTA) implementation for transaction management. Outside of
a container, though, you must demarcate transactions manually through JPA. The
<classname> EntityTransaction</classname> interface controls unmanaged
transactions in JPA.
</para>
<programlisting>
public void begin ();
public void commit ();
public void rollback ();
</programlisting>
<para><indexterm><primary>Transaction</primary><secondary>demarcation</secondary></indexterm><indexterm><primary>transactions</primary><secondary>demarcating</secondary></indexterm><indexterm><primary>Transaction</primary><secondary>begin</secondary></indexterm><indexterm><primary>Transaction</primary><secondary>commit</secondary></indexterm><indexterm><primary>Transaction</primary><secondary>rollback</secondary></indexterm>
The <methodname>begin</methodname>, <methodname>commit</methodname>,
and <methodname>rollback</methodname> methods demarcate transaction
boundaries. The methods should be self-explanatory:
<methodname>begin</methodname> starts a transaction,
<methodname>commit</methodname> attempts to commit the transaction's
changes to the datastore, and <methodname>rollback</methodname>
aborts the transaction, in which case the datastore is
"rolled back" to its previous state. JPA
implementations will automatically roll back transactions if any
exception is thrown during the commit process.
</para>
<para>
Unless you are using an extended persistence context, committing or
rolling back also ends the persistence context. All managed entites
will be detached from the <classname>EntityManager</classname>.
</para>
<programlisting format="linespecific">
<indexterm>
<primary>
Transaction
</primary>
<secondary>
demarcation
</secondary>
</indexterm>
<indexterm>
<primary>
transactions
</primary>
<secondary>
demarcating
</secondary>
</indexterm>
<indexterm>
<primary>
Transaction
</primary>
<secondary>
begin
</secondary>
</indexterm>
<indexterm>
<primary>
Transaction
</primary>
<secondary>
commit
</secondary>
</indexterm>
<indexterm>
<primary>
Transaction
</primary>
<secondary>
rollback
</secondary>
</indexterm>
The <methodname>begin</methodname>, <methodname>commit</methodname>, and
<methodname>rollback</methodname> methods demarcate transaction boundaries. The
methods should be self-explanatory: <methodname>begin</methodname> starts a
transaction, <methodname>commit</methodname> attempts to commit the
transaction's changes to the datastore, and <methodname>rollback</methodname>
aborts the transaction, in which case the datastore is "rolled back" to its
previous state. JPA implementations will automatically roll back transactions if
any exception is thrown during the commit process.
</para>
<para>
Unless you are using an extended persistence context, committing or rolling back
also ends the persistence context. All managed entites will be detached from the
<classname>EntityManager</classname>.
</para>
<programlisting>
public boolean isActive ();
</programlisting>
<para><indexterm><primary>Transaction</primary><secondary>isActive</secondary></indexterm>
Finally, the <methodname>isActive</methodname> method returns
<literal>true</literal> if the transaction is in progress
(<methodname>begin</methodname> has been called more recently than
<methodname>commit</methodname> or
<methodname>rollback</methodname>), and <literal>false</literal>
otherwise.
</para>
<para>
<indexterm>
<primary>
Transaction
</primary>
<secondary>
isActive
</secondary>
</indexterm>
Finally, the <methodname>isActive</methodname> method returns <literal>true
</literal> if the transaction is in progress ( <methodname>begin</methodname>
has been called more recently than <methodname>commit</methodname> or
<methodname>rollback</methodname> ), and <literal>false</literal> otherwise.
</para>
<example id="jpa_overview_trans_group">
<title>Grouping Operations with Transactions</title>
<programlisting format="linespecific">
<title>
Grouping Operations with Transactions
</title>
<programlisting>
public void transferFunds (EntityManager em, User from, User to, double amnt)
{
// note: it would be better practice to move the transaction demarcation
@ -230,5 +419,5 @@ public void transferFunds (EntityManager em, User from, User to, double amnt)
}
</programlisting>
</example>
</section>
</chapter>
</section>
</chapter>

1034
openjpa-project/src/doc/manual/jpa_overview_why.xml
View File

File diff suppressed because it is too large Load Diff

74
openjpa-project/src/doc/manual/jpa_resources.xml
View File

@ -1,39 +1,39 @@
<appendix id="jpa_resources">
<title>JPA Resources</title>
<appendix id="jpa_resources">
<title>
JPA Resources
</title>
<itemizedlist>
<listitem>
<para>
<ulink url="http://java.sun.com/aboutJava/communityprocess/jsr/jsr_220_dataobj.html">
EJB 3 JSR page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://java.sun.com/products/ejb">Sun EJB page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://java.sun.com/javaee/5/docs/api/index.html">Locally mirrored
javax.persistence Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="../../api/index.html">OpenJPA API Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="../apidocs/index.html">Full OpenJPA Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="Persistence.pdf">Locally mirrored JPA
specification</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://java.sun.com/aboutJava/communityprocess/jsr/jsr_220_dataobj.html">
EJB 3 JSR page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://java.sun.com/products/ejb">Sun EJB page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://java.sun.com/javaee/5/docs/api/index.html">Locally mirrored
javax.persistence Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="../../api/index.html">OpenJPA API Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="../apidocs/index.html">Full OpenJPA Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="Persistence.pdf">Locally mirrored JPA specification</ulink>
</para>
</listitem>
</itemizedlist>
</appendix>
</appendix>

2589
openjpa-project/src/doc/manual/jpa_tutorials.xml
View File

File diff suppressed because it is too large Load Diff

40
openjpa-project/src/doc/manual/manual.xml
View File

@ -36,17 +36,17 @@
<!ENTITY supported_databases.xml SYSTEM "supported_databases.xml">
]>
<book id="manual">
<bookinfo>
<title>OpenJPA Developers Guide</title>
</bookinfo>
<bookinfo>
<title>OpenJPA Developers Guide</title>
</bookinfo>
<part id="introduction">
<title>Introduction</title>
<part id="introduction">
<title>Introduction</title>
&openjpa_intro.xml;
</part>
</part>
<part id="jpa_overview">
<title>Java Persistence API</title>
<part id="jpa_overview">
<title>Java Persistence API</title>
&jpa_overview_intro.xml;
&jpa_overview_why.xml;
&jpa_overview_arch.xml;
@ -60,15 +60,15 @@
&jpa_overview_sqlquery.xml;
&jpa_overview_mapping.xml;
&jpa_overview_conclusion.xml;
</part>
</part>
<part id="tutorials">
<title>Tutorials</title>
<part id="tutorials">
<title>Tutorials</title>
&jpa_tutorials.xml;
</part>
</part>
<part id="ref_guide">
<title>OpenJPA <phrase>JPA</phrase> Reference Guide</title>
<part id="ref_guide">
<title>OpenJPA <phrase>JPA</phrase> Reference Guide</title>
&ref_guide_intro.xml;
&ref_guide_conf.xml;
&ref_guide_logging.xml;
@ -82,13 +82,13 @@
&ref_guide_remote.xml;
&ref_guide_integration.xml;
&ref_guide_optimization.xml;
</part>
</part>
<part id="samples_guide_part">
<title>OpenJPA <phrase>JPA</phrase> Samples</title>
<part id="samples_guide_part">
<title>OpenJPA <phrase>JPA</phrase> Samples</title>
&samples_guide.xml;
</part>
</part>
&jpa_resources.xml;
&supported_databases.xml;
&jpa_resources.xml;
&supported_databases.xml;
</book>

117
openjpa-project/src/doc/manual/openjpa_intro.xml
View File

@ -1,61 +1,62 @@
<chapter id="openjpa_intro">
<title>OpenJPA <phrase>JPA</phrase></title>
<indexterm zone="openjpa_intro">
<primary>OpenJPA <phrase>JPA</phrase></primary>
</indexterm>
<para>
OpenJPA is Apache's implementation of Sun's
<phrase>Java Persistence API (JPA) specification</phrase>
for the transparent persistence of Java objects.
This document provides an overview of
<phrase>the JPA standard</phrase>
and technical details on the use of OpenJPA <phrase>JPA</phrase>.
</para>
<para>
To quickly get started with JPA, you may want to begin at
<xref linkend="jpa_tutorial"/>.
If you would prefer to start with an introduction to the concepts of JPA,
begin with <xref linkend="jpa_overview_intro"/>.
</para>
<section id="openjpa_intro_about">
<title>About This Document</title>
<para>
This document is intended for OpenJPA users. It is divided into several
parts:
<chapter id="openjpa_intro">
<title>
OpenJPA
<phrase>
JPA
</phrase>
</title>
<indexterm zone="openjpa_intro">
<primary>
OpenJPA
<phrase>
JPA
</phrase>
</primary>
</indexterm>
<para>
OpenJPA is Apache's implementation of Sun's <phrase>Java Persistence API (JPA)
specification</phrase> for the transparent persistence of Java objects. This
document provides an overview of <phrase>the JPA standard</phrase> and technical
details on the use of OpenJPA.
</para>
<para>
To quickly get started with JPA, you may want to begin at
<xref linkend="jpa_tutorial"></xref>. If you would prefer to start with an
introduction to the concepts of JPA, begin with
<xref linkend="jpa_overview_intro"></xref>.
</para>
<section id="openjpa_intro_about">
<title>
About This Document
</title>
<para>
This document is intended for OpenJPA users. It is divided into several parts:
</para>
<itemizedlist>
<listitem>
<para>
The <link linkend="jpa_overview_intro">JPA Overview</link>
describes the fundamentals of JPA.
</para>
</listitem>
<listitem>
<para>
In the <link linkend="tutorials">OpenJPA <phrase>JPA</phrase>
Tutorials</link> you will develop simple persistent applications
using OpenJPA. Through the tutorials' hands-on approach, you
will become comfortable with the core tools and development
processes under OpenJPA <phrase>JPA</phrase>.
</para>
</listitem>
<listitem>
<para>
The <link linkend="ref_guide_intro">OpenJPA <phrase>JPA</phrase>
Reference Guide</link> contains detailed documentation on all
aspects of OpenJPA <phrase>JPA</phrase>. Browse through this guide to
familiarize yourself with the many advanced features and
customization opportunities OpenJPA provides. Later, you can use
the guide when you need details on a specific aspect of OpenJPA
<phrase>JPA</phrase>.
</para>
</listitem>
<listitem>
<para>
The <link linkend="jpa_overview_intro">JPA Overview</link> describes the
fundamentals of JPA.
</para>
</listitem>
<listitem>
<para>
In the <link linkend="tutorials">OpenJPA <phrase>JPA</phrase> Tutorials</link>
you will develop simple persistent applications using OpenJPA. Through the
tutorials' hands-on approach, you will become comfortable with the core tools
and development processes under OpenJPA <phrase>JPA</phrase>.
</para>
</listitem>
<listitem>
<para>
The <link linkend="ref_guide_intro">OpenJPA <phrase>JPA</phrase> Reference Guide
</link> contains detailed documentation on all aspects of OpenJPA <phrase>JPA
</phrase>. Browse through this guide to familiarize yourself with the many
advanced features and customization opportunities OpenJPA provides. Later, you
can use the guide when you need details on a specific aspect of OpenJPA <phrase>
JPA</phrase>.
</para>
</listitem>
</itemizedlist>
</section>
</chapter>
</section>
</chapter>

1821
openjpa-project/src/doc/manual/ref_guide_caching.xml
View File

File diff suppressed because it is too large Load Diff

6236
openjpa-project/src/doc/manual/ref_guide_conf.xml
View File

File diff suppressed because it is too large Load Diff

6600
openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
View File

File diff suppressed because it is too large Load Diff

350
openjpa-project/src/doc/manual/ref_guide_deploy.xml
View File

@ -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>
<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"></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>
<!-- ### EJBDOC -->
<para>
To be decided.
</para>
<title>
EntityManager Injection
</title>
<!-- ### -->
<para>
TBD
</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>
</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>
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>
<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>
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>
<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>

649
openjpa-project/src/doc/manual/ref_guide_integration.xml
View File

@ -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>
<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>
<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>
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">
<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>
&lt;mappingtool&gt;
&lt;fileset dir="${basedir}"&gt;
&lt;include name="**/model/*.java" /&gt;
@ -101,18 +103,19 @@
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">
</example>
<para>
It is also possible to specify a <literal>properties</literal> or <literal>
propertiesFile</literal> attribute on the <literal>config</literal> tag, which
will be used to locate a properties resource or file. The resource will be
loaded relative to the current CLASSPATH.
</para>
<example id="ref_guide_integration_props">
<title>
Using the Properties Attribute of the &lt;config&gt;
Tag
</title>
<programlisting>
&lt;mappingtool&gt;
&lt;fileset dir="${basedir}"&gt;
&lt;include name="**/model/*.java"/&gt;
@ -120,11 +123,13 @@
&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">
</example>
<example id="ref_guide_integration_propsfile">
<title>
Using the PropertiesFile Attribute of the &lt;config&gt;
Tag
</title>
<programlisting>
&lt;mappingtool&gt;
&lt;fileset dir="${basedir}"&gt;
&lt;include name="**/model/*.java"/&gt;
@ -132,25 +137,25 @@
&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">
</example>
<para>
Tasks also accept a nested <literal>classpath</literal> element, which you can
use in place of the default classpath. The <literal>classpath</literal> argument
behaves the same as it does for Ant's standard <literal>javac</literal> element.
It is sometimes the case that projects are compiled to a separate directory than
the source tree. If the target path for compiled classes is not included in the
project's classpath, then a <literal>classpath</literal> element that includes
the target class directory needs to be included so the enhancer and mapping tool
can locate the relevant classes.
</para>
<para>
Following is an example of using a <literal>classpath</literal> tag:
</para>
<example id="ref_guide_integration_conf_classpath">
<title>
Using the &lt;classpath&gt; Ant Tag
</title>
<programlisting>
&lt;openjpac&gt;
&lt;fileset dir="${basedir}/source"&gt;
&lt;include name="**/model/*.java" /&gt;
@ -162,60 +167,73 @@
&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">
</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 &lt;codeformat&gt; Ant Tag
</title>
<programlisting>
&lt;reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"&gt;
&lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
&lt;/reversemappingtool&gt;
</programlisting>
</example>
</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>
&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;!-- invoke enhancer on all .java files below the model directory --&gt;
&lt;openjpac&gt;
&lt;fileset dir="."&gt;
&lt;include name="**/model/*.java" /&gt;
@ -223,41 +241,52 @@
&lt;/openjpac&gt;
&lt;/target&gt;
</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>
&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;
@ -272,45 +301,53 @@
&lt;/appidtool&gt;
&lt;/target&gt;
</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>
&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;
@ -325,34 +362,45 @@
&lt;/mappingtool&gt;
&lt;/target&gt;
</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>
&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;
@ -366,33 +414,44 @@
&lt;/reversemappingtool&gt;
&lt;/target&gt;
</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>
&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;
@ -407,13 +466,17 @@
&lt;/schematool&gt;
&lt;/target&gt;
</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>

54
openjpa-project/src/doc/manual/ref_guide_intro.xml
View File

@ -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>

729
openjpa-project/src/doc/manual/ref_guide_logging.xml
View File

@ -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>.
<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>
</warning>
<section id="ref_guide_logging_channels">
<title>Logging Channels</title>
<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>
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">
<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>
&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>
</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>
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>
<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">
<title>
Standard OpenJPA Log Configuration
</title>
<programlisting>
&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">
<title>
Standard OpenJPA Log Configuration + All SQL Statements
</title>
<programlisting>
&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">
<title>
Logging to a File
</title>
<programlisting>
&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>
</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.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>
</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.SQL.level=INFO
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 @@ public class CustomLogFactory
}
};
}
}</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>

5725
openjpa-project/src/doc/manual/ref_guide_mapping.xml
View File

File diff suppressed because it is too large Load Diff

1903
openjpa-project/src/doc/manual/ref_guide_meta.xml
View File

File diff suppressed because it is too large Load Diff

1281
openjpa-project/src/doc/manual/ref_guide_optimization.xml
View File

File diff suppressed because it is too large Load Diff

4169
openjpa-project/src/doc/manual/ref_guide_pc.xml
View File

File diff suppressed because it is too large Load Diff

1190
openjpa-project/src/doc/manual/ref_guide_remote.xml
View File

File diff suppressed because it is too large Load Diff

2696
openjpa-project/src/doc/manual/ref_guide_runtime.xml
View File

File diff suppressed because it is too large Load Diff

278
openjpa-project/src/doc/manual/samples_guide.xml
View File

@ -1,137 +1,169 @@
<chapter id="samples_guide">
<title>OpenJPA Sample Code</title>
<para>
The OpenJPA distribution comes with a number of examples that
illustrate the usage of various features.
</para>
<chapter id="samples_guide">
<title>
OpenJPA Sample Code
</title>
<para>
The OpenJPA distribution comes with a number of examples that illustrate the
usage of various features.
</para>
<!--
This is information on the sample application. It will be included
in the documentation (see doc/openjpa/samples-guide.xml). It will also
automatically be converted into a README.txt file in this directory
in the "release.org.apache.openjpa.releasedocs" build target phase of the release.
This is information on the sample application. It will be included
in the documentation (see doc/openjpa/samples-guide.xml). It will also
automatically be converted into a README.txt file in this directory
in the "release.openjpa.releasedocs" build target phase of the release.
-->
<section id="samples_guide_interop">
<title>JDO - JPA Persistence Interoperability</title>
<para>This sample demonstrates how to combine JDO and JPA in a single
application. The <filename>MachineMain.java</filename> program uses both
<classname>EntityManager</classname>s and <classname>PersistenceManager</classname>s
in a single transaction including persist, delete and query operations.</para>
<para>The sample includes both annotated persistent classes as well as JDOR
metadata information. The application can switch to either system simply
by changing the bootstrap mechanism. Depending on which configuration
system you use, OpenJPA will read the corresponding metadata format. You can
override some or all of this behavior using OpenJPA's configuration options,
such as <link linkend="openjpa.MetaDataFactory">openjpa.MetaDataFactory</link>.</para>
<para>To use this sample, you should ensure that either a <filename>jdo.properties</filename>
or <filename>persistence.xml</filename> are in the <filename>META-INF</filename> directory
in your <envar>CLASSPATH</envar>. The rest of the files for this sample are located in the
<filename>samples/mixed</filename> directory of the OpenJPA installation. This tutorial requires JDK 5.
To run this tutorial:</para>
<section id="samples_guide_interop">
<title>
JDO - JPA Persistence Interoperability
</title>
<para>
This sample demonstrates how to combine JDO and JPA in a single application. The
<filename>MachineMain.java</filename> program uses both <classname>
EntityManager</classname>s and <classname>PersistenceManager</classname>s in a
single transaction including persist, delete and query operations.
</para>
<para>
The sample includes both annotated persistent classes as well as JDOR metadata
information. The application can switch to either system simply by changing the
bootstrap mechanism. Depending on which configuration system you use, OpenJPA
will read the corresponding metadata format. You can override some or all of
this behavior using OpenJPA's configuration options, such as
<link linkend="openjpa.MetaDataFactory">openjpa.MetaDataFactory</link>.
</para>
<para>
To use this sample, you should ensure that either a <filename>jdo.properties
</filename> or <filename>persistence.xml</filename> are in the <filename>
META-INF</filename> directory in your <envar>CLASSPATH</envar>. The rest of the
files for this sample are located in the <filename>samples/mixed</filename>
directory of the OpenJPA installation. This tutorial requires JDK 5. To run this
tutorial:
</para>
<itemizedlist>
<listitem>
<para>Ensure that your environment is set properly as described in the
README and that your current path is in the mixed sample directory.</para>
</listitem>
<listitem>
<para>
You may want to edit <literal>ConnectionURL</literal> to point to an absolute
URL (e.g. <filename>C:/openjpa/mixed-sample-db</filename>) if using a file-based database like
<literal>HSQL</literal>.</para>
</listitem>
<listitem>
<para>Include the list of persistent classes in your configuration file. For
JPA, you will want to add the following lines to
<filename>persistence.xml</filename> before the <literal>&lt;property&gt;</literal> lines:
</para>
<programlisting format="linespecific">
<listitem>
<para>
Ensure that your environment is set properly as described in the README and that
your current path is in the mixed sample directory.
</para>
</listitem>
<listitem>
<para>
You may want to edit <literal>ConnectionURL</literal> to point to an absolute
URL (e.g. <filename>C:/openjpa/mixed-sample-db</filename>) if using a
file-based database like <literal>HSQL</literal>.
</para>
</listitem>
<listitem>
<para>
Include the list of persistent classes in your configuration file. For JPA, you
will want to add the following lines to <filename>persistence.xml</filename>
before the <literal>&lt;property&gt;</literal> lines:
</para>
<programlisting>
&lt;class&gt;samples.mixed.Machine&lt;/class&gt;
&lt;class&gt;samples.mixed.Crane&lt;/class&gt;
&lt;class&gt;samples.mixed.Bulldozer&lt;/class&gt;
&lt;class&gt;samples.mixed.Operator&lt;/class&gt;
</programlisting>
<para>
If you are using JDO, point the metadata factory at the <filename>.jdo</filename>
resource containing your persistent classes:
</para>
<programlisting format="linespecific">
<para>
If you are using JDO, point the metadata factory at the <filename>.jdo
</filename> resource containing your persistent classes:
</para>
<programlisting>
openjpa.MetaDataFactory: Resources=samples/mixed/package.jdo
</programlisting>
</listitem>
<listitem>
<para>Compile the classes:
</para>
<para>
<userinput>javac *.java</userinput>
</para>
</listitem>
<listitem>
<para>You should then proceed to pass in the configuration file you are using
to the enhancer:
</para>
<para>
<userinput>openjpac -p persistence.xml Machine.java Crane.java Bulldozer.java Operator.java</userinput>
</para>
<para>
or
</para>
<para>
<userinput>jdoc -p jdo.properties Machine.java Crane.java Bulldozer.java Operator.java</userinput>
</para>
</listitem>
<listitem>
<para>Similarly, you should pass in the same argument to <literal>mappingtool</literal>:
</para>
<para>
<userinput>mappingtool -p persistence.xml -a buildSchema Machine.java Crane.java Bulldozer.java Operator.java</userinput>
</para>
<para>
or
</para>
<para>
<userinput>mappingtool -p jdo.properties -a buildSchema Machine.java Crane.java Bulldozer.java Operator.java</userinput>
</para>
</listitem>
<listitem>
<para>You can now run the sample application. The first argument is
which operation you want the program to run. The second argument tells
the application which bootstrap system to use:
</para>
<para>
<userinput>java samples.mixed.MachineMain &lt;create | delete&gt; &lt;jdo | jpa&gt;</userinput>
</para>
</listitem>
</listitem>
<listitem>
<para>
Compile the classes:
</para>
<para>
<userinput>javac *.java</userinput>
</para>
</listitem>
<listitem>
<para>
You should then proceed to pass in the configuration file you are using to the
enhancer:
</para>
<para>
<userinput>openjpac -p persistence.xml Machine.java Crane.java Bulldozer.java
Operator.java</userinput>
</para>
<para>
or
</para>
<para>
<userinput>jdoc -p jdo.properties Machine.java Crane.java Bulldozer.java
Operator.java</userinput>
</para>
</listitem>
<listitem>
<para>
Similarly, you should pass in the same argument to <literal>mappingtool
</literal>:
</para>
<para>
<userinput>mappingtool -p persistence.xml -a buildSchema Machine.java
Crane.java Bulldozer.java Operator.java</userinput>
</para>
<para>
or
</para>
<para>
<userinput>mappingtool -p jdo.properties -a buildSchema Machine.java Crane.java
Bulldozer.java Operator.java</userinput>
</para>
</listitem>
<listitem>
<para>
You can now run the sample application. The first argument is which operation
you want the program to run. The second argument tells the application which
bootstrap system to use:
</para>
<para>
<userinput>java samples.mixed.MachineMain &lt;create | delete&gt; &lt;jdo |
jpa&gt;</userinput>
</para>
</listitem>
</itemizedlist>
</section>
<section id="samples_guide_ejbdiv">
<title>JPA</title>
</section>
<section id="samples_guide_jpadiv">
<title>
JPA
</title>
<!--
This is information on the sample application. It will be included
in the documentation (see doc/openjpa/samples-guide.xml). It will also
automatically be converted into a README.txt file in this directory
in the "release.jdo.releasedocs" build target phase of the release.
This is information on the sample application. It will be included
in the documentation (see doc/openjpa/samples-guide.xml). It will also
automatically be converted into a README.txt file in this directory
in the "release.jdo.releasedocs" build target phase of the release.
-->
<section id="samples_guide_model_humres_ejb">
<title>Sample Human Resources Model</title>
<para>The files for this sample are located in the <filename>samples/persistence/models/humres</filename>
directory of the OpenJPA installation. This sample demonstrates the mapping of
an example "Human Resources" schema. The following concepts are illustrated
in this sample:</para>
<itemizedlist>
<listitem>
<para>Value Mappings</para>
</listitem>
<listitem>
<para>One to One Mappings</para>
</listitem>
<listitem>
<para>One to Many Mappings (with and without inverses)</para>
</listitem>
</itemizedlist>
<section id="samples_guide_model_humres_jpa">
<title>
Sample Human Resources Model
</title>
<para>
The files for this sample are located in the <filename>
samples/persistence/models/humres</filename> directory of the OpenJPA
installation. This sample demonstrates the mapping of an example "Human
Resources" schema. The following concepts are illustrated in this sample:
</para>
<itemizedlist>
<listitem>
<para>
Value Mappings
</para>
</listitem>
<listitem>
<para>
One to One Mappings
</para>
</listitem>
<listitem>
<para>
One to Many Mappings (with and without inverses)
</para>
</listitem>
</itemizedlist>
</section>
</section>
</chapter>
</section>
</chapter>

1349
openjpa-project/src/doc/manual/supported_databases.xml
View File

File diff suppressed because it is too large Load Diff