Service Data Objects
Version 3.0
Committee Draft 01
16 December 2008
Specification URIs:
This Version:
http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec-cd01.html
http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec-cd01.doc
http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec-cd01.pdf (Authoritative)
Previous Version:
Latest Version:
http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec.html
http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec.doc
http://docs.oasis-open.org/opencsa/sdo/sd0-core-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 for Java Version 3.0
Declared XML Namespaces:
http://docs.oasis-open.org/ns/opencsa/sdo/200812
http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812
Abstract:
SDO provides a unifying API and architecture that allows SOA applications to handle data from heterogeneous sources, including relational databases, Web services, and enterprise information systems. This document describes the architecture and programming model for SDO.
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 8
1.1 Terminology 8
1.2 Normative References 8
1.3 Non-Normative References 9
2 Overview 10
2.1 Key Concepts 10
2.2 Requirements 10
2.3 Organization of this Document 12
3 Architecture 13
4 Programming Model 16
4.1 DataObject 17
4.1.1 DataObject Concepts 18
4.1.2 DataObject Values and Properties 18
4.1.3 Type Conversion 18
4.1.4 Many-valued DataObject Properties 19
4.1.5 Determining whether a Property is Set 19
4.1.6 Containment 20
4.1.7 Creating and Deleting DataObjects 21
4.1.8 Sequenced DataObjects 21
4.1.9 Open Content DataObject Properties 21
4.1.10 Property Indexes 23
4.1.11 Current State for a DataObject 23
4.1.12 DataObject Interface 24
4.1.13 DataObject Accessor Exceptions 24
4.1.14 Validation of Facets and Constraints 26
4.2 DataGraph 26
4.2.1 Creating DataGraphs 26
4.2.2 Modifying DataGraphs 27
4.2.3 Accessing Types 27
4.2.4 DataGraph Interface 27
4.3 ChangeSummary 27
4.3.1 Starting and Stopping Change Logging 28
4.3.2 Scope 28
4.3.3 Old Values 28
4.3.4 Sequenced DataObject 28
4.3.5 Serialization and Deserialization 28
4.3.6 Associating ChangeSummaries with DataObjects 29
4.3.7 ChangeSummary Interface 30
4.4 Sequence 30
4.4.1 Unstructured Text 30
4.4.2 Using Sequences 30
4.4.3 Comparing Sequences with DataObjects 31
4.4.4 Sequence Methods 31
4.4.5 Sequence Interface 32
4.5 Type 32
4.5.1 Mapping SDO Types to Programming and Data Modeling Languages 32
4.5.2 Type Contents 33
4.5.3 Name Uniqueness 33
4.5.4 Compatibility Between Types 33
4.5.5 Data Types 34
4.5.6 Data Type Wrappers 34
4.5.7 Multiple Inheritance 34
4.5.8 Type Instance Properties 35
4.5.9 Type Methods 35
4.5.10 Type Interface 36
4.6 Property 36
4.6.1 Property Index 37
4.6.2 Containment 37
4.6.3 Key Properties 37
4.6.4 Read-Only Properties 38
4.6.5 Nullable Properties 39
4.6.6 Open Content Properties 39
4.6.7 Property Instance Properties 39
4.6.8 Property Methods 39
4.6.9 Property Interface 40
4.7 DataFactory 40
4.7.1 Default DataFactory 40
4.7.2 Creating DataObjects 40
4.7.3 DataFactory Interface 41
4.8 TypeHelper 41
4.8.1 Default TypeHelper 41
4.8.2 Defining SDO Types Dynamically 42
4.8.3 Using SDO Dynamic Types 42
4.8.4 Defining and Using Open Content Properties 43
4.8.5 TypeHelper Methods 43
4.8.6 TypeHelper Interface 44
4.9 CopyHelper 44
4.9.1 Default CopyHelper 44
4.9.2 Shallow Copies 44
4.9.3 Deep Copies 45
4.9.4 CopyHelper Methods 45
4.9.5 CopyHelper Interface 45
4.10 EqualityHelper 45
4.10.1 Default EqualityHelper 45
4.10.2 EqualityHelper Methods 45
4.10.3 EqualityHelper Interface 46
4.11 XMLHelper 46
4.11.1 Default XMLHelper 46
4.11.2 Loading and Saving XML Documents 46
4.11.3 XML Schemas 46
4.11.4 Creating DataObjects from XML 47
4.11.5 Creating DataObjects from XML documents 47
4.11.6 Creating XML without an XSD 48
4.11.7 XMLHelper Methods 49
4.11.8 Orphan Serialization 49
4.11.9 XMLHelper Interface 50
4.12 XMLDocument 50
4.12.1 Example XMLDocument 50
4.12.2 XMLDocument Methods 51
4.12.3 XMLDocument Interface 51
4.13 XSDHelper 52
4.13.1 Default XSDHelper 52
4.13.2 Generating XSDs 52
4.13.3 XSDHelper Methods 52
4.13.4 XSDHelper Interface 53
4.14 DataHelper 53
4.14.1 Default DataHelper 53
4.14.2 DataHelper Interface 53
4.14.3 The Project method 54
4.14.4 Keys and Projection 55
4.15 HelperContext 57
4.15.1 Default HelperContext 58
4.15.2 HelperContext Interface 58
5 SDO Model for Types and Properties 59
5.1 Type Properties 59
5.2 Property Properties 60
5.3 XML Related Properties 60
6 Standard SDO Types 62
6.1 SDO Data Types 62
6.1.1 Conversion from SDO type Bytes to SDO type String 64
6.1.2 Conversion from SDO type String to SDO type Bytes 64
6.1.3 Conversion between Character and String 64
6.2 SDO Abstract Types 64
6.3 SDO Model Types 65
6.4 SDO Type and Property constraints 66
7 XML Schema to SDO Mapping 68
7.1 Mapping Principles 68
7.2 Generating static SDOs from an XSD 69
7.3 Mapping of XSD to SDO Types and Properties 69
7.3.1 XML Schemas 70
7.3.2 XML Simple Types 71
7.3.3 XML Complex Types 72
7.4 Mapping of XSD Attributes and Elements to SDO Properties 75
7.4.1 Mapping of XSD Attributes 76
7.4.2 Mapping of XSD Elements 78
7.5 Mapping of XSD Built in Data Types 82
7.5.1 Conversion between XSD QName and SDO URI 83
7.5.2 Dates 84
7.6 Examples of XSD to SDO Mapping 84
7.6.1 Example of SDO Annotations 87
7.7 XML use of Sequenced Data Objects 88
7.8 XSD Mapping Details 88
7.9 Compliance 89
7.10 Corner cases 89
7.11 XML without Schema to SDO Type and Property 89
8 Generation of XSD from SDO Type and Property 91
8.1 Mapping of SDO DataTypes to XSD Built in Data Types 95
8.2 Generating XSD from Types using Keys 96
8.3 Example Generated XSD 97
8.4 Customizing Generated XSDs 99
9 DataGraph XML Serialization 100
10 SDO Path Expression for DataObjects 102
11 ChangeSummary XML format 105
11.1 Example Use of ChangeSummary on a DataObject 108
12 DataType Conversions 109
A. Complete Data Graph Examples 112
A.1 Complete Data Graph Serialization 112
A.2 Complete Data Graph for Company Example 112
A.3 Complete Data Graph for Letter Example 113
A.4 Complete WSDL for Web services Example 113
B. Acknowledgements 115
C. Non-Normative Text 116
D. Revision History 117
SDO Core Specification Version 3.0 16 December 2008
Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 60 of 117
1 Introduction
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 architecture and programming model for SDO.
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].
The following standard namespace URIs are associated with this specification:
· “http://docs.oasis-open.org/ns/opencsa/sdo/200812” contains the standard SDO types and properties. Previous implementations of SDO used “commonj.sdo” for this namespace. Implementations may choose to continue to support “commonj.sdo” as an alias URI for this namespace.
· “http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812” contains XML specific SDO types and properties. Previous implementations of SDO used “commonj.sdo/xml” for this namespace. Implementations may choose to continue to support “commonj.sdo/xml” as an alias URI for this namespace.
When not explicitly stated, this specification uses a default mapping for each of the following XML namespace prefixes:
· “sdo” is mapped to namespace “http://docs.oasis-open.org/ns/opencsa/sdo/200812”
· “sdox” is mapped to namespace “http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812”
· “xsd” is mapped to namespace “http://www.w3.org/2001/XMLSchema (the default prefix can also be used when the context is clear)
· “xsi” is mapped to namespace “http://www.w3.org/2001/XMLSchema-instance
Although this specification is language-neutral, for simplicity we use the Java programming language to illustrate code patterns and for the examples. Language-specific specifications may reproduce some of these examples or patterns, in cases where the language mapping is not obvious.
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.
[Schema1] XML Schema Part 1: Structures, http://www.w3.org/TR/xmlschema-1
[Schema2] XML Schema Part 2: Datatypes http://www.w3.org/TR/xmlschema-2
[XPath] XPath 1.0 specification http://www.w3.org/TR/xpath
[SDOJava] F. Budinsky, et al., Service Data Objects For Java Specification Version 3.0, http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec.pdf, OASIS Service Data Objects For Java Specification Version 3.0, XXX 2008
1.3 Non-Normative References
[NextGen] Next-Generation Data Programming with Service Data Objects,
Any one of:
· http://www.ibm.com/developerworks/library/specification/ws-sdo/
· http://oracle.com/technology/webservices/sca
· https://www.sdn.sap.com/
2 Overview
Service Data Objects (SDO) is a data programming architecture and an API.
The main purpose of SDO is to simplify data programming, so that developers can focus on business logic instead of the underlying technology.
SDO simplifies data programming by:
unifying data programming across data source types
providing support for common application patterns
enabling applications, tools and frameworks to more easily query, view, bind, update, and introspect data.
For a high-level overview of SDO, see the white paper titled “Next-Generation Data Programming: Service Data Objects” [NextGen].
2.1 Key Concepts
The key concepts in the SDO architecture are the Data Object, the Data Graph and the Data Access Services (DAS).
A Data Object holds a set of named properties, each of which contains either a simple data-type value or a reference to another Data Object. The Data Object API provides a dynamic data API for manipulating these properties.
The data graph provides an envelope for Data Objects, and is the normal unit of transport between components. Data graphs can track changes made to the graph of Data Objects. Changes include inserting Data Objects, deleting Data Objects and modifying Data Object property values.