You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-commits@db.apache.org by mb...@apache.org on 2006/03/29 00:14:17 UTC
svn commit: r389615 [1/3] - in /db/jdo/trunk/api20/src/java/javax/jdo: ./
datastore/ identity/ listener/ spi/
Author: mbo
Date: Tue Mar 28 14:14:14 2006
New Revision: 389615
URL: http://svn.apache.org/viewcvs?rev=389615&view=rev
Log:
JDO-353: fix issues reported by checkstyle
Modified:
db/jdo/trunk/api20/src/java/javax/jdo/JDODetachedFieldAccessException.java
db/jdo/trunk/api20/src/java/javax/jdo/JDOHelper.java
db/jdo/trunk/api20/src/java/javax/jdo/JDOOptimisticVerificationException.java
db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java
db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java
db/jdo/trunk/api20/src/java/javax/jdo/Query.java
db/jdo/trunk/api20/src/java/javax/jdo/Transaction.java
db/jdo/trunk/api20/src/java/javax/jdo/datastore/JDOConnection.java
db/jdo/trunk/api20/src/java/javax/jdo/datastore/Sequence.java
db/jdo/trunk/api20/src/java/javax/jdo/identity/ObjectIdentity.java
db/jdo/trunk/api20/src/java/javax/jdo/identity/StringIdentity.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/AttachCallback.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/AttachLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/ClearLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/CreateLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/DeleteLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/DetachCallback.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/DetachLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/DirtyLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/InstanceLifecycleEvent.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/InstanceLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/LoadLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/listener/StoreLifecycleListener.java
db/jdo/trunk/api20/src/java/javax/jdo/spi/I18NHelper.java
db/jdo/trunk/api20/src/java/javax/jdo/spi/JDOImplHelper.java
db/jdo/trunk/api20/src/java/javax/jdo/spi/JDOPermission.java
db/jdo/trunk/api20/src/java/javax/jdo/spi/PersistenceCapable.java
db/jdo/trunk/api20/src/java/javax/jdo/spi/StateInterrogation.java
db/jdo/trunk/api20/src/java/javax/jdo/spi/StateManager.java
Modified: db/jdo/trunk/api20/src/java/javax/jdo/JDODetachedFieldAccessException.java
URL: http://svn.apache.org/viewcvs/db/jdo/trunk/api20/src/java/javax/jdo/JDODetachedFieldAccessException.java?rev=389615&r1=389614&r2=389615&view=diff
==============================================================================
--- db/jdo/trunk/api20/src/java/javax/jdo/JDODetachedFieldAccessException.java (original)
+++ db/jdo/trunk/api20/src/java/javax/jdo/JDODetachedFieldAccessException.java Tue Mar 28 14:14:14 2006
@@ -30,7 +30,8 @@
public class JDODetachedFieldAccessException extends JDOUserException {
/**
- * Constructs a new <code>JDODetachedFieldAccessException</code> without a detail message.
+ * Constructs a new <code>JDODetachedFieldAccessException</code> without a
+ * detail message.
* @since 2.0
*/
public JDODetachedFieldAccessException() {
@@ -38,7 +39,8 @@
/**
- * Constructs a new <code>JDODetachedFieldAccessException</code> with the specified detail message.
+ * Constructs a new <code>JDODetachedFieldAccessException</code> with the
+ * specified detail message.
* @param msg the detail message.
* @since 2.0
*/
Modified: db/jdo/trunk/api20/src/java/javax/jdo/JDOHelper.java
URL: http://svn.apache.org/viewcvs/db/jdo/trunk/api20/src/java/javax/jdo/JDOHelper.java?rev=389615&r1=389614&r2=389615&view=diff
==============================================================================
--- db/jdo/trunk/api20/src/java/javax/jdo/JDOHelper.java (original)
+++ db/jdo/trunk/api20/src/java/javax/jdo/JDOHelper.java Tue Mar 28 14:14:14 2006
@@ -45,7 +45,6 @@
import javax.jdo.spi.JDOImplHelper.StateInterrogationObjectReturn;
import javax.jdo.spi.PersistenceCapable;
import javax.jdo.spi.StateInterrogation;
-import javax.jdo.spi.StateManager; // for javadoc
import javax.naming.Context;
import javax.naming.InitialContext;
@@ -62,8 +61,8 @@
* various methods.
* <P>This helper class defines static methods that allow a JDO-aware
* application to examine the runtime state of instances. For example,
- * an application can discover whether the instance is persistent, transactional,
- * dirty, new, deleted, or detached; and to get its associated
+ * an application can discover whether the instance is persistent,
+ * transactional, dirty, new, deleted, or detached; and to get its associated
* <code>PersistenceManager</code> if it has one.
*
* @version 2.0
@@ -72,7 +71,8 @@
/** The Internationalization message helper.
*/
- private final static I18NHelper msg = I18NHelper.getInstance ("javax.jdo.Bundle"); //NOI18N
+ private final static I18NHelper msg =
+ I18NHelper.getInstance ("javax.jdo.Bundle"); //NOI18N
/** The JDOImplHelper instance used for handling non-binary-compatible
* implementations.
@@ -191,10 +191,12 @@
* <code>PersistenceManager</code>.
*
* <P>Transient non-transactional instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>null</code>.
+ * that do not implement <code>PersistenceCapable</code> return
+ * <code>null</code>.
* @see PersistenceCapable#jdoGetPersistenceManager()
* @param pc the <code>PersistenceCapable</code> instance.
- * @return the <code>PersistenceManager</code> associated with the parameter instance.
+ * @return the <code>PersistenceManager</code> associated with the parameter
+ * instance.
*/
public static PersistenceManager getPersistenceManager(Object pc) {
if (pc instanceof PersistenceCapable) {
@@ -206,9 +208,9 @@
}
/** Explicitly mark the parameter instance and field dirty.
- * Normally, <code>PersistenceCapable</code> classes are able to detect changes made
- * to their fields. However, if a reference to an array is given to a
- * method outside the class, and the array is modified, then the
+ * Normally, <code>PersistenceCapable</code> classes are able to detect
+ * changes made to their fields. However, if a reference to an array is
+ * given to a method outside the class, and the array is modified, then the
* persistent instance is not aware of the change. This API allows the
* application to notify the instance that a change was made to a field.
*
@@ -226,32 +228,35 @@
}
}
- /** Return a copy of the JDO identity associated with the parameter instance.
+ /** Return a copy of the JDO identity associated with the parameter
+ * instance.
*
- * <P>Persistent instances of <code>PersistenceCapable</code> classes have a JDO identity
- * managed by the <code>PersistenceManager</code>. This method returns a copy of the
- * ObjectId that represents the JDO identity.
+ * <P>Persistent instances of <code>PersistenceCapable</code> classes have a
+ * JDO identity managed by the <code>PersistenceManager</code>. This method
+ * returns a copy of the ObjectId that represents the JDO identity.
*
- * <P>Transient instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>null</code>.
+ * <P>Transient instances and instances of classes that do not implement
+ * <code>PersistenceCapable</code> return <code>null</code>.
*
* <P>The ObjectId may be serialized
- * and later restored, and used with a <code>PersistenceManager</code> from the same JDO
- * implementation to locate a persistent instance with the same data store
- * identity.
- *
- * <P>If the JDO identity is managed by the application, then the ObjectId may
- * be used with a <code>PersistenceManager</code> from any JDO implementation that supports
- * the <code>PersistenceCapable</code> class.
- *
- * <P>If the JDO identity is not managed by the application or the data store,
- * then the ObjectId returned is only valid within the current transaction.
+ * and later restored, and used with a <code>PersistenceManager</code> from
+ * the same JDO implementation to locate a persistent instance with the same
+ * data store identity.
+ *
+ * <P>If the JDO identity is managed by the application, then the ObjectId
+ * may be used with a <code>PersistenceManager</code> from any JDO
+ * implementation that supports the <code>PersistenceCapable</code> class.
+ *
+ * <P>If the JDO identity is not managed by the application or the data
+ * store, then the ObjectId returned is only valid within the current
+ * transaction.
*<P>
* @see PersistenceManager#getObjectId(Object pc)
* @see PersistenceCapable#jdoGetObjectId()
* @see PersistenceManager#getObjectById(Object oid, boolean validate)
* @param pc the PersistenceCapable instance.
- * @return a copy of the ObjectId of the parameter instance as of the beginning of the transaction.
+ * @return a copy of the ObjectId of the parameter instance as of the
+ * beginning of the transaction.
*/
public static Object getObjectId(Object pc) {
if (pc instanceof PersistenceCapable) {
@@ -301,18 +306,21 @@
return result;
}
- /** Return a copy of the JDO identity associated with the parameter instance.
+ /** Return a copy of the JDO identity associated with the parameter
+ * instance.
*
* @see PersistenceCapable#jdoGetTransactionalObjectId()
* @see PersistenceManager#getObjectById(Object oid, boolean validate)
* @param pc the <code>PersistenceCapable</code> instance.
- * @return a copy of the ObjectId of the parameter instance as modified in this transaction.
+ * @return a copy of the ObjectId of the parameter instance as modified in
+ * this transaction.
*/
public static Object getTransactionalObjectId(Object pc) {
if (pc instanceof PersistenceCapable) {
return ((PersistenceCapable)pc).jdoGetTransactionalObjectId();
} else {
- return implHelper.nonBinaryCompatibleGet(pc, getTransactionalObjectId);
+ return implHelper.nonBinaryCompatibleGet(
+ pc, getTransactionalObjectId);
}
}
@@ -334,13 +342,15 @@
* Instances that have been modified, deleted, or newly
* made persistent in the current transaction return <code>true</code>.
*
- *<P>Transient instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
+ *<P>Transient instances and instances of classes that do not implement
+ * <code>PersistenceCapable</code> return <code>false</code>.
*<P>
- * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName)
+ * @see javax.jdo.spi.StateManager#makeDirty(PersistenceCapable pc,
+ * String fieldName)
* @see PersistenceCapable#jdoIsDirty()
* @param pc the <code>PersistenceCapable</code> instance.
- * @return <code>true</code> if the parameter instance has been modified in the current transaction.
+ * @return <code>true</code> if the parameter instance has been modified in
+ * the current transaction.
*/
public static boolean isDirty(Object pc) {
if (pc instanceof PersistenceCapable) {
@@ -355,8 +365,8 @@
* Instances whose state is associated with the current transaction
* return true.
*
- *<P>Transient instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
+ *<P>Transient instances and instances of classes that do not implement
+ * <code>PersistenceCapable</code> return <code>false</code>.
* @see PersistenceCapable#jdoIsTransactional()
* @param pc the <code>PersistenceCapable</code> instance.
* @return <code>true</code> if the parameter instance is transactional.
@@ -374,8 +384,8 @@
* Instances that represent persistent objects in the data store
* return <code>true</code>.
*
- *<P>Transient instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
+ *<P>Transient instances and instances of classes that do not implement
+ * <code>PersistenceCapable</code> return <code>false</code>.
*<P>
* @see PersistenceManager#makePersistent(Object pc)
* @see PersistenceCapable#jdoIsPersistent()
@@ -395,8 +405,8 @@
* Instances that have been made persistent in the current transaction
* return <code>true</code>.
*
- *<P>Transient instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
+ *<P>Transient instances and instances of classes that do not implement
+ * <code>PersistenceCapable</code> return <code>false</code>.
*<P>
* @see PersistenceManager#makePersistent(Object pc)
* @see PersistenceCapable#jdoIsNew()
@@ -414,10 +424,11 @@
/** Tests whether the parameter instance has been deleted.
*
- * Instances that have been deleted in the current transaction return <code>true</code>.
+ * Instances that have been deleted in the current transaction return
+ * <code>true</code>.
*
- *<P>Transient instances and instances of classes
- * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
+ *<P>Transient instances and instances of classes that do not implement
+ * <code>PersistenceCapable</code> return <code>false</code>.
*<P>
* @see PersistenceManager#deletePersistent(Object pc)
* @see PersistenceCapable#jdoIsDeleted()
@@ -453,11 +464,12 @@
}
}
- /** Get a <code>PersistenceManagerFactory</code> based on a <code>Properties</code> instance, using
- * the current thread's context class loader to locate the
+ /** Get a <code>PersistenceManagerFactory</code> based on a <code>Properties</code>
+ * instance, using the current thread's context class loader to locate the
* <code>PersistenceManagerFactory</code> class.
* @return the <code>PersistenceManagerFactory</code>.
- * @param props a <code>Properties</code> instance with properties of the <code>PersistenceManagerFactory</code>.
+ * @param props a <code>Properties</code> instance with properties of the
+ * <code>PersistenceManagerFactory</code>.
* @see #getPersistenceManagerFactory(Map,ClassLoader)
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
@@ -467,8 +479,8 @@
}
/**
- * Get a <code>PersistenceManagerFactory</code> based on a <code>Properties</code>
- * instance and a class loader.
+ * Get a <code>PersistenceManagerFactory</code> based on a
+ * <code>Properties</code> instance and a class loader.
* The following are standard key values:
* <BR><code>"javax.jdo.PersistenceManagerFactoryClass"
* <BR>"javax.jdo.option.Optimistic",
@@ -491,45 +503,60 @@
* recognized by the implementation must be ignored. Key values that are
* recognized but not supported by an implementation must result in a
* <code>JDOFatalUserException</code> thrown by the method.
- * <P>The returned <code>PersistenceManagerFactory</code> is not configurable (the
- * <code>set<I>XXX</I></code> methods will throw an exception).
+ * <P>The returned <code>PersistenceManagerFactory</code> is not
+ * configurable (the <code>set<I>XXX</I></code> methods will throw an
+ * exception).
* <P>JDO implementations might manage a map of instantiated
- * <code>PersistenceManagerFactory</code> instances based on specified property key
- * values, and return a previously instantiated <code>PersistenceManagerFactory</code>
- * instance. In this case, the properties of the returned
- * instance must exactly match the requested properties.
+ * <code>PersistenceManagerFactory</code> instances based on specified
+ * property key values, and return a previously instantiated
+ * <code>PersistenceManagerFactory</code> instance. In this case, the
+ * properties of the returned instance must exactly match the requested
+ * properties.
* @return the <code>PersistenceManagerFactory</code>.
- * @param props a <code>Properties</code> instance with properties of the <code>PersistenceManagerFactory</code>.
- * @param cl the class loader to use to load the <code>PersistenceManagerFactory</code> class
+ * @param props a <code>Properties</code> instance with properties of the
+ * <code>PersistenceManagerFactory</code>.
+ * @param cl the class loader to use to load the
+ * <code>PersistenceManagerFactory</code> class
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
(Map props, ClassLoader cl) {
- String pmfClassName = (String) props.get ("javax.jdo.PersistenceManagerFactoryClass"); //NOI18N
+ String pmfClassName = (String) props.get (
+ "javax.jdo.PersistenceManagerFactoryClass"); //NOI18N
if (pmfClassName == null) {
- throw new JDOFatalUserException (msg.msg("EXC_GetPMFNoClassNameProperty")); // NOI18N
+ throw new JDOFatalUserException (msg.msg(
+ "EXC_GetPMFNoClassNameProperty")); // NOI18N
}
try {
Class pmfClass = cl.loadClass (pmfClassName);
- Method pmfMethod = pmfClass.getMethod("getPersistenceManagerFactory", //NOI18N
+ Method pmfMethod = pmfClass.getMethod(
+ "getPersistenceManagerFactory", //NOI18N
new Class[] {Map.class});
- return (PersistenceManagerFactory) pmfMethod.invoke (null, new Object[] {props});
+ return (PersistenceManagerFactory) pmfMethod.invoke (
+ null, new Object[] {props});
} catch (ClassNotFoundException cnfe) {
- throw new JDOFatalUserException (msg.msg("EXC_GetPMFClassNotFound", pmfClassName), cnfe); //NOI18N
+ throw new JDOFatalUserException (msg.msg(
+ "EXC_GetPMFClassNotFound", pmfClassName), cnfe); //NOI18N
} catch (IllegalAccessException iae) {
- throw new JDOFatalUserException (msg.msg("EXC_GetPMFIllegalAccess", pmfClassName), iae); //NOI18N
+ throw new JDOFatalUserException (msg.msg(
+ "EXC_GetPMFIllegalAccess", pmfClassName), iae); //NOI18N
} catch (NoSuchMethodException nsme) {
- throw new JDOFatalInternalException (msg.msg("EXC_GetPMFNoSuchMethod"), nsme); //NOI18N
+ throw new JDOFatalInternalException (msg.msg(
+ "EXC_GetPMFNoSuchMethod"), nsme); //NOI18N
} catch (InvocationTargetException ite) {
Throwable nested = ite.getTargetException();
if (nested instanceof JDOException) {
throw (JDOException)nested;
- } else throw new JDOFatalInternalException (msg.msg("EXC_GetPMFUnexpectedException"), ite); //NOI18N
+ } else throw new JDOFatalInternalException (msg.msg(
+ "EXC_GetPMFUnexpectedException"), ite); //NOI18N
} catch (NullPointerException e) {
- throw new JDOFatalInternalException (msg.msg("EXC_GetPMFNullPointerException", pmfClassName), e); //NOI18N
+ throw new JDOFatalInternalException (msg.msg(
+ "EXC_GetPMFNullPointerException", pmfClassName), e); //NOI18N
} catch (ClassCastException e) {
- throw new JDOFatalInternalException (msg.msg("EXC_GetPMFClassCastException", pmfClassName), e); //NOI18N
+ throw new JDOFatalInternalException (msg.msg(
+ "EXC_GetPMFClassCastException", pmfClassName), e); //NOI18N
} catch (Exception e) {
- throw new JDOFatalInternalException (msg.msg("EXC_GetPMFUnexpectedException"), e); //NOI18N
+ throw new JDOFatalInternalException (msg.msg(
+ "EXC_GetPMFUnexpectedException"), e); //NOI18N
}
}
@@ -561,7 +588,8 @@
* be wrapped in a {@link JDOFatalUserException}.
* @since 2.0
* @param propsResource the resource containing the Properties
- * @param loader the class loader to use to load both the propsResource and the <code>PersistenceManagerFactory</code> class
+ * @param loader the class loader to use to load both the propsResource and
+ * the <code>PersistenceManagerFactory</code> class
* @return the PersistenceManagerFactory
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
@@ -580,30 +608,34 @@
* @since 2.0
* @param propsResource the resource containing the Properties
* @param propsLoader the class loader to use to load the propsResource
- * @param pmfLoader the class loader to use to load the <code>PersistenceManagerFactory</code> class
+ * @param pmfLoader the class loader to use to load the
+ * <code>PersistenceManagerFactory</code> class
* @return the PersistenceManagerFactory
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
(String propsResource, ClassLoader propsLoader, ClassLoader pmfLoader) {
if (propsResource == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullResource")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullResource")); //NOI18N
if (propsLoader == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullPropsLoader")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullPropsLoader")); //NOI18N
if (pmfLoader == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullPMFLoader")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullPMFLoader")); //NOI18N
Properties props = new Properties ();
InputStream in = null;
try {
in = propsLoader.getResourceAsStream (propsResource);
if (in == null)
- throw new JDOFatalUserException
- (msg.msg ("EXC_GetPMFNoResource", propsResource, propsLoader)); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNoResource", propsResource, propsLoader)); //NOI18N
props.load (in);
} catch (IOException ioe) {
- throw new JDOFatalUserException
- (msg.msg ("EXC_GetPMFIOExceptionRsrc", propsResource), ioe); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFIOExceptionRsrc", propsResource), ioe); //NOI18N
}
finally {
if (in != null)
@@ -644,26 +676,29 @@
* loading will be wrapped in a {@link JDOFatalUserException}.
* @since 2.0
* @param propsFile the file containing the Properties
- * @param loader the class loader to use to load the <code>PersistenceManagerFactory</code> class
+ * @param loader the class loader to use to load the
+ * <code>PersistenceManagerFactory</code> class
* @return the PersistenceManagerFactory
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
(File propsFile, ClassLoader loader) {
if (propsFile == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullFile")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullFile")); //NOI18N
if (loader == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullLoader")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullLoader")); //NOI18N
Properties props = new Properties ();
InputStream in = null;
try {
in = new FileInputStream (propsFile);
props.load (in);
} catch (FileNotFoundException fnfe) {
- throw new JDOFatalUserException
- (msg.msg ("EXC_GetPMFNoFile", propsFile, loader), fnfe); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNoFile", propsFile, loader), fnfe); //NOI18N
} catch (IOException ioe) {
- throw new JDOFatalUserException
- (msg.msg ("EXC_GetPMFIOExceptionFile", propsFile), ioe); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFIOExceptionFile", propsFile), ioe); //NOI18N
} finally {
if (in != null)
try {
@@ -683,8 +718,10 @@
* with <code>Thread.currentThread().getContextClassLoader()</code> as
* the <code>loader</code> argument.
* @since 2.0
- * @param jndiLocation the JNDI location containing the PersistenceManagerFactory
- * @param context the context in which to find the named PersistenceManagerFactory
+ * @param jndiLocation the JNDI location containing the
+ * PersistenceManagerFactory
+ * @param context the context in which to find the named
+ * PersistenceManagerFactory
* @return the PersistenceManagerFactory
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
@@ -703,17 +740,22 @@
* <code>loader</code>. Any <code>NamingException</code>s thrown
* will be wrapped in a {@link JDOFatalUserException}.
* @since 2.0
- * @param jndiLocation the JNDI location containing the PersistenceManagerFactory
- * @param context the context in which to find the named PersistenceManagerFactory
- * @param loader the class loader to use to load the <code>PersistenceManagerFactory</code> class
+ * @param jndiLocation the JNDI location containing the
+ * PersistenceManagerFactory
+ * @param context the context in which to find the named
+ * PersistenceManagerFactory
+ * @param loader the class loader to use to load the
+ * <code>PersistenceManagerFactory</code> class
* @return the PersistenceManagerFactory
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
(String jndiLocation, Context context, ClassLoader loader) {
if (jndiLocation == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullJndiLoc")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullJndiLoc")); //NOI18N
if (loader == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullLoader")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullLoader")); //NOI18N
try {
if (context == null)
context = new InitialContext ();
@@ -722,8 +764,8 @@
return (PersistenceManagerFactory) PortableRemoteObject.narrow
(o, PersistenceManagerFactory.class);
} catch (NamingException ne) {
- throw new JDOFatalUserException
- (msg.msg ("EXC_GetPMFNamingException", jndiLocation, loader), ne); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNamingException", jndiLocation, loader), ne); //NOI18N
}
}
@@ -754,15 +796,18 @@
* loading will be wrapped in a {@link JDOFatalUserException}.
* @since 2.0
* @param stream the stream containing the Properties
- * @param loader the class loader to use to load the <code>PersistenceManagerFactory</code> class
+ * @param loader the class loader to use to load the
+ * <code>PersistenceManagerFactory</code> class
* @return the PersistenceManagerFactory
*/
public static PersistenceManagerFactory getPersistenceManagerFactory
(InputStream stream, ClassLoader loader) {
if (stream == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullStream")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullStream")); //NOI18N
if (loader == null)
- throw new JDOFatalUserException (msg.msg ("EXC_GetPMFNullLoader")); //NOI18N
+ throw new JDOFatalUserException (msg.msg (
+ "EXC_GetPMFNullLoader")); //NOI18N
Properties props = new Properties ();
try {
props.load (stream);
Modified: db/jdo/trunk/api20/src/java/javax/jdo/JDOOptimisticVerificationException.java
URL: http://svn.apache.org/viewcvs/db/jdo/trunk/api20/src/java/javax/jdo/JDOOptimisticVerificationException.java?rev=389615&r1=389614&r2=389615&view=diff
==============================================================================
--- db/jdo/trunk/api20/src/java/javax/jdo/JDOOptimisticVerificationException.java (original)
+++ db/jdo/trunk/api20/src/java/javax/jdo/JDOOptimisticVerificationException.java Tue Mar 28 14:14:14 2006
@@ -31,22 +31,24 @@
public class JDOOptimisticVerificationException extends JDOFatalDataStoreException {
/**
- * Constructs a new <code>JDOOptimisticVerificationException</code> without a detail message.
+ * Constructs a new <code>JDOOptimisticVerificationException</code> without a
+ * detail message.
*/
public JDOOptimisticVerificationException() {
}
/**
- * Constructs a new <code>JDOOptimisticVerificationException</code> with the specified detail message.
+ * Constructs a new <code>JDOOptimisticVerificationException</code> with the
+ * specified detail message.
* @param msg the detail message.
*/
public JDOOptimisticVerificationException(String msg) {
super(msg);
}
- /** Constructs a new <code>JDOOptimisticVerificationException</code> with the specified detail message
- * and failed object.
+ /** Constructs a new <code>JDOOptimisticVerificationException</code> with the
+ * specified detail message and failed object.
* @param msg the detail message.
* @param failed the failed object.
*/
@@ -55,8 +57,8 @@
}
/**
- * Constructs a new <code>JDOOptimisticVerificationException</code> with the specified
- * detail message and nested <code>Throwable</code>s.
+ * Constructs a new <code>JDOOptimisticVerificationException</code> with the
+ * specified detail message and nested <code>Throwable</code>s.
* @param msg the detail message.
* @param nested the nested <code>Throwable[]</code>.
*/
Modified: db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java
URL: http://svn.apache.org/viewcvs/db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java?rev=389615&r1=389614&r2=389615&view=diff
==============================================================================
--- db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java (original)
+++ db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java Tue Mar 28 14:14:14 2006
@@ -28,10 +28,10 @@
import javax.jdo.listener.InstanceLifecycleListener;
-/** <code>PersistenceManager</code> is the primary interface for JDO-aware application
- * components. It is the factory for <code>Query</code> and <code>Transaction</code> instances,
- * and contains methods to manage the life cycle of <code>PersistenceCapable</code>
- * instances.
+/** <code>PersistenceManager</code> is the primary interface for JDO-aware
+ * application components. It is the factory for <code>Query</code> and
+ * <code>Transaction</code> instances, and contains methods to manage the
+ * life cycle of <code>PersistenceCapable</code> instances.
*
* <P>A <code>PersistenceManager</code> is obtained from the
* {@link PersistenceManagerFactory}
@@ -41,40 +41,44 @@
public interface PersistenceManager {
/**
- * A <code>PersistenceManager</code> instance can be used until it is closed.
- * @return <code>true</code> if this <code>PersistenceManager</code> has been closed.
+ * A <code>PersistenceManager</code> instance can be used until it is
+ * closed.
+ * @return <code>true</code> if this <code>PersistenceManager</code> has
+ * been closed.
* @see #close()
*/
boolean isClosed ();
- /** Close this <code>PersistenceManager</code> so that no further requests may be
- * made on it. A <code>PersistenceManager</code> instance can be used
- * only until it is closed.
- *
- * <P>Closing a <code>PersistenceManager</code> might release it to the pool of available
- * <code>PersistenceManager</code>s, or might be garbage collected, at the option of
- * the JDO implementation. Before being used again to satisfy a
- * <code>getPersistenceManager()</code> request, the default values for options will
- * be restored to their values as specified in the <code>PersistenceManagerFactory</code>.
+ /** Close this <code>PersistenceManager</code> so that no further requests
+ * may be made on it. A <code>PersistenceManager</code> instance can be
+ * used only until it is closed.
+ *
+ * <P>Closing a <code>PersistenceManager</code> might release it to the pool
+ * of available <code>PersistenceManager</code>s, or might be garbage
+ * collected, at the option of the JDO implementation. Before being used
+ * again to satisfy a <code>getPersistenceManager()</code> request, the
+ * default values for options will be restored to their values as specified
+ * in the <code>PersistenceManagerFactory</code>.
*
* <P>This method closes the <code>PersistenceManager</code>.
*/
void close ();
- /** Return the <code>Transaction</code> instance associated with a <code>PersistenceManager</code>.
- * There is one <code>Transaction</code> instance associated with each <code>PersistenceManager</code>
- * instance. The <code>Transaction</code> instance supports options as well as
+ /** Return the <code>Transaction</code> instance associated with a
+ * <code>PersistenceManager</code>. There is one <code>Transaction</code>
+ * instance associated with each <code>PersistenceManager</code> instance.
+ * The <code>Transaction</code> instance supports options as well as
* transaction completion requests.
* @return the <code>Transaction</code> associated with this
* <code>PersistenceManager</code>.
*/
Transaction currentTransaction();
- /** Mark an instance as no longer needed in the cache.
- * Eviction is normally done automatically by the <code>PersistenceManager</code>
- * at transaction completion. This method allows the application to
- * explicitly provide a hint to the <code>PersistenceManager</code> that the instance
- * is no longer needed in the cache.
+ /** Mark an instance as no longer needed in the cache. Eviction is normally
+ * done automatically by the <code>PersistenceManager</code> at transaction
+ * completion. This method allows the application to explicitly provide a
+ * hint to the <code>PersistenceManager</code> that the instance is no
+ * longer needed in the cache.
* @param pc the instance to evict from the cache.
*/
void evict (Object pc);
@@ -85,9 +89,11 @@
*/
void evictAll (Object[] pcs);
- /** Mark a <code>Collection</code> of instances as no longer needed in the cache.
+ /** Mark a <code>Collection</code> of instances as no longer needed in the
+ * cache.
* @see #evict(Object pc)
- * @param pcs the <code>Collection</code> of instances to evict from the cache.
+ * @param pcs the <code>Collection</code> of instances to evict from the
+ * cache.
*/
void evictAll (Collection pcs);
@@ -105,7 +111,8 @@
* might not match the state in the data store. This method is used to
* reload the state of the instance from the data store so that a subsequent
* commit is more likely to succeed.
- * <P>Outside a transaction, this method will refresh nontransactional state.
+ * <P>Outside a transaction, this method will refresh nontransactional
+ * state.
* @param pc the instance to refresh.
*/
void refresh (Object pc);
@@ -117,7 +124,8 @@
*/
void refreshAll (Object[] pcs);
- /** Refresh the state of a <code>Collection</code> of instances from the data store.
+ /** Refresh the state of a <code>Collection</code> of instances from the
+ * data store.
*
* @see #refresh(Object pc)
* @param pcs the <code>Collection</code> of instances to refresh.
@@ -144,14 +152,17 @@
*/
Query newQuery ();
- /** Create a new <code>Query</code> using elements from another <code>Query</code>.
- * The other <code>Query</code> must have been created by the same JDO implementation.
- * It might be active
- * in a different <code>PersistenceManager</code> or might have been serialized and restored.
- * <P>All of the settings of the other <code>Query</code> are copied to this <code>Query</code>,
- * except for the candidate <code>Collection</code> or <code>Extent</code>.
+ /** Create a new <code>Query</code> using elements from another
+ * <code>Query</code>. The other <code>Query</code> must have been created
+ * by the same JDO implementation. It might be active in a different
+ * <code>PersistenceManager</code> or might have been serialized and
+ * restored.
+ * <P>All of the settings of the other <code>Query</code> are copied to this
+ * <code>Query</code>, except for the candidate <code>Collection</code> or
+ * <code>Extent</code>.
* @return the new <code>Query</code>
- * @param compiled another <code>Query</code> from the same JDO implementation
+ * @param compiled another <code>Query</code> from the same JDO
+ * implementation
*/
Query newQuery (Object compiled);
@@ -170,7 +181,8 @@
*/
Query newQuery (String language, Object query);
- /** Create a new <code>Query</code> specifying the <code>Class</code> of the candidate instances.
+ /** Create a new <code>Query</code> specifying the <code>Class</code> of the
+ * candidate instances.
* @param cls the <code>Class</code> of the candidate instances
* @return the new <code>Query</code>
*/
@@ -199,7 +211,8 @@
*/
Query newQuery (Class cls, String filter);
- /** Create a new <code>Query</code> with the <code>Class</code> of the candidate instances,
+ /** Create a new <code>Query</code> with the <code>Class</code> of the
+ * candidate instances,
* candidate <code>Collection</code>, and filter.
* @param cls the <code>Class</code> of candidate instances
* @param cln the <code>Collection</code> of candidate instances
@@ -227,12 +240,13 @@
*/
Query newNamedQuery (Class cls, String queryName);
- /** The <code>PersistenceManager</code> manages a collection of instances in the data
- * store based on the class of the instances. This method returns an
- * <code>Extent</code> of instances in the data store that might be iterated or
- * given to a <code>Query</code>. The <code>Extent</code> itself might not reference any
- * instances, but only hold the class name and an
- * indicator as to whether subclasses are included in the <code>Extent</code>.
+ /** The <code>PersistenceManager</code> manages a collection of instances in
+ * the data store based on the class of the instances. This method returns
+ * an <code>Extent</code> of instances in the data store that might be
+ * iterated or given to a <code>Query</code>. The <code>Extent</code>
+ * itself might not reference any instances, but only hold the class name
+ * and an indicator as to whether subclasses are included in the
+ * <code>Extent</code>.
* <P>Note that the <code>Extent</code> might be very large.
* @param persistenceCapableClass <code>Class</code> of instances
* @param subclasses whether to include instances of subclasses
@@ -253,18 +267,20 @@
* managed by this <code>PersistenceManager</code>.
* The <code>getObjectById</code> method attempts
* to find an instance in the cache with the specified JDO identity.
- * The <code>oid</code> parameter object might have been returned by an earlier call
- * to <code>getObjectId</code> or <code>getTransactionalObjectId</code>,
- * or might have been constructed by the application.
- * <P>If the <code>PersistenceManager</code> is unable to resolve the <code>oid</code> parameter
- * to an ObjectId instance, then it throws a <code>JDOUserException</code>.
- * <P>If the <code>validate</code> flag is <code>false</code>, and there is already an instance in the
- * cache with the same JDO identity as the <code>oid</code> parameter, then this method
- * returns it. There is no change made to the state of the returned
- * instance.
+ * The <code>oid</code> parameter object might have been returned by an
+ * earlier call to <code>getObjectId</code> or
+ * <code>getTransactionalObjectId</code>, or might have been constructed by
+ * the application.
+ * <P>If the <code>PersistenceManager</code> is unable to resolve the
+ * <code>oid</code> parameter to an ObjectId instance, then it throws a
+ * <code>JDOUserException</code>.
+ * <P>If the <code>validate</code> flag is <code>false</code>, and there is
+ * already an instance in the cache with the same JDO identity as the
+ * <code>oid</code> parameter, then this method returns it. There is no
+ * change made to the state of the returned instance.
* <P>If there is not an instance already in the cache with the same JDO
- * identity as the <code>oid</code> parameter, then this method creates an instance
- * with the specified JDO identity and returns it. If there is no
+ * identity as the <code>oid</code> parameter, then this method creates an
+ * instance with the specified JDO identity and returns it. If there is no
* transaction in progress, the returned instance will be hollow or
* persistent-nontransactional, at the choice of the implementation.
* <P>If there is a transaction in progress, the returned instance will
@@ -272,10 +288,10 @@
* choice of the implementation.
* <P>It is an implementation decision whether to access the data store,
* if required to determine the exact class. This will be the case of
- * inheritance, where multiple <code>PersistenceCapable</code> classes share the
- * same ObjectId class.
- * <P>If the validate flag is <code>false</code>, and the instance does not exist in
- * the data store, then this method might not fail. It is an
+ * inheritance, where multiple <code>PersistenceCapable</code> classes share
+ * the same ObjectId class.
+ * <P>If the validate flag is <code>false</code>, and the instance does not
+ * exist in the data store, then this method might not fail. It is an
* implementation choice whether to fail immediately with a
* <code>JDOObjectNotFoundException</code>. But a subsequent access
* of the fields of the
@@ -284,19 +300,19 @@
* exist at that time. Further, if a relationship is established to this
* instance, then the transaction in which the association was made will
* fail.
- * <P>If the <code>validate</code> flag is <code>true</code>, and there is already a transactional
- * instance in the cache with the same JDO identity as the <code>oid</code> parameter,
- * then this method returns it. There is no change made to the state of
- * the returned instance.
- * <P>If there is an instance already in the cache with the same JDO
- * identity as the <code>oid</code> parameter, but the instance is not transactional,
- * then it must be verified in the data store. If the instance does not
- * exist in the datastore, then a <code>JDOObjectNotFoundException</code>
- * is thrown.
+ * <P>If the <code>validate</code> flag is <code>true</code>, and there is
+ * already a transactional instance in the cache with the same JDO identity
+ * as the <code>oid</code> parameter, then this method returns it. There is
+ * no change made to the state of the returned instance.
+ * <P>If there is an instance already in the cache with the same JDO
+ * identity as the <code>oid</code> parameter, but the instance is not
+ * transactional, then it must be verified in the data store. If the
+ * instance does not exist in the datastore, then a
+ * <code>JDOObjectNotFoundException</code> is thrown.
* <P>If there is not an instance already in the cache with the same JDO
- * identity as the <code>oid</code> parameter, then this method creates an instance
- * with the specified JDO identity, verifies that it exists in the data
- * store, and returns it. If there is no transaction in progress, the
+ * identity as the <code>oid</code> parameter, then this method creates an
+ * instance with the specified JDO identity, verifies that it exists in the
+ * data store, and returns it. If there is no transaction in progress, the
* returned instance will be hollow or persistent-nontransactional,
* at the choice of the implementation.
* <P>If there is a data store transaction in progress, the returned
@@ -305,7 +321,8 @@
* instance will be persistent-nontransactional.
* @see #getObjectId(Object pc)
* @see #getTransactionalObjectId(Object pc)
- * @return the <code>PersistenceCapable</code> instance with the specified ObjectId
+ * @return the <code>PersistenceCapable</code> instance with the specified
+ * ObjectId
* @param oid an ObjectId
* @param validate if the existence of the instance is to be validated
*/
@@ -333,31 +350,32 @@
* the instance. The ObjectId is a copy (clone) of the internal state
* of the instance, and changing it does not affect the JDO identity of
* the instance.
- * <P>The <code>getObjectId</code> method returns an ObjectId instance that represents
- * the object identity of the specified JDO instance. The identity is
- * guaranteed to be unique only in the context of the JDO
- * <code>PersistenceManager</code> that created the identity, and only for two types
- * of JDO Identity: those that are managed by the application, and
+ * <P>The <code>getObjectId</code> method returns an ObjectId instance that
+ * represents the object identity of the specified JDO instance. The
+ * identity is guaranteed to be unique only in the context of the JDO
+ * <code>PersistenceManager</code> that created the identity, and only for
+ * two types of JDO Identity: those that are managed by the application, and
* those that are managed by the data store.
* <P>If the object identity is being changed in the transaction, by the
* application modifying one or more of the application key fields,
* then this method returns the identity as of the beginning of the
- * transaction. The value returned by <code>getObjectId</code> will be different
- * following <code>afterCompletion</code> processing for successful transactions.
- * <P>Within a transaction, the ObjectId returned will compare equal to
- * the ObjectId returned by only one among all JDO instances associated
- * with the <code>PersistenceManager</code> regardless of the type of ObjectId.
+ * transaction. The value returned by <code>getObjectId</code> will be
+ * different following <code>afterCompletion</code> processing for
+ * successful transactions. <P>Within a transaction, the ObjectId returned
+ * will compare equal to the ObjectId returned by only one among all JDO
+ * instances associated with the <code>PersistenceManager</code> regardless
+ * of the type of ObjectId.
* <P>The ObjectId does not necessarily contain any internal state of the
* instance, nor is it necessarily an instance of the class used to
* manage identity internally. Therefore, if the application makes a
* change to the ObjectId instance returned by this method, there is
* no effect on the instance from which the ObjectId was obtained.
* <P>The <code>getObjectById</code> method can be used between instances of
- * <code>PersistenceManager</code> of different JDO vendors only for instances of
- * persistence capable classes using application-managed (primary key)
- * JDO identity. If it is used for instances of classes using datastore
- * identity, the method might succeed, but there are no guarantees that
- * the parameter and return instances are related in any way.
+ * <code>PersistenceManager</code> of different JDO vendors only for
+ * instances of persistence capable classes using application-managed
+ * (primary key) JDO identity. If it is used for instances of classes using
+ * datastore identity, the method might succeed, but there are no guarantees
+ * that the parameter and return instances are related in any way.
* @see #getTransactionalObjectId(Object pc)
* @see #getObjectById(Object oid, boolean validate)
* @param pc the <code>PersistenceCapable</code> instance
@@ -521,12 +539,12 @@
/** Delete the persistent instance from the data store.
* This method must be called in an active transaction.
* The data store object will be removed at commit.
- * Unlike <code>makePersistent</code>, which makes the closure of the instance persistent,
- * the closure of the instance is not deleted from the data store.
- * This method has no effect if the instance is already deleted in the
- * current transaction.
- * This method throws <code>JDOUserException</code> if the instance is transient or
- * is managed by another <code>PersistenceManager</code>.
+ * Unlike <code>makePersistent</code>, which makes the closure of the
+ * instance persistent, the closure of the instance is not deleted from the
+ * data store. This method has no effect if the instance is already deleted
+ * in the current transaction.
+ * This method throws <code>JDOUserException</code> if the instance is
+ * transient or is managed by another <code>PersistenceManager</code>.
*
* @param pc a persistent instance
*/
@@ -548,25 +566,28 @@
* <code>PersistenceManager</code>.
*
* <P>The instance loses its JDO identity and it is no longer associated
- * with any <code>PersistenceManager</code>. The state of fields is preserved unchanged.
+ * with any <code>PersistenceManager</code>. The state of fields is
+ * preserved unchanged.
* @param pc the instance to make transient.
*/
void makeTransient (Object pc);
- /** Make an array of instances transient, removing them from management by this
- * <code>PersistenceManager</code>.
+ /** Make an array of instances transient, removing them from management by
+ * this <code>PersistenceManager</code>.
*
- * <P>The instances lose their JDO identity and they are no longer associated
- * with any <code>PersistenceManager</code>. The state of fields is preserved unchanged.
+ * <P>The instances lose their JDO identity and they are no longer
+ * associated with any <code>PersistenceManager</code>. The state of fields
+ * is preserved unchanged.
* @param pcs the instances to make transient.
*/
void makeTransientAll (Object[] pcs);
- /** Make a <code>Collection</code> of instances transient, removing them from
- * management by this <code>PersistenceManager</code>.
+ /** Make a <code>Collection</code> of instances transient, removing them
+ * from management by this <code>PersistenceManager</code>.
*
- * <P>The instances lose their JDO identity and they are no longer associated
- * with any <code>PersistenceManager</code>. The state of fields is preserved unchanged.
+ * <P>The instances lose their JDO identity and they are no longer
+ * associated with any <code>PersistenceManager</code>. The state of fields
+ * is preserved unchanged.
* @param pcs the instances to make transient.
*/
void makeTransientAll (Collection pcs);
@@ -639,16 +660,16 @@
/** Make an instance subject to transactional boundaries.
*
* <P>Transient instances normally do not observe transaction boundaries.
- * This method makes transient instances sensitive to transaction completion.
- * If an instance is modified in a transaction, and the transaction rolls back,
- * the state of the instance is restored to the state before the first change
- * in the transaction.
+ * This method makes transient instances sensitive to transaction
+ * completion. If an instance is modified in a transaction, and the
+ * transaction rolls back, the state of the instance is restored to the
+ * state before the first change in the transaction.
*
* <P>For persistent instances read in optimistic transactions, this method
* allows the application to make the state of the instance part of the
* transactional state. At transaction commit, the state of the instance in
- * the cache is compared to the state of the instance in the data store. If they
- * are not the same, then an exception is thrown.
+ * the cache is compared to the state of the instance in the data store. If
+ * they are not the same, then an exception is thrown.
* @param pc the instance to make transactional.
*/
void makeTransactional (Object pc);
@@ -659,8 +680,10 @@
*/
void makeTransactionalAll (Object[] pcs);
- /** Make a <code>Collection</code> of instances subject to transactional boundaries.
- * @param pcs the <code>Collection</code> of instances to make transactional.
+ /** Make a <code>Collection</code> of instances subject to transactional
+ * boundaries.
+ * @param pcs the <code>Collection</code> of instances to make
+ * transactional.
* @see #makeTransactional(Object pc)
*/
void makeTransactionalAll (Collection pcs);
@@ -683,81 +706,108 @@
*/
void makeNontransactionalAll (Object[] pcs);
- /** Make a <code>Collection</code> of instances non-transactional after commit.
+ /** Make a <code>Collection</code> of instances non-transactional after
+ * commit.
*
- * @param pcs the <code>Collection</code> of instances to make nontransactional.
+ * @param pcs the <code>Collection</code> of instances to make
+ * nontransactional.
* @see #makeNontransactional(Object pc)
*/
void makeNontransactionalAll (Collection pcs);
/** Retrieve field values of an instance from the store. This tells
- * the <code>PersistenceManager</code> that the application intends to use the
- * instance, and its field values must be retrieved.
- * <P>The <code>PersistenceManager</code> might use policy information about the
- * class to retrieve associated instances.
+ * the <code>PersistenceManager</code> that the application intends to use
+ * the instance, and its field values must be retrieved.
+ * <P>The <code>PersistenceManager</code> might use policy information about
+ * the class to retrieve associated instances.
* @param pc the instance
*/
void retrieve (Object pc);
/** Retrieve field values of an instance from the store. This tells
- * the <code>PersistenceManager</code> that the application intends to use the
- * instance, and its field values must be retrieved.
- * <P>The <code>PersistenceManager</code> might use policy information about the
- * class to retrieve associated instances.
+ * the <code>PersistenceManager</code> that the application intends to use
+ * the instance, and its field values must be retrieved.
+ * <P>If the useFetchPlan parameter is false, this method behaves exactly
+ * as the corresponding method without the useFetchPlan parameter.
+ * If the useFetchPlan parameter is true, and the fetch plan has not been
+ * modified from its default setting, all fields in the current fetch plan
+ * are fetched, and other fields might be fetched lazily by the
+ * implementation. If the useFetchPlan parameter is true, and the fetch
+ * plan has been changed from its default setting, then the fields
+ * specified by the fetch plan are loaded, along with related instances
+ * specified by the fetch plan.
* @param pc the instance
- * @param FGOnly whether to only retrieve the fields in the current fetch group
+ * @param useFetchPlan whether to use the current fetch plan to determine
+ * which fields to load and which instances to retrieve.
* @since 2.0
*/
- void retrieve (Object pc, boolean FGOnly);
+ void retrieve (Object pc, boolean useFetchPlan);
/** Retrieve field values of instances from the store. This tells
- * the <code>PersistenceManager</code> that the application intends to use the
- * instances, and all field values must be retrieved.
- * <P>The <code>PersistenceManager</code> might use policy information about the
- * class to retrieve associated instances.
+ * the <code>PersistenceManager</code> that the application intends to use
+ * the instances, and all field values must be retrieved.
+ * <P>The <code>PersistenceManager</code> might use policy information about
+ * the class to retrieve associated instances.
* @param pcs the instances
*/
void retrieveAll (Collection pcs);
/** Retrieve field values of instances from the store. This tells
- * the <code>PersistenceManager</code> that the application intends to use the
- * instances, and their field values should be retrieved. The fields
+ * the <code>PersistenceManager</code> that the application intends to use
+ * the instances, and their field values should be retrieved. The fields
* in the current fetch group must be retrieved, and the implementation
* might retrieve more fields than the current fetch group.
- * <P>The <code>PersistenceManager</code> might use policy information about the
- * class to retrieve associated instances.
+ * <P>If the useFetchPlan parameter is false, this method behaves exactly
+ * as the corresponding method without the useFetchPlan parameter.
+ * If the useFetchPlan parameter is true, and the fetch plan has not been
+ * modified from its default setting, all fields in the current fetch plan
+ * are fetched, and other fields might be fetched lazily by the
+ * implementation. If the useFetchPlan parameter is true, and the fetch
+ * plan has been changed from its default setting, then the fields
+ * specified by the fetch plan are loaded, along with related instances
+ * specified by the fetch plan.
* @param pcs the instances
- * @param FGOnly whether to retrieve only the fields in the current fetch group
+ * @param useFetchPlan whether to use the current fetch plan to determine
+ * which fields to load and which instances to retrieve.
* @since 1.0.1
*/
- void retrieveAll (Collection pcs, boolean FGOnly);
+ void retrieveAll (Collection pcs, boolean useFetchPlan);
/** Retrieve field values of instances from the store. This tells
- * the <code>PersistenceManager</code> that the application intends to use the
- * instances, and all field values must be retrieved.
- * <P>The <code>PersistenceManager</code> might use policy information about the
- * class to retrieve associated instances.
+ * the <code>PersistenceManager</code> that the application intends to use
+ * the instances, and all field values must be retrieved.
+ * <P>The <code>PersistenceManager</code> might use policy information about
+ * the class to retrieve associated instances.
* @param pcs the instances
*/
void retrieveAll (Object[] pcs);
/** Retrieve field values of instances from the store. This tells
- * the <code>PersistenceManager</code> that the application intends to use the
- * instances, and their field values should be retrieved. The fields
+ * the <code>PersistenceManager</code> that the application intends to use
+ * the instances, and their field values should be retrieved. The fields
* in the current fetch group must be retrieved, and the implementation
* might retrieve more fields than the current fetch group.
- * <P>The <code>PersistenceManager</code> might use policy information about the
- * class to retrieve associated instances.
+ * <P>If the useFetchPlan parameter is false, this method behaves exactly
+ * as the corresponding method without the useFetchPlan parameter.
+ * If the useFetchPlan parameter is true, and the fetch plan has not been
+ * modified from its default setting, all fields in the current fetch plan
+ * are fetched, and other fields might be fetched lazily by the
+ * implementation. If the useFetchPlan parameter is true, and the fetch
+ * plan has been changed from its default setting, then the fields
+ * specified by the fetch plan are loaded, along with related instances
+ * specified by the fetch plan.
* @param pcs the instances
- * @param FGOnly whether to retrieve only the fields in the current fetch group
+ * @param useFetchPlan whether to use the current fetch plan to determine
+ * which fields to load and which instances to retrieve.
* @since 1.0.1
*/
- void retrieveAll (Object[] pcs, boolean FGOnly);
+ void retrieveAll (Object[] pcs, boolean useFetchPlan);
/** The application can manage the <code>PersistenceManager</code> instances
* more easily by having an application object associated with each
* <code>PersistenceManager</code> instance.
- * @param o the user instance to be remembered by the <code>PersistenceManager</code>
+ * @param o the user instance to be remembered by the
+ * <code>PersistenceManager</code>
* @see #getUserObject
*/
void setUserObject (Object o);
@@ -765,44 +815,48 @@
/** The application can manage the <code>PersistenceManager</code> instances
* more easily by having an application object associated with each
* <code>PersistenceManager</code> instance.
- * @return the user object associated with this <code>PersistenceManager</code>
+ * @return the user object associated with this
+ * <code>PersistenceManager</code>
* @see #setUserObject
*/
Object getUserObject ();
- /** This method returns the <code>PersistenceManagerFactory</code> used to create
- * this <code>PersistenceManager</code>.
+ /** This method returns the <code>PersistenceManagerFactory</code> used to
+ * create this <code>PersistenceManager</code>.
* @return the <code>PersistenceManagerFactory</code> that created
* this <code>PersistenceManager</code>
*/
PersistenceManagerFactory getPersistenceManagerFactory();
/** Return the <code>Class</code> that implements the JDO Identity for the
- * specified <code>PersistenceCapable</code> class. The application can use the
- * returned <code>Class</code> to construct a JDO Identity instance for
- * application identity <code>PersistenceCapable</code> classes. This JDO Identity
- * instance can then be used to get an instance of the
+ * specified <code>PersistenceCapable</code> class. The application can use
+ * the returned <code>Class</code> to construct a JDO Identity instance for
+ * application identity <code>PersistenceCapable</code> classes. This JDO
+ * Identity instance can then be used to get an instance of the
* <code>PersistenceCapable</code> class for use in the application.
*
- * <P>In order for the application to construct an instance of the ObjectId class
- * it needs to know the class being used by the JDO implementation.
+ * <P>In order for the application to construct an instance of the ObjectId
+ * class it needs to know the class being used by the JDO implementation.
* @param cls the <code>PersistenceCapable Class</code>
* @return the <code>Class</code> of the ObjectId of the parameter
* @see #getObjectById
*/
Class getObjectIdClass(Class cls);
- /** Set the Multithreaded flag for this <code>PersistenceManager</code>. Applications
- * that use multiple threads to invoke methods or access fields from
- * instances managed by this <code>PersistenceManager</code> must set this flag to <code>true</code>.
- * Instances managed by this <code>PersistenceManager</code> include persistent or
- * transactional instances of <code>PersistenceCapable</code> classes, as well as
- * helper instances such as <code>Query</code>, <code>Transaction</code>, or <code>Extent</code>.
+ /** Set the Multithreaded flag for this <code>PersistenceManager</code>.
+ * Applications that use multiple threads to invoke methods or access fields
+ * from instances managed by this <code>PersistenceManager</code> must set
+ * this flag to <code>true</code>.
+ * Instances managed by this <code>PersistenceManager</code> include
+ * persistent or transactional instances of <code>PersistenceCapable</code>
+ * classes, as well as helper instances such as <code>Query</code>,
+ * <code>Transaction</code>, or <code>Extent</code>.
* @param flag the Multithreaded setting.
*/
void setMultithreaded (boolean flag);
- /** Get the current Multithreaded flag for this <code>PersistenceManager</code>.
+ /** Get the current Multithreaded flag for this
+ * <code>PersistenceManager</code>.
* @see #setMultithreaded
* @return the Multithreaded setting.
*/
@@ -810,16 +864,20 @@
/** Set the ignoreCache parameter for queries.
*
- * <P>IgnoreCache set to <code>true</code> specifies that for all <code>Query</code> instances created by this
- * <code>PersistenceManager</code>, the default is the cache should be ignored for queries.
+ * <P>IgnoreCache set to <code>true</code> specifies that for all
+ * <code>Query</code> instances created by this
+ * <code>PersistenceManager</code>, the default is the cache should be
+ * ignored for queries.
* @param flag the ignoreCache setting.
*/
void setIgnoreCache(boolean flag);
/** Get the ignoreCache setting for queries.
*
- * <P>IgnoreCache set to <code>true</code> specifies that for all <code>Query</code> instances created by this
- * <code>PersistenceManager</code>, the default is the cache should be ignored for queries.
+ * <P>IgnoreCache set to <code>true</code> specifies that for all
+ * <code>Query</code> instances created by this
+ * <code>PersistenceManager</code>, the default is the cache should be
+ * ignored for queries.
* @return the ignoreCache setting.
*/
boolean getIgnoreCache();
Modified: db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java
URL: http://svn.apache.org/viewcvs/db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java?rev=389615&r1=389614&r2=389615&view=diff
==============================================================================
--- db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java (original)
+++ db/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java Tue Mar 28 14:14:14 2006
@@ -29,24 +29,26 @@
import javax.jdo.listener.InstanceLifecycleListener;
/** The <code>PersistenceManagerFactory</code> is the interface to use to obtain
- * <code>PersistenceManager</code> instances. All <code>PersistenceManager</code> instances obtained
- * from the same <code>PersistenceManagerFactory</code> will have the same default
- * properties.
+ * <code>PersistenceManager</code> instances.
+ * All <code>PersistenceManager</code> instances obtained from the same
+ * <code>PersistenceManagerFactory</code> will have the same default properties.
*
* <P><code>PersistenceManagerFactory</code> instances may be configured and
* serialized for later use. They may be stored via JNDI and looked up
* and used later. Any properties configured will be saved and restored.
*
* <P>Once the first <code>PersistenceManager</code> is obtained from the
- * <code>PersistenceManagerFactory</code>, the factory can no longer be configured.
- * <P>If the <code>ConnectionFactory</code> property is set (non-<code>null</code>) then
- * all other Connection properties including <code>ConnectionFactoryName</code> are ignored;
- * otherwise, if <code>ConnectionFactoryName</code> is set (non-<code>null</code>) then
- * all other Connection properties are ignored.
- * Similarly, if the <code>ConnectionFactory2</code> property is set (non-<code>null</code>) then
- * <code>ConnectionFactory2Name</code> is ignored.
- * <P>Operational state (<code>PersistenceManager</code> pooling, connection pooling,
- * operational parameters) must not be serialized.
+ * <code>PersistenceManagerFactory</code>, the factory can no longer be
+ * configured.
+ * <P>If the <code>ConnectionFactory</code> property is set
+ * (non-<code>null</code>) then all other Connection properties including
+ * <code>ConnectionFactoryName</code> are ignored;
+ * otherwise, if <code>ConnectionFactoryName</code> is set
+ * (non-<code>null</code>) then all other Connection properties are ignored.
+ * Similarly, if the <code>ConnectionFactory2</code> property is set
+ * (non-<code>null</code>) then <code>ConnectionFactory2Name</code> is ignored.
+ * <P>Operational state (<code>PersistenceManager</code> pooling, connection
+ * pooling, operational parameters) must not be serialized.
*
* @version 2.0
*/
@@ -81,22 +83,23 @@
*/
boolean isClosed();
- /** Get an instance of <code>PersistenceManager</code> from this factory. The instance has
- * default values for options.
+ /** Get an instance of <code>PersistenceManager</code> from this factory.
+ * The instance has default values for options.
*
- * <P>After the first use of <code>getPersistenceManager</code>, no "set" methods will
- * succeed.
+ * <P>After the first use of <code>getPersistenceManager</code>, no "set"
+ * methods will succeed.
*
* @return a <code>PersistenceManager</code> instance with default options.
*/
PersistenceManager getPersistenceManager();
- /** Get an instance of <code>PersistenceManager</code> from this factory. The instance has
- * default values for options. The parameters <code>userid</code> and <code>password</code> are used
+ /** Get an instance of <code>PersistenceManager</code> from this factory.
+ * The instance has default values for options.
+ * The parameters <code>userid</code> and <code>password</code> are used
* when obtaining datastore connections from the connection pool.
*
- * <P>After the first use of <code>getPersistenceManager</code>, no "set" methods will
- * succeed.
+ * <P>After the first use of <code>getPersistenceManager</code>, no "set"
+ * methods will succeed.
*
* @return a <code>PersistenceManager</code> instance with default options.
* @param userid the userid for the connection
@@ -120,9 +123,9 @@
void setConnectionPassword (String password);
/** Set the URL for the data store connection.
- * @param URL the URL for the data store connection.
+ * @param url the URL for the data store connection.
*/
- void setConnectionURL (String URL);
+ void setConnectionURL (String url);
/** Get the URL for the data store connection.
* @return the URL for the data store connection.
@@ -140,7 +143,8 @@
String getConnectionDriverName ();
/** Set the name for the data store connection factory.
- * @param connectionFactoryName the name of the data store connection factory.
+ * @param connectionFactoryName the name of the data store connection
+ * factory.
*/
void setConnectionFactoryName (String connectionFactoryName);
@@ -164,7 +168,8 @@
/** Set the name for the second data store connection factory. This is
* needed for managed environments to get nontransactional connections for
* optimistic transactions.
- * @param connectionFactoryName the name of the data store connection factory.
+ * @param connectionFactoryName the name of the data store connection
+ * factory.
*/
void setConnectionFactory2Name (String connectionFactoryName);
@@ -191,15 +196,15 @@
*/
Object getConnectionFactory2 ();
- /** Set the default Multithreaded setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Set the default Multithreaded setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @param flag the default Multithreaded setting.
*/
void setMultithreaded (boolean flag);
- /** Get the default Multithreaded setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Get the default Multithreaded setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @return the default Multithreaded setting.
*/
@@ -219,29 +224,29 @@
*/
String getMapping ();
- /** Set the default Optimistic setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Set the default Optimistic setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @param flag the default Optimistic setting.
*/
void setOptimistic (boolean flag);
- /** Get the default Optimistic setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Get the default Optimistic setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @return the default Optimistic setting.
*/
boolean getOptimistic();
- /** Set the default RetainValues setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Set the default RetainValues setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @param flag the default RetainValues setting.
*/
void setRetainValues (boolean flag);
- /** Get the default RetainValues setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Get the default RetainValues setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @return the default RetainValues setting.
*/
@@ -269,71 +274,72 @@
*/
boolean getRestoreValues();
- /** Set the default NontransactionalRead setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Set the default NontransactionalRead setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @param flag the default NontransactionalRead setting.
*/
void setNontransactionalRead (boolean flag);
- /** Get the default NontransactionalRead setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Get the default NontransactionalRead setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @return the default NontransactionalRead setting.
*/
boolean getNontransactionalRead ();
- /** Set the default NontransactionalWrite setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Set the default NontransactionalWrite setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @param flag the default NontransactionalWrite setting.
*/
void setNontransactionalWrite (boolean flag);
- /** Get the default NontransactionalWrite setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Get the default NontransactionalWrite setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @return the default NontransactionalWrite setting.
*/
boolean getNontransactionalWrite ();
- /** Set the default IgnoreCache setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Set the default IgnoreCache setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @param flag the default IgnoreCache setting.
*/
void setIgnoreCache (boolean flag);
- /** Get the default IgnoreCache setting for all <code>PersistenceManager</code> instances
- * obtained from this factory.
+ /** Get the default IgnoreCache setting for all
+ * <code>PersistenceManager</code> instances obtained from this factory.
*
* @return the default IngoreCache setting.
*/
boolean getIgnoreCache ();
- /** Gets the detachAllOnCommit setting.
- * @see #setDetachAllOnCommit(boolean)
- * @since 2.0
- * @return the default detachAllOnCommit setting.
- */
- boolean getDetachAllOnCommit();
-
- /** Sets the default detachAllOnCommit setting for all
- * <code>PersistenceManager</code> instances obtained from this
- * factory.
- * @see #getDetachAllOnCommit()
- * @since 2.0
- */
- void setDetachAllOnCommit(boolean flag);
-
- /** Return non-configurable properties of this <code>PersistenceManagerFactory</code>.
- * Properties with keys <code>VendorName</code> and <code>VersionNumber</code> are required. Other
- * keys are optional.
+ /** Gets the detachAllOnCommit setting.
+ * @see #setDetachAllOnCommit(boolean)
+ * @since 2.0
+ * @return the default detachAllOnCommit setting.
+ */
+ boolean getDetachAllOnCommit();
+
+ /** Sets the default detachAllOnCommit setting for all
+ * <code>PersistenceManager</code> instances obtained from this
+ * factory.
+ * @see #getDetachAllOnCommit()
+ * @since 2.0
+ */
+ void setDetachAllOnCommit(boolean flag);
+
+ /** Return non-configurable properties of this
+ * <code>PersistenceManagerFactory</code>.
+ * Properties with keys <code>VendorName</code> and
+ * <code>VersionNumber</code> are required. Other keys are optional.
* @return the non-configurable properties of this
* <code>PersistenceManagerFactory</code>.
*/
Properties getProperties();
-
+
/** The application can determine from the results of this
* method which optional features, and which query languages
* are supported by the JDO implementation.
@@ -367,9 +373,11 @@
* <BR>javax.jdo.query.JDOQL
* </code>
*
- *<P>The standard JDO query language is represented by a <code>String</code>:
+ *<P>The standard JDO query language is represented by a
+ * <code>String</code>:
*<P><code>javax.jdo.query.JDOQL</code>
- * @return the <code>Collection</code> of <code>String</code>s representing the supported options.
+ * @return the <code>Collection</code> of <code>String</code>s representing
+ * the supported options.
*/
Collection supportedOptions();