Add JDOHelper.isLoaded methods
------------------------------
Key: JDO-483
URL: https://issues.apache.org/jira/browse/JDO-483
Project: JDO
Issue Type: Improvement
Components: api2, api2-legacy
Affects Versions: JDO 2 maintenance release 1
Reporter: Matthew T. Adams
I'm putting forth a proposal to add a method to JDOHelper that allows users to
determine whether or not a given object's field is loaded. There are two
options to handle implementations that won't/can't support loaded field
checking, especially when detached (essentially binary compatible v. non-binary
compatible implementations). Option A adopts an approach that uses Boolean
objects instead of primitives, leaving null as a return value for
implementations that won't/can't support it. Option B takes an exception-based
approach and uses boolean primitives. I'm not sure which I prefer; let's
discuss.
<proposal option="A">
JDOHelper
Checking whether fields are loaded
In some use cases, an application may need to know whether or not a given field
is loaded, for example when marshaling data from detached objects to data
transfer objects (DTOs).
Transient fields
Transient fields are always considered loaded.
Implementation support
Some implementations may not be able to support the ability to check the loaded
status of a field, especially when the object is detached. If the
implementation does not support checking whether a field is loaded, then it
must return null from the isLoaded methods.
Boolean isLoaded(String fieldName, Object pc);
If the field in the most-derived class of the given object's class identified
by the given name is loaded in the given object, Boolean.TRUE is returned. If
the field is not loaded, Boolean.FALSE is returned. If the given field name is
not declared by the given object's class or its direct or indirect
superclasses, then JDOUserException is thrown. If the implementation does not
support checking the loaded state of a field, null is returned. This method is
equivalent to calling isLoaded(fieldName, pc, pc.getClass());
Boolean isLoaded(String fieldName, Object pc, Class c);
This method exists to support the case where a class hides fields defined in a
superclass and an application wants to determine the loaded state of the field
in the superclass. In most cases, the given Class, c, will be identical to the
class of the given object, pc (that is, c == pc.getClass() will return true).
If the class of the given object, pc, is a subclass of the given Class, c, then
the loaded state of the field defined on c is given. If the given Class c is
not identical to the class of or a superclass of the given object, pc, then
JDOUserException is thrown. If the given Class represents an interface, then
JDOUserException is thrown.
If the field of the given class is loaded, Boolean.TRUE is returned. If the
field is not loaded, Boolean.FALSE is returned. If the implementation does not
supporting checking the loaded state of a field, null is returned.
</proposal>
<proposal option="B">
JDOHelper
Checking whether fields are loaded
In some use cases, an application may need to know whether or not a given field
is loaded, for example, when marshaling data from detached objects to data
transfer objects (DTOs).
Transient fields
Transient fields are always considered loaded.
Implementation support
Some implementations may not be able to support the ability to check the loaded
status of a field, especially when the object is detached. If the
implementation does not support checking whether a field is loaded, then it
must throw JDOUnsupportedOperationException from the isLoaded methods.
boolean isLoaded(String fieldName, Object pc);
If the field in the most-derived class of the given object's class identified
by the given name is loaded in the given object, true is returned, otherwise
false is returned. If the given field name is not defined by the given
object's class or its direct or indirect superclasses, then a JDOUserException
is thrown. If the implementation does not support checking the loaded state of
a field, JDOUnsupportedOptionException is thrown. This method is equivalent to
calling isLoaded(fieldName, pc, pc.getClass());
boolean isLoaded(String fieldName, Object pc, Class c);
This method exists to support the case where a class hides fields defined in a
superclass and an application wants to determine the loaded state of the field
in the superclass. In most cases, the given Class, c, will be identical to the
class of the given object, pc. If the class of the given object, pc, is a
subclass of the given Class, c, then the loaded state of the field defined on c
is given. If the given Class c is not identical to the class and is not a
superclass of the given object, pc, then a JDOUserException is thrown. If the
given Class represents an interface, then JDOUserException is thrown.
If the field of the given class is loaded, true is returned, otherwise false is
returned. If the implementation does not support checking the loaded state of
a field, JDOUnsupportedOptionException is thrown.
</proposal>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
