You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [1/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Author: awhite
Date: Thu Aug 24 13:41:12 2006
New Revision: 434517
URL: http://svn.apache.org/viewvc?rev=434517&view=rev
Log:
Formatted our documentation XML files.
Modified:
incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java
incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/PersistenceAwareClass.java
incubator/openjpa/trunk/openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/XMLMetaDataParser.java
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_mapping.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_persistence.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_trans.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_why.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_intro.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml
Modified: incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java (original)
+++ incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java Thu Aug 24 13:41:12 2006
@@ -83,11 +83,11 @@
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 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 @@
// 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 @@
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.
@@ -888,25 +852,6 @@
}
/**
- * 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 @@
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 @@
_registered.clear();
_factory.clear();
_aliases.clear();
+ _pawares.clear();
}
/**
@@ -1560,18 +1557,6 @@
(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.
*/
Modified: incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/PersistenceAwareClass.java
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/PersistenceAwareClass.java?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/PersistenceAwareClass.java (original)
+++ incubator/openjpa/trunk/openjpa-kernel/src/main/java/org/apache/openjpa/meta/PersistenceAwareClass.java Thu Aug 24 13:41:12 2006
@@ -5,9 +5,13 @@
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 @@
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 @@
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 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());
}
Modified: incubator/openjpa/trunk/openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/XMLMetaDataParser.java
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/XMLMetaDataParser.java?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/XMLMetaDataParser.java (original)
+++ incubator/openjpa/trunk/openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/XMLMetaDataParser.java Thu Aug 24 13:41:12 2006
@@ -338,9 +338,8 @@
_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 {
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml Thu Aug 24 13:41:12 2006
@@ -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.
- </para>
- </note>
- <itemizedlist>
+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>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">
+ <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>
+ <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 @@
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 @@
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>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml Thu Aug 24 13:41:12 2006
@@ -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>