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);
From: Barack, Ron [mailto:ron.barack@sap.com]
Sent: Montag, 18. Januar 2010 12:10
To: sdo@lists.oasis-open.org
Subject: [sdo] ISSUE 27: Add generics to SDO APIs
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);