Service Data Objects for Java
Version 3.0
Committee Draft 01
16 December 2008
Specification URIs:
This Version:
http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec-cd01.html
http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec-cd01.doc
http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec-cd01.pdf (Authoritative)
Previous Version:
Latest Version:
http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec.html
http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec.doc
http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec.pdf (Authoritative)
Technical Committee:
OASIS Service Data Objects TC
Chair(s):
Ron Barack
Frank Budinsky
Editor(s):
name]
name]
Related Work:
This specification replaces or supercedes:
· OSOA Service Data Objects for Java Specification, Version 2.1
This specification is related to:
· Service Data Objects Version 3.0
Declared XML Namespaces:
http://docs.oasis-open.org/ns/opencsa/sdo/java/200812
Abstract:
SDO provides a unifying API and architecture that allows SOA applications handle data from heterogeneous sources, including relational databases, Web services, and enterprise information systems. This document describes the API for programming using SDO on a Java platform.
Status:
This Working Draft is an editor’s draft. It does not necessarily represent the consensus of the committee.
Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at at http://www.oasis-open.org/committees/sdo/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page ((http://www.oasis-open.org/committees/sdo/ipr.php).
The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/sdo/.
Notices
Copyright © OASIS® 2003, 2008. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS", is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
Table of Contents
1 Introduction 7
1.1 Terminology 7
1.2 Normative References 7
1.3 Non-Normative References 8
2 Java API 9
2.1 DataObject 9
2.1.1 Type Conversion 9
2.1.2 Open Content DataObject Properties 10
2.1.3 DataObject Interface 10
2.1.4 DataObject Accessor Exceptions 12
2.2 ChangeSummary 12
2.2.1 Old Values 12
2.2.2 ChangeSummary Interface 13
2.3 Sequence 13
2.3.1 Sequence Interface 13
2.4 Type 14
2.4.1 InstanceClass 14
2.4.2 Type Interface 14
2.5 Property 15
2.5.1 Property Interface 15
2.6 HelperContext 15
2.6.1 Default HelperContext 15
2.6.2 HelperContext Interface 15
2.7 DataFactory 15
2.7.1 DataFactory Interface 15
2.8 TypeHelper 16
2.8.1 TypeHelper Interface 16
2.9 JavaHelper 16
2.9.1 JavaHelper Interface 16
2.9.2 Example Using the JavaHelper Interface 17
2.10 CopyHelper 17
2.10.1 CopyHelper Interface 17
2.11 EqualityHelper 17
2.11.1 EqualityHelper Interface 17
2.12 XMLHelper 17
2.12.1 Default XMLHelper 17
2.12.2 XMLHelper Interface 18
2.13 XMLDocument 19
2.13.1 XMLDocument Interface 19
2.14 SDOContentHandler 19
2.14.1 SDOContentHandler Interface 19
2.15 SDOSource 19
2.15.1 SDOSource Interface 19
2.16 SDOResult 20
2.16.1 SDOResult Interface 20
2.17 XSDHelper 20
2.17.1 Default XSDHelper 20
2.17.2 XSDHelper Interface 20
2.18 DataHelper 21
2.18.1 DataHelper Interface 21
2.19 SDO 21
2.19.1 Default HelperContext 21
2.19.2 HelperContext by Identifier 21
2.19.3 Default HelperContextFactory 22
2.19.4 Implementation Specific HelperContextFactory 22
2.20 HelperContextFactory 22
2.20.1 Creating a HelperContext 22
2.21 Environment 22
3 Java Interface Specification 23
3.1 Goals and Limitations 23
3.2 Mapping Principles 23
3.3 Associating SDO Types with Static SDOs 24
3.4 Default Mapping between SDO Types and Static SDOs 24
3.4.1 Use of enum Types 26
3.5 Generation of SDO Types from Static SDOs 26
3.6 Customizing the Mapping between SDO Types and Static SDOs 28
3.6.1 @SdoType 28
3.6.2 @SdoOpenContentProperty 29
3.6.3 @SdoProperty 30
3.6.4 @SdoDefault 31
3.6.5 @SdoKey 32
3.6.6 @SdoXmlProperty 32
3.6.7 @SdoXmlType 32
3.7 Package Level Annotations 33
3.7.1 @SdoUri 33
3.7.2 @SdoSeePackage 33
3.7.3 @SdoDataType 34
3.7.4 Use of @SdoOpenContentProperty 35
3.8 Example of Static SDO interfaces 35
4 Java Serialization of DataObjects 39
5 SDO Model for Types and Properties 42
5.1 Java Related Properties 42
6 Standard SDO Types 43
6.1 SDO Data Types 43
6.1.1 Conversion from java.util.Date to SDO type String 45
6.1.2 Conversion from SDO type String to SDO type Date 45
6.1.3 Conversion from a String-based SDO Date/Time type to Calendar 46
6.1.4 Conversion from Calendar to a String-based SDO Date/Time type 46
6.1.5 Conversion from SDO Date to a String-based SDO Date/Time type 46
6.1.6 Conversion from String to a String-based SDO Date/Time type 46
6.2 SDO Abstract Types 47
6.3 SDO Type and Property constraints 47
7 XML Schema to SDO Mapping 48
7.1 Mapping Principles 48
7.2 Mapping of XSD to SDO Types and Properties 48
7.2.1 XML Simple Types 49
XML Complex Types 50
7.2.2 50
7.3 Mapping of XSD Built in Data Types 51
7.3.1 Dates 51
7.4 Examples of XSD to SDO Mapping 52
7.4.1 Example of sdo annotations 52
8 Generation of XSD from SDO Type and Property 54
A. Examples 55
A.1 Accessing DataObjects using SDO Path 56
A.2 Accessing DataObjects via Property Index 58
A.3 Accessing the Contents of a Sequence 59
A.4 Serializing/Deserializing a DataObject 60
A.5 Using Type and Property with DataObjects 61
A.6 Creating XML from Data Objects 63
A.7 Creating open content XML documents 64
A.8 Web Services Client using XMLHelper 65
A.9 Web service and Data Graph Example 66
B. Acknowledgements 69
C. Non-Normative Text 70
D. Revision History 71
1 Introduction 7
1.1 Terminology 7
1.2 Normative References 7
1.3 Non-Normative References 8
2 Java API 9
2.1 DataObject 10
2.1.1 Type Conversion 10
2.1.2 Open Content DataObject Properties 10
2.1.3 DataObject Interface 11
2.1.4 DataObject Accessor Exceptions 13
2.2 ChangeSummary 13
2.2.1 Old Values 13
2.2.2 ChangeSummary Interface 14
2.3 Sequence 14
2.3.1 Sequence Interface 14
2.4 Type 15
2.4.1 Type Contents 15
2.4.2 Type Interface 15
2.5 Property 15
2.5.1 Property Interface 15
2.6 HelperContext 16
2.6.1 Default HelperContext 16
2.6.2 Non-Default HelperContext 16
2.6.3 HelperContext Interface 16
2.7 DataFactory 16
2.7.1 Default DataFactory 16
2.7.2 DataFactory Interface 16
2.8 TypeHelper 17
2.8.1 Default TypeHelper 17
2.8.2 TypeHelper Interface 17
2.9 JavaHelper 17
2.9.1 JavaHelper Interface 17
2.9.2 Using the JavaHelper Interface 18
2.10 CopyHelper 18
2.10.1 Default CopyHelper 18
2.10.2 CopyHelper Interface 18
2.11 EqualityHelper 18
2.11.1 Default EqualityHelper 18
2.11.2 EqualityHelper Interface 18
2.12 XMLHelper 19
2.12.1 Default XMLHelper 19
2.12.2 XMLHelper Interface 19
2.13 XMLDocument 20
2.13.1 XMLDocument Interface 20
2.14 SDOContentHandler 20
2.14.1 SDOContentHandler Interface 20
2.15 SDOSource 20
2.15.1 SDOSource Interface 20
2.16 SDOResult 21
2.16.1 SDOResult Interface 21
2.17 XSDHelper 21
2.17.1 Default XSDHelper 21
2.17.2 XSDHelper Interface 21
2.18 DataHelper 22
2.18.1 Default DataHelper 22
2.18.2 DataHelper Interface 22
2.19 SDO 23
2.19.1 Default HelperContext 23
2.19.2 HelperContext by Identifier 23
2.19.3 Default HelperContextFactory 23
2.19.4 Implementation Specific HelperContextFactory 23
HelperContextFactory 23
2.20 23
2.20.1 Creating a HelperContext 23
2.21 Environment 24
3 Java Interface Specification 25
3.1 Goals and Limitations 25
3.2 Mapping Principles 25
3.3 Associating SDO Types with Static SDOs 26
3.4 Default Mapping between SDO Types and Static SDOs 26
3.5 Use of enum Types 28
3.6 Generation of SDO Types from Static SDOs 28
3.7 Customizing the Mapping between SDO Types and Static SDOs 30
3.7.1 @SdoType 30
3.7.2 @SdoOpenContentProperty 31
3.7.3 @SdoProperty 32
3.7.4 @SdoDefault 33
3.7.5 @SdoKey 33
3.7.6 @SdoXmlProperty 34
3.7.7 @SdoXmlType 34
3.8 Package Level Annotations 34
3.8.1 @SdoUri 35
3.8.2 @SdoSeePackage 35
3.8.3 @SdoDataType 36
3.8.4 Use of @SdoOpenContentProperty 36
3.9 Example of Static SDO interfaces 37
4 Java Serialization of DataObjects 41
5 SDO Model for Types and Properties 45
5.1 Java Related Properties 45
6 Standard SDO Types 46
6.1 SDO Data Types 46
6.1.1 Conversion from SDO type Date to SDO type String 48
6.1.2 Conversion from SDO type String to SDO type Date 48
6.1.3 Conversion from a String-based SDO Date/Time type to Calendar 49
6.1.4 Conversion from Calendar to a String-based SDO Date/Time type 49
6.1.5 Conversion from SDO Date to a String-based SDO Date/Time type 49
6.1.6 Conversion from String to a String-based SDO Date/Time type 49
6.1.7 Conversion between Calendar/Date and Duration 49
6.2 SDO Abstract Types 50
6.3 SDO Type and Property constraints 50
7 XML Schema to SDO Mapping 51
7.1 Mapping Principles 51
7.2 Mapping of XSD to SDO Types and Properties 51
7.2.1 XML Schemas 52
7.2.2 XML Simple Types 52
7.2.3 XML Complex Types 53
7.3 Mapping of XSD Built in Data Types 54
7.3.1 Dates 55
7.4 Examples of XSD to SDO Mapping 55
7.4.1 Example of sdo annotations 55
8 Generation of XSD from SDO Type and Property 57
A. Examples 58
A.1 Accessing DataObjects using SDO Path 59
A.2 Accessing DataObjects via Property Index 61
A.3 Accessing the Contents of a Sequence 62
A.4 Serializing/Deserializing a DataObject 63
A.5 Using Type and Property with DataObjects 64
A.6 Creating XML from Data Objects 66
A.7 Creating open content XML documents 67
A.8 Web Services Client using XMLHelper 68
A.9 Web service and Data Graph Example 69
B. Acknowledgements 72
C. Non-Normative Text 73
D. Revision History 74
SDO Java Specification Version 3.0 16 December 2008
Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 28 of 75
1 Introduction
As described in the core SDO specification [SDO], SDO provides a unifying API and architecture that allows SOA applications handle data from heterogeneous sources, including relational databases, Web services, and enterprise information systems.
This document builds on the core SDO specification by describing the interfaces for programming using SDO on the Java platform. Details on the mapping of SDO data to Java are also provided.
1.1 Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
In addition to the ones described in [SDO], the following standard namespace URI is associated with this specification:
· “http://docs.oasis-open.org/ns/opencsa/sdo/java/200812” contains Java specific SDO types and properties. Previous implementations of SDO used “commonj.sdo/java” for this namespace. Implementations may choose to continue to support “commonj.sdo/java” as an alias URI for this namespace.
This specification also uses the additional default mapping for the following XML namespace prefix:
· “sdoj” is mapped to namespace “http://docs.oasis-open.org/ns/opencsa/sdo/java/200812”
1.2 Normative References
[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
[SDO] F. Budinsky, et al., Service Data Object Specification Version 3.0, http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec.pdf, OASIS Service Data Object Specification Version 3.0, XXX 2008