Author: mtylenda
Date: Sat Apr 9 19:02:33 2011
New Revision: 1090649
URL: http://svn.apache.org/viewvc?rev=1090649&view=rev
Log:
OPENJPA-1932: Documentation update: remove Java 5 references, improve
formatting and wording, point out that getSupportedProperties is an OpenJPA
extension (no longer in the JPA 2.0 spec), remove link to criteria API draft
(criteria API is in the final 2.0 spec).
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_criteria.xml
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml
openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml
openjpa/trunk/openjpa-project/src/doc/manual/properties_info.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_criteria.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_criteria.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_criteria.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_criteria.xml Sat
Apr 9 19:02:33 2011
@@ -38,7 +38,7 @@
</see>
</indexterm>
<para>
- JPA 2.0 Specification introduces a new API to define queries dynamically
+ JPA 2.0 specification introduces a new API to define queries dynamically
via construction of an object-based
<classname>javax.persistence.CriteriaQuery</classname> instance, rather
than string-based approach used in JPQL (Java Persistence Query Language).
@@ -116,7 +116,7 @@ Root<Order> order = customer.join(
<section>
<title>Executing a CriteriaQuery</title>
<para>
- A CriteriaQuery is executed in a similar fashion of a string-based JPQL
+ A CriteriaQuery is executed in a similar fashion to a string-based JPQL
query via the EntityManager and Query interfaces.
<programlisting>
EntityManager em = ...
@@ -130,12 +130,6 @@ List result = query.getResultList();
</para>
<para>
- The JPA 2.0 Specification on Criteria API can be found at
- <ulink
url="http://jcp.org/aboutJava/communityprocess/pr/jsr317/index.html";>
- public draft</ulink>.
- </para>
- <para>
-
<ulink
url="http://www.ibm.com/developerworks/java/library/j-typesafejpa/";>A
developerworks article</ulink>
explains details and further usage of Criteria API and its OpenJPA
extensions.
</para>
@@ -145,18 +139,18 @@ List result = query.getResultList();
<title>Extension to Criteria API</title>
<para>
Criteria API has provided an alternative means to string-based JPQL to
- execute a query. However, JPA 2.0 Specification has not explicitly
specified
+ execute a query. However, JPA 2.0 specification has not explicitly
specified
any equivalence between a dynamically constructed CriteriaQuery and
a JPQL string. OpenJPA provides a mechanism to convert a CriteriaQuery to
an equivalent JPQL query string via the extended OpenJPACriteriaQuery API.
<programlisting>
- public interface OpenJPACriteriaQuery extends CriteriaQuery {
- /**
- * Gets equivalent JPQL String for the given CriteriaQuery.
- */
- public String toCQL();
- }
- </programlisting>
+public interface OpenJPACriteriaQuery extends CriteriaQuery {
+ /**
+ * Gets equivalent JPQL String for the given CriteriaQuery.
+ */
+ public String toCQL();
+}
+ </programlisting>
</para>
</section>
@@ -197,7 +191,7 @@ The Annotation Processor recognizes the
-Aopenjpa.naming=class name : fully-qualified name of a class
implementing
<code>org.apache.openjpa.meta.MetaDataFactory</code> that
determines
the name of a meta-class given the name of the original persistent Java entity
class. Defaults to
-<code>org.apache.openjpa.persistence.PersistenceMetaDataFactory</code> which
appends a underscore character
+<code>org.apache.openjpa.persistence.PersistenceMetaDataFactory</code> which
appends an underscore character
(<code>_</code>) to the original Java class name.
</para>
</listitem>
@@ -205,7 +199,7 @@ the name of a meta-class given the name
<para>
-Aopenjpa.header=<url> : A url whose content will appear
as comment header to the generated file(s).
Recognizes special value <code>ASL</code> for Apache Source
License header as comment.
- By default, adds a OpenJPA proprietary text as comment block.
+ By default, adds an OpenJPA proprietary text as comment block.
</para>
</listitem>
</itemizedlist>
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml Sat
Apr 9 19:02:33 2011
@@ -446,7 +446,7 @@ public PersistenceUnitUtil getPersistenc
</programlisting>
<para>
The <classname>EntityManagerFactory</classname> method
-<methodname>getPersistenceUnitUtil</methodname> to provide access to a
+<methodname>getPersistenceUnitUtil</methodname> provides access to a
<classname>PersistenceUnitUtil</classname> utility.
<classname>PersistenceUnitUtil</classname>
can be used to obtain the identity of a managed object and determine the load
state of the entity or one of its attributes. If the object is not
@@ -461,7 +461,7 @@ if (puUtil.getIdentifier(deptEntity) ==
throw new Exception("Identity is not valid.");
}
if (!puUtil.isLoaded(deptEntity, "employees")) {
- throw new Exception("Employees not loaded.")
+ throw new Exception("Employees not loaded.");
}
</programlisting>
</para>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml Sat Apr
9 19:02:33 2011
@@ -65,7 +65,7 @@ simply reflecting on the persistent clas
annotations
</primary>
</indexterm>
-Persistence metadata is specified using either the Java 5 annotations defined
in
+Persistence metadata is specified using either the Java annotations defined in
the <literal>javax.persistence</literal> package, XML mapping files, or a
mixture of both. In the latter case, XML declarations override conflicting
annotations. If you choose to use XML metadata, the XML files must be available
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml Sat Apr
9 19:02:33 2011
@@ -882,7 +882,7 @@ To specify an isolation level, specify a
Other Fetchplan Hints
</title>
<para>
-Any property of an OpenJPA FetchPlan can be changed using a hint by using a
name of the form "openjpa.FetchPlan."<property name>.Valid
property names include :
+Any property of an OpenJPA FetchPlan can be changed using a hint by using a
name of the form "openjpa.FetchPlan."<property name>. Valid
property names include:
<classname>MaxFetchDepth</classname>, <classname>FetchBatchSize</classname>,
<classname>LockTimeOut</classname>, <classname>EagerFetchMode</classname>,
<classname>SubclassFetchMode</classname> and <classname>Isolation</classname>.
</para>
</section>
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml
Sat Apr 9 19:02:33 2011
@@ -50,8 +50,8 @@
The OpenJPAEntityManagerFactory interface getProperties()
method was changed to return a Map instead of a
Properties object. This change was made in order to
- support the getProperties() method defined in the 2.0
- JPA specification.
+ support the getProperties() method defined in the
+ JPA 2.0 specification.
</para>
</section>
<section id="migration_detach_behavior">
Modified: openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml Sat Apr 9
19:02:33 2011
@@ -77,7 +77,7 @@ The openjpa-all aggregate JAR includes s
Apache Geronimo project (JMS 1.1, JTA 1.1 and JPA 2.0 spec APIs)
</para></listitem>
<listitem><para>
- JCP JSR-317 JPA 2.0 Schemas
+ JCP JSR-317 JPA 2.0 schemas
</para></listitem>
<listitem><para>
SERP project
Modified: openjpa/trunk/openjpa-project/src/doc/manual/properties_info.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/properties_info.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/properties_info.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/properties_info.xml Sat Apr 9
19:02:33 2011
@@ -19,7 +19,7 @@
-->
<para>
There are two sets of properties that may be specified: those that
-are specific to openjpa and those that have been defined by the JPA
+are specific to OpenJPA and those that have been defined by the JPA
specification. In some cases, two properties may be equivalent, but
have different keys. For example, <emphasis>openjpa.LockTimeout
</emphasis> and <emphasis>javax.persistence.lock.timeout</emphasis>
@@ -28,24 +28,35 @@ are two different keys for the same prop
<para>
There are two methods that can be used to retrieve information related to
properties:
+<programlisting>
+public Map<String,Object> getProperties();
+public Set<String> getSupportedProperties();
+</programlisting>
<itemizedlist>
<listitem>
<para>
- getProperties() - This method provides a list of
current
+ <methodname>getProperties</methodname> - Provides a
list of current
properties. If a property has more than one key, the key
that will be returned is the one that was used when the
property was set. If the property was not explicitly
- set, the key defined by JPA specification will be
returned
+ set, the key defined by the JPA specification will be
returned
with the default value.
</para>
</listitem>
<listitem>
<para>
- getSupportedProperties() - This method returns a set of
- property keys. See the javadoc in the latest JPA
- specification for the definition of the set. If a
property
+ <methodname>getSupportedProperties</methodname> -
Returns a set of
+ supported property keys. This includes keys defined by
the JPA
+ specification as well as keys specific to OpenJPA.
+ If a property
has more than one key, all possible keys will be
returned.
</para>
</listitem>
</itemizedlist>
</para>
+<note>
+ <para>
+ The <methodname>getSupportedProperties</methodname> method is
an OpenJPA
+ extension to the JPA specification.
+ </para>
+</note>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml Sat Apr 9
19:02:33 2011
@@ -303,7 +303,7 @@ java org.apache.openjpa.enhance.Applicat
<para>
Because OpenJPA is a highly customizable environment, many configuration
properties relate to the creation and configuration of system plugins. Plugin
-properties have a syntax very similar to that of Java 5 annotations. They allow
+properties have a syntax very similar to that of Java annotations. They allow
you to specify both what class to use for the plugin and how to configure the
public fields or bean properties of the instantiated plugin instance. The
easiest way to describe the plugin syntax is by example:
@@ -396,8 +396,8 @@ default JDBC store.
</para>
<para>
-Few of the properties recognized by OpenJPA have been standardized in JPA 2.0
-Specification using equivalent names. These properties can be specified either
+A few of the properties recognized by OpenJPA have been standardized in JPA
2.0
+specification using equivalent names. These properties can be specified either
by the JPA standard key or equivalent OpenJPA key. Specifying the same key once
as JPA standard key and again as equivalent OpenJPA key in the same
configuration,
however, is not allowed. The following table lists these standard JPA
properties
@@ -4234,7 +4234,7 @@ implementation is
<para>
The default behavior of certain OpenJPA API methods can evolve to align with
the behaviors
defined in JPA specification. To maintain backward compatibility, OpenJPA
allows configuration
-options such that while the default behavior changes to align with current JPA
Specification, the
+options such that while the default behavior changes to align with current JPA
specification, the
previous behaviors can always be emulated.
</para>
<para>
@@ -4253,13 +4253,13 @@ JPA 2.0 <literal>detach()</literal> sema
before detach.
</para>
<para>
-A user application running with OpenJPA that is compliant to a specific
version of JPA of specification,
-the older behavior can be emulated by configuring OpenJPA Compatibility
options.
+A user application running with OpenJPA that is compliant to a specific
version of JPA specification
+can emulate the older behavior by configuring OpenJPA compatibility options.
For example,
<literal>openjpa.Compatibility=FlushBeforeDetach=false,CopyOnDetach=true</literal>
-will emulate the older behavior of detach even when running with OpenJPA that
are
-compliant to JPA 2.0 Specification. The configuration can also be set to a
different version of the specification.
+will emulate the older behavior of detach even when running with OpenJPA that
is
+compliant to JPA 2.0 specification. The configuration can also be set to a
different version of the specification.
For example, <literal>openjpa.Specification="JPA 1.0"</literal> configuration
setting will emulate
-default OpenJPA behavior as it were for JPA Specification version 1.0. Setting
via
+default OpenJPA behavior as it were for JPA specification version 1.0. Setting
<literal>openjpa.Specification</literal> is a shorthand for more fine-grained
control available via
<literal>openjpa.Compatibility</literal>.
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml Sat Apr
9 19:02:33 2011
@@ -3909,7 +3909,7 @@ the operation will fail.
Delimited Identifiers Support
</title>
<para>
-OpenJPA provides support for delimited identifiers as defined in the 2.0 JPA
specification.
+OpenJPA provides support for delimited identifiers as defined in the JPA 2.0
specification.
Identifiers can either be automatically delimited or individually manually
delimited. To have OpenJPA automatically delimit identifiers, add the
<literal><delimited-identifiers/></literal> tag
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml Sat Apr
9 19:02:33 2011
@@ -278,7 +278,7 @@ For example, when loading an application
following will be sent to the <literal>openjpa.Runtime</literal> channel:
</para>
<programlisting>
-2107 INFO [main] openjpa.Runtime - Starting OpenJPA 0.9.7
+2107 INFO [main] openjpa.Runtime - Starting OpenJPA 2.2.0
</programlisting>
<para>
The default logging system accepts the following parameters:
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml?rev=1090649&r1=1090648&r2=1090649&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml Sat Apr 9
19:02:33 2011
@@ -2286,7 +2286,7 @@ default fetch group or in any other acti
fields that will be eagerly loaded from the database.
</para>
<para>
-JPA <classname>FetchPlan</classname> methods:
+OpenJPA <classname>FetchPlan</classname> methods:
</para>
<programlisting>
public FetchPlan addField(String field);
@@ -2318,7 +2318,6 @@ publisher</literal>.
</para>
<para>
- <title>Extended Path Lookup</title>
To include the fields defined in a super class by the subclass or to
distinguish
between fields that are defined in <emphasis>both</emphasis> super- and
subclass,
set <literal>setExtendedPathLookup(boolean)</literal> on <literal>FetchPlan
