Javadogs,
This is the specification update to implement Issue 136, which
removes attachCopy and changes the signature of makePersistent to
return the instances made persistent.
Please comment.
<proposed 12.6.7>
Make instances persistent
Object makePersistent (Object pc);
Object [] makePersistentAll (Object[] pcs);
Collection makePersistentAll (Collection pcs);
A12.5.7-6A [These methods make transient instances persistent and
apply detached instance changes to the cache. They must be called in
the context of an active transaction, or a JDOUserException is
thrown.] A12.5.7-6B [For a transient instance, they will assign an
object identity to the instance and transition it to persistent-new.]
Any transient instances reachable from this instance via persistent
fields of this instance will become provisionally persistent,
transitively. That is, they behave as persistent-new instances
(return true to isPersistent, isNew, and isDirty). But A12.5.7-6C [at
commit time, the reachability algorithm is run again, and instances
made provisionally persistent that are not currently reachable from
persistent instances will revert to transient.]
For a detached instance, they locate or create a persistent instance
with the same JDO identity as the detached instance, and copy the
persistent state of the detached instance to the persistent instance.
Only the state of persistent fields is copied. If non-persistent
state needs to be copied, the application should use the
jdoPostAttach callback or the postAttach lifecycle event listener.
Any references to the detached instances from instances in the
closure of the parameter instances are modified to refer to the
corresponding persistent instance instead of to the detached instance.
During application of changes of the detached state, if the JDO
implementation can determine that there were no changes made during
detachment, then the implementation is not required to mark the
corresponding instance dirty. A12.6.8-28 [If it cannot determine if
changes were made, then it must mark the instance dirty.]
No consistency checking is done during makePersistent. If consistency
checking is required by the application, then flush or
checkConsistency should be called after attaching the instances.
A12.5.7-7 [These methods have no effect on parameter persistent
instances already managed by this PersistenceManager.] A12.5.7-8
[They will throw a JDOUserException if the parameter instance is
managed by a different PersistenceManager.]
A12.6.7-1 [If an instance is of a class whose identity type
(application, datastore, or none) is not supported by the JDO
implementation, then a JDOUserException will be thrown for that
instance.]
The return value for instances in the transient or persistent states
is the same as the parameter value. The return value for detached
instances is the persistent instance corresponding to the detached
instance.
The return values for makePersistentAll methods correspond by
position to the parameter instances.</proposed 12.6.7>
<proposed 12.6.8 to be deleted>
Attaching Instances
Object attachCopy(Object detached, boolean makeTransactional);
Collection attachCopyAll(Collection detached, boolean
makeTransactional);
Object[] attachCopyAll(Object[] detached, boolean makeTransactional);
This method applies the changes contained in the collection of
detached instances to the corresponding persistent instances in the
cache and returns a collection of persistent instances that exactly
corresponds to the parameter instances. A12.6.8-25 [The order of
instances in the parameter Collection’s iteration corresponds to the
order of corresponding instances in the returned Collection’s
iteration.]
A12.6.8-26 [Changes made to instances while detached are applied to
the corresponding persistent instances in the cache.] A12.6.8-27
[Transient instances associated with the detached instances are
copied and the copies are added to the persistent instances in the
corresponding place.]
During application of changes, if the JDO implementation can
determine that there were no changes made during detachment, then the
implementation is not required to mark the corresponding instance
dirty. A12.6.8-28 [If it cannot determine if changes were made, then
it must mark the instance dirty.]
A12.6.8-29 [The makeTransactional flag, if set to true, requires the
implementation to mark transactional the persistent instances
corresponding to all instances in the closure of the detached graph.]
No consistency checking is done during attachment. If consistency
checking is required by the application, then flush or
checkConsistency should be called after attaching the instances.
Transient instances in the parameter list are treated the same as
transient instances reachable from parameter instances. That is, a
copy of each such instance is made persistent.
Each instance to be attached must be a transient or detached instance
of a persistence-capable class; or of a class identified in the JDO
metadata as detachable. A12.6.8-30 [If an instance that is not is
attempted to be attached, a JDOUserException is thrown with a nested
JDOUserException for each such instance.]
If a persistent instance is reachable in the closure of instances to
be attached, a JDOUserException is thrown with a nested
JDOUserException for each instance that references any such
persistent instance.
</proposed 12.6.8 to be deleted>
<proposed 12.15>
package javax.jdo.listener;
public interface AttachLifecycleListener
extends InstanceLifecycleListener {
A12.15-13 [void preAttach(InstanceLifecycleEvent event);
}
This method is called before a detached instance is attached, via the
makePersistent method. The source instance is the detached instance.
This method is called before the corresponding jdoPreAttach on the
detached instance.]
A12.15-14 [void postAttach(InstanceLifecycleEvent event);
}
This method is called after a detached instance is attached. The
source instance is the corresponding persistent instance in the
cache; the target instance is the detached instance. This method is
called after the corresponding jdoPostAttach on the persistent
instance.]
</proposed 12.15>
These are the previous contents of the above updates.
<spec 12.6.7>
Make instances persistent
void makePersistent (Object pc);
void makePersistentAll (Object[] pcs);
void makePersistentAll (Collection pcs);A12.5.7-6A [These methods
make a transient instance persistent directly. They must be called in
the context of an active transaction, or a JDOUserException is
thrown.] A12.5.7-6B [They will assign an object identity to the
instance and transition it to persistent-new.] Any transient
instances reachable from this instance via persistent fields of this
instance will become provisionally persistent, transitively. That is,
they behave as persistent-new instances (return true to isPersistent,
isNew, and isDirty). But A12.5.7-6C [at commit time, the reachability
algorithm is run again, and instances made provisionally persistent
that are not currently reachable from persistent instances will
revert to transient.]
A12.5.7-7 [These methods have no effect on parameter persistent
instances already managed by this PersistenceManager.] A12.5.7-8
[They will throw a JDOUserException if the parameter instance is
managed by a different PersistenceManager.]
A12.6.7-1 [If an instance is of a class whose identity type
(application, datastore, or none) is not supported by the JDO
implementation, then a JDOUserException will be thrown for that
instance.]
</spec 12.6.7>
<spec 12.6.8>
Attaching Instances
Object attachCopy(Object detached, boolean makeTransactional);
Collection attachCopyAll(Collection detached, boolean
makeTransactional);
Object[] attachCopyAll(Object[] detached, boolean makeTransactional);
This method applies the changes contained in the collection of
detached instances to the corresponding persistent instances in the
cache and returns a collection of persistent instances that exactly
corresponds to the parameter instances. A12.6.8-25 [The order of
instances in the parameter Collection’s iteration corresponds to the
order of corresponding instances in the returned Collection’s
iteration.]
A12.6.8-26 [Changes made to instances while detached are applied to
the corresponding persistent instances in the cache.] A12.6.8-27
[Transient instances associated with the detached instances are
copied and the copies are added to the persistent instances in the
corresponding place.]
During application of changes, if the JDO implementation can
determine that there were no changes made during detachment, then the
implementation is not required to mark the corresponding instance
dirty. A12.6.8-28 [If it cannot determine if changes were made, then
it must mark the instance dirty.]
A12.6.8-29 [The makeTransactional flag, if set to true, requires the
implementation to mark transactional the persistent instances
corresponding to all instances in the closure of the detached graph.]
No consistency checking is done during attachment. If consistency
checking is required by the application, then flush or
checkConsistency should be called after attaching the instances.
Transient instances in the parameter list are treated the same as
transient instances reachable from parameter instances. That is, a
copy of each such instance is made persistent.
Each instance to be attached must be a transient or detached instance
of a persistence-capable class; or of a class identified in the JDO
metadata as detachable. A12.6.8-30 [If an instance that is not is
attempted to be attached, a JDOUserException is thrown with a nested
JDOUserException for each such instance.]
If a persistent instance is reachable in the closure of instances to
be attached, a JDOUserException is thrown with a nested
JDOUserException for each instance that references any such
persistent instance.
</spec 12.6.8>
<spec 12.15>
package javax.jdo.listener;
public interface AttachLifecycleListener
extends InstanceLifecycleListener {
A12.15-13 [void preAttach(InstanceLifecycleEvent event);
}
This method is called before a detached instance is attached. The
source instance is the detached instance. This method is called
before the corresponding jdoPreAttach on the detached instance.]
A12.15-14 [void postAttach(InstanceLifecycleEvent event);
}
This method is called after a detached instance is attached. The
source instance is the corresponding persistent instance in the
cache; the target instance is the detached instance. This method is
called after the corresponding jdoPostAttach on the persistent
instance.]
</spec 12.15>
Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:[EMAIL PROTECTED]
P.S. A good JDO? O, Gasp!
