Re: [sdo] ISSUE 164: Questions to Java Spec

[Bryan Aupperle <aupperle@us.ibm.com>]

Comments in-line

Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect

Research Triangle Park,  NC 
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com

From:	"Barack, Ron" <ron.barack@sap.com>
To:	"sdo@lists.oasis-open.org" <sdo@lists.oasis-open.org>
Date:	09/01/2009 07:17 AM
Subject:	[sdo] ISSUE 164:  Questions to Java Spec

---

Hi Everyone, 
 
I've started work on the Java spec, and have
a could of comments/ questions, that I'd like to address before proceeding.
  The questions are mostly directed at Bryan, who did the great work
splitting the 2.1.1 spec, so that we have a Java spec in any form at all…
 
Section 2 (JavaAPI), introduction…  This
section basically repeats the wording in chapter 4 of the core spec.  I
think we should remove the redundant wording and focus only on the differences
to the core spec (eg, the need to integrate with other frameworks, the
introduction of JavaHelper, the use of reflection).

<BEA>  It's been a
while since I did the split and I do not recall the decision-making that
lead to the current text, but I agree with removing redundant text </BEA>
 
Section 2.1, and on-words…I have the impression
that Brian thought that the SDO type integer maps to java.lang.Integer
and not to BigInteger, and therefore there is a discussion of wrapper types
and some special wording relating to BigInteger and BigDecimal.  Actually,
though, wrapper types don't appear in the DataObject interface (as they
would be redundent, thanks to autoboxing), and the methods getBigInteger,
getBigDecimal map perfectly to the get<T> pattern described in the
core spec, and IMO do not require any special discussion.

<BEA> You are correct in
your impression...  </BEA>
 
I would also like to move the discussion
of default values for primitive types to the Java spec.
 
Here is my proposed text for the beginning
of Chapter 2.
 
I'd like some feedback from the group as
to whether we are OK with this approach
Ron
 
1       Java
API
The SDO 3.0 Java API requires a minimum Java
Development Kit, version 1.5.0 or higher.
The SDO programming model, as defined in
the core SDO specification [SDO] is implemented in Java as a set
of interfaces.  These interfaces implement the functionality of the
core SDO specification, along with some extensions specific to the Java
environment.
Among the extensions that SDO’s Java API
provides beyond the SDO Core Specification is the JavaHelper interface.
 Additional methods have been added to some other helpers, notably
XMLHelper, which are intended to enable integration with existing frameworks.
 Another notable extension that the SDO 3.0 Java API provides provides
beyond the SDO core is the ability to derive SDO types and properties by
introspecting Java classes. 
The remainder of this section describes the
implementation of the SDO programming model in Java, including any extensions,
optimizations, and specializations.  For details of the interfaces,
refer to the core SDO specification.
1.1     DataObject
The DataObject interface in Java contains
type specific accessors (get<T> and set<T> methods) for each
of the standard DataTypes listed in Chapter 11 of the Core Specification
[SDO]. The table in section 6.1: SDO Data Types defines the mapping
between standard Java types and the SDO types defined in the core SDO specification
[SDO].   Note that Java’s autoboxing feature also allows the
Java object representation (e.g., java.lang.Integer) to be used where the
API calls for a primitive value (e.g., int).
1.1.1   Type Conversion
The set of standard converstions implicit
in the various get<T> and set<T> methods is implied by the
table in Chapter 11 of the core specification.  In addition to the
behavior defined in the core specification, the following rules apply specifically
for type conversions in Java.
When get(property) is called on an unset
property for which the default value is null (there is no default value)
and the instanceClass of the property is a Java object, a Java Implemenation
of SDO MUST return null.  [JAV02010101]  When the instanceClass
is a primitive Java type (e.g., int, boolean, float), then a Java Implementation
of SDO MUST return the corresponding default value: [JAV02010102]

• “false” if the type is “boolean”
• “0” if the type is “byte”, “char”, double”, “float”, “int”, “short”, “long”

This
value is also used as a starting point if a conversion is necessary (for
example in the case of get<T> methods).
When a get<T>() 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. [JAV02010102]
 If the 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.
 If the list is empty an the target type is primitive, then a Java
implementation of SDO MUST return the same value as for an unset property,
as described above [JAV02010103] 
When a set<T> method is invoked on
a many-valued property and <T> is not <List>, a Java Implementation
of SDO MUST set the the property to a List of length 1 where the single
element is the (possibly converted) parameter value [JAV02010104].
Note that when calling the primitive DataObject.set()
methods, no automatic conversion is performed. In this case, type conversion
can be explicitly performed by calling DataHelper.convert() before calling
the set() method. For example:
 
dataObject.set(property, dataHelper.convert(property,
value));