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 JDODetachedFieldAccessException without a detail message. + * Constructs a new JDODetachedFieldAccessException without a + * detail message. * @since 2.0 */ public JDODetachedFieldAccessException() { @@ -38,7 +39,8 @@ /** - * Constructs a new JDODetachedFieldAccessException with the specified detail message. + * Constructs a new JDODetachedFieldAccessException 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. *

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 * PersistenceManager 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 @@ * PersistenceManager. * *

Transient non-transactional instances and instances of classes - * that do not implement PersistenceCapable return null. + * that do not implement PersistenceCapable return + * null. * @see PersistenceCapable#jdoGetPersistenceManager() * @param pc the PersistenceCapable instance. - * @return the PersistenceManager associated with the parameter instance. + * @return the PersistenceManager 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, PersistenceCapable 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, PersistenceCapable 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. * - *

Persistent instances of PersistenceCapable classes have a JDO identity - * managed by the PersistenceManager. This method returns a copy of the - * ObjectId that represents the JDO identity. + *

Persistent instances of PersistenceCapable classes have a + * JDO identity managed by the PersistenceManager. This method + * returns a copy of the ObjectId that represents the JDO identity. * - *

Transient instances and instances of classes - * that do not implement PersistenceCapable return null. + *

Transient instances and instances of classes that do not implement + * PersistenceCapable return null. * *

The ObjectId may be serialized - * and later restored, and used with a PersistenceManager from the same JDO - * implementation to locate a persistent instance with the same data store - * identity. - * - *

If the JDO identity is managed by the application, then the ObjectId may - * be used with a PersistenceManager from any JDO implementation that supports - * the PersistenceCapable class. - * - *

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 PersistenceManager from + * the same JDO implementation to locate a persistent instance with the same + * data store identity. + * + *

If the JDO identity is managed by the application, then the ObjectId + * may be used with a PersistenceManager from any JDO + * implementation that supports the PersistenceCapable class. + * + *

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. *

* @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 PersistenceCapable 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 true. * - *

Transient instances and instances of classes - * that do not implement PersistenceCapable return false. + *

Transient instances and instances of classes that do not implement + * PersistenceCapable return false. *

- * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName) + * @see javax.jdo.spi.StateManager#makeDirty(PersistenceCapable pc, + * String fieldName) * @see PersistenceCapable#jdoIsDirty() * @param pc the PersistenceCapable instance. - * @return true if the parameter instance has been modified in the current transaction. + * @return true 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. * - *

Transient instances and instances of classes - * that do not implement PersistenceCapable return false. + *

Transient instances and instances of classes that do not implement + * PersistenceCapable return false. * @see PersistenceCapable#jdoIsTransactional() * @param pc the PersistenceCapable instance. * @return true if the parameter instance is transactional. @@ -374,8 +384,8 @@ * Instances that represent persistent objects in the data store * return true. * - *

Transient instances and instances of classes - * that do not implement PersistenceCapable return false. + *

Transient instances and instances of classes that do not implement + * PersistenceCapable return false. *

* @see PersistenceManager#makePersistent(Object pc) * @see PersistenceCapable#jdoIsPersistent() @@ -395,8 +405,8 @@ * Instances that have been made persistent in the current transaction * return true. * - *

Transient instances and instances of classes - * that do not implement PersistenceCapable return false. + *

Transient instances and instances of classes that do not implement + * PersistenceCapable return false. *

* @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 true. + * Instances that have been deleted in the current transaction return + * true. * - *

Transient instances and instances of classes - * that do not implement PersistenceCapable return false. + *

Transient instances and instances of classes that do not implement + * PersistenceCapable return false. *

* @see PersistenceManager#deletePersistent(Object pc) * @see PersistenceCapable#jdoIsDeleted() @@ -453,11 +464,12 @@ } } - /** Get a PersistenceManagerFactory based on a Properties instance, using - * the current thread's context class loader to locate the + /** Get a PersistenceManagerFactory based on a Properties + * instance, using the current thread's context class loader to locate the * PersistenceManagerFactory class. * @return the PersistenceManagerFactory. - * @param props a Properties instance with properties of the PersistenceManagerFactory. + * @param props a Properties instance with properties of the + * PersistenceManagerFactory. * @see #getPersistenceManagerFactory(Map,ClassLoader) */ public static PersistenceManagerFactory getPersistenceManagerFactory @@ -467,8 +479,8 @@ } /** - * Get a PersistenceManagerFactory based on a Properties - * instance and a class loader. + * Get a PersistenceManagerFactory based on a + * Properties instance and a class loader. * The following are standard key values: *
"javax.jdo.PersistenceManagerFactoryClass" *
"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 * JDOFatalUserException thrown by the method. - *

The returned PersistenceManagerFactory is not configurable (the - * setXXX methods will throw an exception). + *

The returned PersistenceManagerFactory is not + * configurable (the setXXX methods will throw an + * exception). *

JDO implementations might manage a map of instantiated - * PersistenceManagerFactory instances based on specified property key - * values, and return a previously instantiated PersistenceManagerFactory - * instance. In this case, the properties of the returned - * instance must exactly match the requested properties. + * PersistenceManagerFactory instances based on specified + * property key values, and return a previously instantiated + * PersistenceManagerFactory instance. In this case, the + * properties of the returned instance must exactly match the requested + * properties. * @return the PersistenceManagerFactory. - * @param props a Properties instance with properties of the PersistenceManagerFactory. - * @param cl the class loader to use to load the PersistenceManagerFactory class + * @param props a Properties instance with properties of the + * PersistenceManagerFactory. + * @param cl the class loader to use to load the + * PersistenceManagerFactory 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 PersistenceManagerFactory class + * @param loader the class loader to use to load both the propsResource and + * the PersistenceManagerFactory 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 PersistenceManagerFactory class + * @param pmfLoader the class loader to use to load the + * PersistenceManagerFactory 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 PersistenceManagerFactory class + * @param loader the class loader to use to load the + * PersistenceManagerFactory 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 Thread.currentThread().getContextClassLoader() as * the loader 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 @@ * loader. Any NamingExceptions 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 PersistenceManagerFactory 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 + * PersistenceManagerFactory 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 PersistenceManagerFactory class + * @param loader the class loader to use to load the + * PersistenceManagerFactory 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 JDOOptimisticVerificationException without a detail message. + * Constructs a new JDOOptimisticVerificationException without a + * detail message. */ public JDOOptimisticVerificationException() { } /** - * Constructs a new JDOOptimisticVerificationException with the specified detail message. + * Constructs a new JDOOptimisticVerificationException with the + * specified detail message. * @param msg the detail message. */ public JDOOptimisticVerificationException(String msg) { super(msg); } - /** Constructs a new JDOOptimisticVerificationException with the specified detail message - * and failed object. + /** Constructs a new JDOOptimisticVerificationException 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 JDOOptimisticVerificationException with the specified - * detail message and nested Throwables. + * Constructs a new JDOOptimisticVerificationException with the + * specified detail message and nested Throwables. * @param msg the detail message. * @param nested the nested Throwable[]. */ 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; -/** PersistenceManager is the primary interface for JDO-aware application - * components. It is the factory for Query and Transaction instances, - * and contains methods to manage the life cycle of PersistenceCapable - * instances. +/** PersistenceManager is the primary interface for JDO-aware + * application components. It is the factory for Query and + * Transaction instances, and contains methods to manage the + * life cycle of PersistenceCapable instances. * *

A PersistenceManager is obtained from the * {@link PersistenceManagerFactory} @@ -41,40 +41,44 @@ public interface PersistenceManager { /** - * A PersistenceManager instance can be used until it is closed. - * @return true if this PersistenceManager has been closed. + * A PersistenceManager instance can be used until it is + * closed. + * @return true if this PersistenceManager has + * been closed. * @see #close() */ boolean isClosed (); - /** Close this PersistenceManager so that no further requests may be - * made on it. A PersistenceManager instance can be used - * only until it is closed. - * - *

Closing a PersistenceManager might release it to the pool of available - * PersistenceManagers, or might be garbage collected, at the option of - * the JDO implementation. Before being used again to satisfy a - * getPersistenceManager() request, the default values for options will - * be restored to their values as specified in the PersistenceManagerFactory. + /** Close this PersistenceManager so that no further requests + * may be made on it. A PersistenceManager instance can be + * used only until it is closed. + * + *

Closing a PersistenceManager might release it to the pool + * of available PersistenceManagers, or might be garbage + * collected, at the option of the JDO implementation. Before being used + * again to satisfy a getPersistenceManager() request, the + * default values for options will be restored to their values as specified + * in the PersistenceManagerFactory. * *

This method closes the PersistenceManager. */ void close (); - /** Return the Transaction instance associated with a PersistenceManager. - * There is one Transaction instance associated with each PersistenceManager - * instance. The Transaction instance supports options as well as + /** Return the Transaction instance associated with a + * PersistenceManager. There is one Transaction + * instance associated with each PersistenceManager instance. + * The Transaction instance supports options as well as * transaction completion requests. * @return the Transaction associated with this * PersistenceManager. */ Transaction currentTransaction(); - /** Mark an instance as no longer needed in the cache. - * Eviction is normally done automatically by the PersistenceManager - * at transaction completion. This method allows the application to - * explicitly provide a hint to the PersistenceManager 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 PersistenceManager at transaction + * completion. This method allows the application to explicitly provide a + * hint to the PersistenceManager 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 Collection of instances as no longer needed in the cache. + /** Mark a Collection of instances as no longer needed in the + * cache. * @see #evict(Object pc) - * @param pcs the Collection of instances to evict from the cache. + * @param pcs the Collection 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. - *

Outside a transaction, this method will refresh nontransactional state. + *

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 Collection of instances from the data store. + /** Refresh the state of a Collection of instances from the + * data store. * * @see #refresh(Object pc) * @param pcs the Collection of instances to refresh. @@ -144,14 +152,17 @@ */ Query newQuery (); - /** Create a new Query using elements from another Query. - * The other Query must have been created by the same JDO implementation. - * It might be active - * in a different PersistenceManager or might have been serialized and restored. - *

All of the settings of the other Query are copied to this Query, - * except for the candidate Collection or Extent. + /** Create a new Query using elements from another + * Query. The other Query must have been created + * by the same JDO implementation. It might be active in a different + * PersistenceManager or might have been serialized and + * restored. + *

All of the settings of the other Query are copied to this + * Query, except for the candidate Collection or + * Extent. * @return the new Query - * @param compiled another Query from the same JDO implementation + * @param compiled another Query from the same JDO + * implementation */ Query newQuery (Object compiled); @@ -170,7 +181,8 @@ */ Query newQuery (String language, Object query); - /** Create a new Query specifying the Class of the candidate instances. + /** Create a new Query specifying the Class of the + * candidate instances. * @param cls the Class of the candidate instances * @return the new Query */ @@ -199,7 +211,8 @@ */ Query newQuery (Class cls, String filter); - /** Create a new Query with the Class of the candidate instances, + /** Create a new Query with the Class of the + * candidate instances, * candidate Collection, and filter. * @param cls the Class of candidate instances * @param cln the Collection of candidate instances @@ -227,12 +240,13 @@ */ Query newNamedQuery (Class cls, String queryName); - /** The PersistenceManager manages a collection of instances in the data - * store based on the class of the instances. This method returns an - * Extent of instances in the data store that might be iterated or - * given to a Query. The Extent itself might not reference any - * instances, but only hold the class name and an - * indicator as to whether subclasses are included in the Extent. + /** The PersistenceManager manages a collection of instances in + * the data store based on the class of the instances. This method returns + * an Extent of instances in the data store that might be + * iterated or given to a Query. The Extent + * itself might not reference any instances, but only hold the class name + * and an indicator as to whether subclasses are included in the + * Extent. *

Note that the Extent might be very large. * @param persistenceCapableClass Class of instances * @param subclasses whether to include instances of subclasses @@ -253,18 +267,20 @@ * managed by this PersistenceManager. * The getObjectById method attempts * to find an instance in the cache with the specified JDO identity. - * The oid parameter object might have been returned by an earlier call - * to getObjectId or getTransactionalObjectId, - * or might have been constructed by the application. - *

If the PersistenceManager is unable to resolve the oid parameter - * to an ObjectId instance, then it throws a JDOUserException. - *

If the validate flag is false, and there is already an instance in the - * cache with the same JDO identity as the oid parameter, then this method - * returns it. There is no change made to the state of the returned - * instance. + * The oid parameter object might have been returned by an + * earlier call to getObjectId or + * getTransactionalObjectId, or might have been constructed by + * the application. + *

If the PersistenceManager is unable to resolve the + * oid parameter to an ObjectId instance, then it throws a + * JDOUserException. + *

If the validate flag is false, and there is + * already an instance in the cache with the same JDO identity as the + * oid parameter, then this method returns it. There is no + * change made to the state of the returned instance. *

If there is not an instance already in the cache with the same JDO - * identity as the oid parameter, then this method creates an instance - * with the specified JDO identity and returns it. If there is no + * identity as the oid 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. *

If there is a transaction in progress, the returned instance will @@ -272,10 +288,10 @@ * choice of the implementation. *

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 PersistenceCapable classes share the - * same ObjectId class. - *

If the validate flag is false, and the instance does not exist in - * the data store, then this method might not fail. It is an + * inheritance, where multiple PersistenceCapable classes share + * the same ObjectId class. + *

If the validate flag is false, 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 * JDOObjectNotFoundException. 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. - *

If the validate flag is true, and there is already a transactional - * instance in the cache with the same JDO identity as the oid parameter, - * then this method returns it. There is no change made to the state of - * the returned instance. - *

If there is an instance already in the cache with the same JDO - * identity as the oid 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 JDOObjectNotFoundException - * is thrown. + *

If the validate flag is true, and there is + * already a transactional instance in the cache with the same JDO identity + * as the oid parameter, then this method returns it. There is + * no change made to the state of the returned instance. + *

If there is an instance already in the cache with the same JDO + * identity as the oid 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 + * JDOObjectNotFoundException is thrown. *

If there is not an instance already in the cache with the same JDO - * identity as the oid 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 oid 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. *

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 PersistenceCapable instance with the specified ObjectId + * @return the PersistenceCapable 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. - *

The getObjectId 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 - * PersistenceManager that created the identity, and only for two types - * of JDO Identity: those that are managed by the application, and + *

The getObjectId 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 + * PersistenceManager 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. *

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 getObjectId will be different - * following afterCompletion processing for successful transactions. - *

Within a transaction, the ObjectId returned will compare equal to - * the ObjectId returned by only one among all JDO instances associated - * with the PersistenceManager regardless of the type of ObjectId. + * transaction. The value returned by getObjectId will be + * different following afterCompletion processing for + * successful transactions.

Within a transaction, the ObjectId returned + * will compare equal to the ObjectId returned by only one among all JDO + * instances associated with the PersistenceManager regardless + * of the type of ObjectId. *

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. *

The getObjectById method can be used between instances of - * PersistenceManager 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. + * PersistenceManager 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 PersistenceCapable 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 makePersistent, 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 JDOUserException if the instance is transient or - * is managed by another PersistenceManager. + * Unlike makePersistent, 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 JDOUserException if the instance is + * transient or is managed by another PersistenceManager. * * @param pc a persistent instance */ @@ -548,25 +566,28 @@ * PersistenceManager. * *

The instance loses its JDO identity and it is no longer associated - * with any PersistenceManager. The state of fields is preserved unchanged. + * with any PersistenceManager. 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 - * PersistenceManager. + /** Make an array of instances transient, removing them from management by + * this PersistenceManager. * - *

The instances lose their JDO identity and they are no longer associated - * with any PersistenceManager. The state of fields is preserved unchanged. + *

The instances lose their JDO identity and they are no longer + * associated with any PersistenceManager. The state of fields + * is preserved unchanged. * @param pcs the instances to make transient. */ void makeTransientAll (Object[] pcs); - /** Make a Collection of instances transient, removing them from - * management by this PersistenceManager. + /** Make a Collection of instances transient, removing them + * from management by this PersistenceManager. * - *

The instances lose their JDO identity and they are no longer associated - * with any PersistenceManager. The state of fields is preserved unchanged. + *

The instances lose their JDO identity and they are no longer + * associated with any PersistenceManager. 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. * *

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. * *

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 Collection of instances subject to transactional boundaries. - * @param pcs the Collection of instances to make transactional. + /** Make a Collection of instances subject to transactional + * boundaries. + * @param pcs the Collection of instances to make + * transactional. * @see #makeTransactional(Object pc) */ void makeTransactionalAll (Collection pcs); @@ -683,81 +706,108 @@ */ void makeNontransactionalAll (Object[] pcs); - /** Make a Collection of instances non-transactional after commit. + /** Make a Collection of instances non-transactional after + * commit. * - * @param pcs the Collection of instances to make nontransactional. + * @param pcs the Collection 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 PersistenceManager that the application intends to use the - * instance, and its field values must be retrieved. - *

The PersistenceManager might use policy information about the - * class to retrieve associated instances. + * the PersistenceManager that the application intends to use + * the instance, and its field values must be retrieved. + *

The PersistenceManager 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 PersistenceManager that the application intends to use the - * instance, and its field values must be retrieved. - *

The PersistenceManager might use policy information about the - * class to retrieve associated instances. + * the PersistenceManager that the application intends to use + * the instance, and its field values must be retrieved. + *

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 PersistenceManager that the application intends to use the - * instances, and all field values must be retrieved. - *

The PersistenceManager might use policy information about the - * class to retrieve associated instances. + * the PersistenceManager that the application intends to use + * the instances, and all field values must be retrieved. + *

The PersistenceManager 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 PersistenceManager that the application intends to use the - * instances, and their field values should be retrieved. The fields + * the PersistenceManager 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. - *

The PersistenceManager might use policy information about the - * class to retrieve associated instances. + *

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 PersistenceManager that the application intends to use the - * instances, and all field values must be retrieved. - *

The PersistenceManager might use policy information about the - * class to retrieve associated instances. + * the PersistenceManager that the application intends to use + * the instances, and all field values must be retrieved. + *

The PersistenceManager 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 PersistenceManager that the application intends to use the - * instances, and their field values should be retrieved. The fields + * the PersistenceManager 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. - *

The PersistenceManager might use policy information about the - * class to retrieve associated instances. + *

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 PersistenceManager instances * more easily by having an application object associated with each * PersistenceManager instance. - * @param o the user instance to be remembered by the PersistenceManager + * @param o the user instance to be remembered by the + * PersistenceManager * @see #getUserObject */ void setUserObject (Object o); @@ -765,44 +815,48 @@ /** The application can manage the PersistenceManager instances * more easily by having an application object associated with each * PersistenceManager instance. - * @return the user object associated with this PersistenceManager + * @return the user object associated with this + * PersistenceManager * @see #setUserObject */ Object getUserObject (); - /** This method returns the PersistenceManagerFactory used to create - * this PersistenceManager. + /** This method returns the PersistenceManagerFactory used to + * create this PersistenceManager. * @return the PersistenceManagerFactory that created * this PersistenceManager */ PersistenceManagerFactory getPersistenceManagerFactory(); /** Return the Class that implements the JDO Identity for the - * specified PersistenceCapable class. The application can use the - * returned Class to construct a JDO Identity instance for - * application identity PersistenceCapable classes. This JDO Identity - * instance can then be used to get an instance of the + * specified PersistenceCapable class. The application can use + * the returned Class to construct a JDO Identity instance for + * application identity PersistenceCapable classes. This JDO + * Identity instance can then be used to get an instance of the * PersistenceCapable class for use in the application. * - *

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. + *

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 PersistenceCapable Class * @return the Class of the ObjectId of the parameter * @see #getObjectById */ Class getObjectIdClass(Class cls); - /** Set the Multithreaded flag for this PersistenceManager. Applications - * that use multiple threads to invoke methods or access fields from - * instances managed by this PersistenceManager must set this flag to true. - * Instances managed by this PersistenceManager include persistent or - * transactional instances of PersistenceCapable classes, as well as - * helper instances such as Query, Transaction, or Extent. + /** Set the Multithreaded flag for this PersistenceManager. + * Applications that use multiple threads to invoke methods or access fields + * from instances managed by this PersistenceManager must set + * this flag to true. + * Instances managed by this PersistenceManager include + * persistent or transactional instances of PersistenceCapable + * classes, as well as helper instances such as Query, + * Transaction, or Extent. * @param flag the Multithreaded setting. */ void setMultithreaded (boolean flag); - /** Get the current Multithreaded flag for this PersistenceManager. + /** Get the current Multithreaded flag for this + * PersistenceManager. * @see #setMultithreaded * @return the Multithreaded setting. */ @@ -810,16 +864,20 @@ /** Set the ignoreCache parameter for queries. * - *

IgnoreCache set to true specifies that for all Query instances created by this - * PersistenceManager, the default is the cache should be ignored for queries. + *

IgnoreCache set to true specifies that for all + * Query instances created by this + * PersistenceManager, 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. * - *

IgnoreCache set to true specifies that for all Query instances created by this - * PersistenceManager, the default is the cache should be ignored for queries. + *

IgnoreCache set to true specifies that for all + * Query instances created by this + * PersistenceManager, 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 PersistenceManagerFactory is the interface to use to obtain - * PersistenceManager instances. All PersistenceManager instances obtained - * from the same PersistenceManagerFactory will have the same default - * properties. + * PersistenceManager instances. + * All PersistenceManager instances obtained from the same + * PersistenceManagerFactory will have the same default properties. * *

PersistenceManagerFactory 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. * *

Once the first PersistenceManager is obtained from the - * PersistenceManagerFactory, the factory can no longer be configured. - *

If the ConnectionFactory property is set (non-null) then - * all other Connection properties including ConnectionFactoryName are ignored; - * otherwise, if ConnectionFactoryName is set (non-null) then - * all other Connection properties are ignored. - * Similarly, if the ConnectionFactory2 property is set (non-null) then - * ConnectionFactory2Name is ignored. - *

Operational state (PersistenceManager pooling, connection pooling, - * operational parameters) must not be serialized. + * PersistenceManagerFactory, the factory can no longer be + * configured. + *

If the ConnectionFactory property is set + * (non-null) then all other Connection properties including + * ConnectionFactoryName are ignored; + * otherwise, if ConnectionFactoryName is set + * (non-null) then all other Connection properties are ignored. + * Similarly, if the ConnectionFactory2 property is set + * (non-null) then ConnectionFactory2Name is ignored. + *

Operational state (PersistenceManager pooling, connection + * pooling, operational parameters) must not be serialized. * * @version 2.0 */ @@ -81,22 +83,23 @@ */ boolean isClosed(); - /** Get an instance of PersistenceManager from this factory. The instance has - * default values for options. + /** Get an instance of PersistenceManager from this factory. + * The instance has default values for options. * - *

After the first use of getPersistenceManager, no "set" methods will - * succeed. + *

After the first use of getPersistenceManager, no "set" + * methods will succeed. * * @return a PersistenceManager instance with default options. */ PersistenceManager getPersistenceManager(); - /** Get an instance of PersistenceManager from this factory. The instance has - * default values for options. The parameters userid and password are used + /** Get an instance of PersistenceManager from this factory. + * The instance has default values for options. + * The parameters userid and password are used * when obtaining datastore connections from the connection pool. * - *

After the first use of getPersistenceManager, no "set" methods will - * succeed. + *

After the first use of getPersistenceManager, no "set" + * methods will succeed. * * @return a PersistenceManager 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 PersistenceManager instances - * obtained from this factory. + /** Set the default Multithreaded setting for all + * PersistenceManager instances obtained from this factory. * * @param flag the default Multithreaded setting. */ void setMultithreaded (boolean flag); - /** Get the default Multithreaded setting for all PersistenceManager instances - * obtained from this factory. + /** Get the default Multithreaded setting for all + * PersistenceManager instances obtained from this factory. * * @return the default Multithreaded setting. */ @@ -219,29 +224,29 @@ */ String getMapping (); - /** Set the default Optimistic setting for all PersistenceManager instances - * obtained from this factory. + /** Set the default Optimistic setting for all + * PersistenceManager instances obtained from this factory. * * @param flag the default Optimistic setting. */ void setOptimistic (boolean flag); - /** Get the default Optimistic setting for all PersistenceManager instances - * obtained from this factory. + /** Get the default Optimistic setting for all + * PersistenceManager instances obtained from this factory. * * @return the default Optimistic setting. */ boolean getOptimistic(); - /** Set the default RetainValues setting for all PersistenceManager instances - * obtained from this factory. + /** Set the default RetainValues setting for all + * PersistenceManager instances obtained from this factory. * * @param flag the default RetainValues setting. */ void setRetainValues (boolean flag); - /** Get the default RetainValues setting for all PersistenceManager instances - * obtained from this factory. + /** Get the default RetainValues setting for all + * PersistenceManager instances obtained from this factory. * * @return the default RetainValues setting. */ @@ -269,71 +274,72 @@ */ boolean getRestoreValues(); - /** Set the default NontransactionalRead setting for all PersistenceManager instances - * obtained from this factory. + /** Set the default NontransactionalRead setting for all + * PersistenceManager instances obtained from this factory. * * @param flag the default NontransactionalRead setting. */ void setNontransactionalRead (boolean flag); - /** Get the default NontransactionalRead setting for all PersistenceManager instances - * obtained from this factory. + /** Get the default NontransactionalRead setting for all + * PersistenceManager instances obtained from this factory. * * @return the default NontransactionalRead setting. */ boolean getNontransactionalRead (); - /** Set the default NontransactionalWrite setting for all PersistenceManager instances - * obtained from this factory. + /** Set the default NontransactionalWrite setting for all + * PersistenceManager instances obtained from this factory. * * @param flag the default NontransactionalWrite setting. */ void setNontransactionalWrite (boolean flag); - /** Get the default NontransactionalWrite setting for all PersistenceManager instances - * obtained from this factory. + /** Get the default NontransactionalWrite setting for all + * PersistenceManager instances obtained from this factory. * * @return the default NontransactionalWrite setting. */ boolean getNontransactionalWrite (); - /** Set the default IgnoreCache setting for all PersistenceManager instances - * obtained from this factory. + /** Set the default IgnoreCache setting for all + * PersistenceManager instances obtained from this factory. * * @param flag the default IgnoreCache setting. */ void setIgnoreCache (boolean flag); - /** Get the default IgnoreCache setting for all PersistenceManager instances - * obtained from this factory. + /** Get the default IgnoreCache setting for all + * PersistenceManager 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 - * PersistenceManager instances obtained from this - * factory. - * @see #getDetachAllOnCommit() - * @since 2.0 - */ - void setDetachAllOnCommit(boolean flag); - - /** Return non-configurable properties of this PersistenceManagerFactory. - * Properties with keys VendorName and VersionNumber 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 + * PersistenceManager instances obtained from this + * factory. + * @see #getDetachAllOnCommit() + * @since 2.0 + */ + void setDetachAllOnCommit(boolean flag); + + /** Return non-configurable properties of this + * PersistenceManagerFactory. + * Properties with keys VendorName and + * VersionNumber are required. Other keys are optional. * @return the non-configurable properties of this * PersistenceManagerFactory. */ 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 @@ *
javax.jdo.query.JDOQL * * - *

The standard JDO query language is represented by a String: + *

The standard JDO query language is represented by a + * String: *

javax.jdo.query.JDOQL - * @return the Collection of Strings representing the supported options. + * @return the Collection of Strings representing + * the supported options. */ Collection supportedOptions();