openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From awh...@apache.org
Subject 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/
Date Thu, 24 Aug 2006 20:41:14 GMT
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>



Mime
View raw message