Here is the API of the generic setList methods. I
believe
the JavaDoc is sufficient, and we do not need any modifications to the
text.
/**
* Converts (as necessary) the elements of the supplied list type from
the
specified class to the
* instanceClass of the property identified by the specified and sets
the
property’s value accordingly.
* @param sourceClass if the conversion is supported, the value will be
converted
* from this class.
* @param path the path to a valid object and property.
* @see #set(String, Object)
*/
<T> void setList(Class<T> sourceClass, String path,
List<T>
sourceList);
/**
* Converts (as necessary) the elements of the supplied list type from
the
specified class to the
* instanceClass of the property having the specified property index and
sets
the property’s value accordingly.
* @param sourceClass if the conversion is supported, the value will be
converted
* from this class.
* @param propertyIndex the index of the property.
* @see #set(int, Object)
*/
<T> void setList(Class<T> sourceClass, int propertyIndex,
List<T> sourceList);
/**
* Converts (as necessary) the elements of the supplied list type from
the
specified class to the
* instanceClass of the specified property and sets the property’s value
accordingly.
* @param sourceClass if the conversion is supported, the value will be
converted
* from this class.
* @param property the property to get.
* @see #set(Proprty, Object)
*/
<T> void setList(Class<T> sourceClass, Property property,
List<T>
sourceList);
As
promised, here is my proposal for resolving SDO-27. I don’t think
there is too much that is controversial, but maybe we can discuss why
getList(Class<T>…) methods have to return live lists, and whether
setList(Class<T>) methods are needed.
____________________________________________________________________________________________________________________________+
Add
a sentence (here in bold) to the core spec, section 4.1.3,
second
paragraph. For context, the entire paragraph is reproduced here:
When
a DataObject’s typed accessors get<T>() are invoked, a type
conversion is necessary if the value is not already an instance of the
requested type T. Similarly, when calling set<T>() methods, type
conversion is necessary if the specified property is not of type T.
Languages (such as Java) that support the reflection can provide
language specific means of specifying the target type T. Regardless
of how the target type T is specified, the same conversion rules apply.
Add
the following text to the Java spec, section 2.1.1, around line 83.
The
new text is again in bold
The
Java API supports two mechanisms through which application programs can
force
conversion of property values to a target class: through the various
get<T> methods, and through the use of the various getter methods
that
make use of generics, i.e., methods of the form <T> T
get(Class<T>,…). When such a method is invoked
on a
many-valued property and <T> is not <List>, then, if the
property’s value is a List of length 1, a Java Implementation of SDO
MUST
return the item in the list converted, if necessary, to the target
type. [JAV02010106]
If a property’s value is an empty
list and the target type is not a primitive type, then a Java
Implementation of
SDO MUST return null. [JAV02010103]
If a
property’s value is an empty list and the target type is primitive,
then
a Java implementation of SDO MUST return the same value as for an unset
property. [JAV02010104]
The
Java API supports two mechanisms through which application programs can
force
conversion of supplied values to the class appropriate to a property:
through
the various set<T> methods, and through the use of the various
getter
methods that make use of generics, i.e., methods of the form <T>
void
set(Class<T>,…, T value). When such a method is invoked
on a
many-valued property and <T> is not <List>, a Java
Implementation
of SDO MUST set the property to a List of length 1 where the single
element is
the (possibly converted) parameter value [JAV02010105].
Add
the following text to the Java spec at the end of section 2.1.1
SDO’s
Java API also provides methods that support conversion of elements in a
list. The methods
<T>
List<T>
getList(Class<T> targetClass, Property property);
<T>
List<T>
getList(Class<T> targetClass, int propertyIndex);
<T>
List<T>
getList(Class<T> targetClass, String propertyName);
return
lists in which each element is converted from the corresponding element
of the
underlying property. A Java implementation of SDO MUST create the
lists
such that modifications to them (such as adding or removing elements)
modifies the value of the property and are visible in any other lists
that
represent the same property’s value. . [JAV02010106]
DataObject
gets 9 new methods. 3 single object getters, 3 single object setters,
and
3 list getters.
* Converts the value of the property identified by the specified path
to the
provided
* @param targetClass if the conversion is supported, the property value
will be
converted
* @param path the path to a valid object and property.
* @return the converted value of the specified property.
<T> T get(Class<T> targetClass, String path);
* Converts the value of the property identified by the specified
property index
to the provided
* @param targetClass if the conversion is supported, the property value
will be
converted
* @param propertyIndex the index of the property.
* @return the converted value of the specified property.
<T> T get(Class<T> targetClass, int propertyIndex);
* Converts the value of the specified property to the provided target
class.
* @param targetClass if the conversion is supported, the property value
will be
converted
* @param property the property to get.
* @return the converted value of the specified property.
<T> T get(Class<T> targetClass, Property property);
* Converts the provided value, and uses it to set the value of the
property
identified by the specified path.
* @param targetClass if the conversion is supported, the value will be
converted
* @param path the path to a valid object and property.
* @param value the new value for the property.
* @see #set(String, Object)
<T> void set(Class<T> sourceClass, String path, T value);
* Converts the provided value, and uses it to set the value of the
property
identified by the specified property index.
* @param targetClass if the conversion is supported, the value will be
converted
* @param propertyIndex the index of the property.
* @param value the new value for the property.
<T> void set(Class<T> sourceClass, int propertyIndex, T
value);
* Converts the provided value, and uses it to set the value of the
property.
* @param targetClass if the conversion is supported, the value will be
converted
* @param property the property to set.
* @param value the new value for the property.
* @see #set(Property, Object)
<T> void set(Class<T> sourceClass, Property property, T
value);
* Returns the value of the property identified by the specified path as
the
specified type of list.
* Updates through the List interface operate on the current values of
the
DataObject.
*
@param
targetClass if the conversion is supported, the elements of the list
will be
converted
* @param path the path to a valid object and property.
* @return the <code>List</code> value of the specified
property.
<T> List<T> getList(Class<T> targetClass, String
path);
* Returns the value of the property identified by the specified
property index
as the specified type of list.
* Updates through the List interface operate on the current values of
the
DataObject.
*
@param
targetClass if the conversion is supported, the elements of the list
will be
converted
* @param propertyIndex the index of the property.
* @return the <code>List</code> value of the specified
property.
<T> List<T> getList(Class<T> targetClass, int
propertyIndex);
* Returns the value of the specified property as the specified type of
list.
* Updates through the List interface operate on the current values of
the
DataObject.
*
@param
targetClass if the conversion is supported, the elements of the list
will be
converted
* @param property the property to get.
* @return the <code>List</code> value of the specified
property.
<T> List<T> getList(Class<T> targetClass, Property
property);