1
2Service Data Objects
3Version 3.0
4Committee Draft 021
516 29 December September13 October 20098
6Specification URIs: 7This Version: 8 http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec-cd01.html 9 http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec-cd01.doc 10 http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec-cd01.pdf (Authoritative) 11Previous Version: 12Latest Version: 13 http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec.html 14 http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec.doc 15 http://docs.oasis-open.org/opencsa/sdo/sd0-core-3.0-spec.pdf (Authoritative) 16Technical Committee: 17 OASIS Service Data Objects TC 18Chair(s): 19 Ron Barack 20 Frank Budinsky 21Editor(s): 22 [Editor name] 23 [Editor name] 24Related Work: 25 This specification replaces or supercedes: 26 OSOA Service Data Objects for Java Specification, version 2.1 27 This specification is related to: 28 Service Data Objects for Java Version 3.0 29Declared XML Namespaces: 30 http://docs.oasis-open.org/ns/opencsa/sdo/200812 31 http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812 32Abstract: 33 SDO provides a unifying API and architecture that allows SOA applications to handle data from 34 heterogeneous sources, including relational databases, Web services, and enterprise information 35 systems. This document describes the architecture and programming model for SDO. 36Status: 37 This Working Draft is an editor’s draft. It does not necessarily represent the consensus of the 38 committee.
1SDO Core Specification Version 3.0 16 December 2008 2Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 1 of 141 39 Technical Committee members should send comments on this specification to the Technical 40 Committee’s email list. Others should send comments to the Technical Committee by using the 41 “Send A Comment” button on the Technical Committee’s web page at at http://www.oasis- 42 open.org/committees/sdo/. 43 For information on whether any patents have been disclosed that may be essential to 44 implementing this specification, and any offers of patent licensing terms, please refer to the 45 Intellectual Property Rights section of the Technical Committee web page ((http://www.oasis- 46 open.org/committees/sdo/ipr.php). 47 The non-normative errata page for this specification is located at http://www.oasis- 48 open.org/committees/sdo/.
4SDO Core Specification Version 3.0 16 December 2008 5Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 2 of 141 49Notices
50Copyright © OASIS® 2003, 2008. All Rights Reserved. 51All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual 52Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. 53This document and translations of it may be copied and furnished to others, and derivative works that 54comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, 55and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice 56and this section are included on all such copies and derivative works. However, this document itself may 57not be modified in any way, including by removing the copyright notice or references to OASIS, except as 58needed for the purpose of developing any document or deliverable produced by an OASIS Technical 59Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must 60be followed) or as required to translate it into languages other than English. 61The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors 62or assigns. 63This document and the information contained herein is provided on an "AS IS" basis and OASIS 64DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 65WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 66OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 67PARTICULAR PURPOSE. 68OASIS requests that any OASIS Party or any other party that believes it has patent claims that would 69necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, 70to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to 71such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that 72produced this specification. 73OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of 74any patent claims that would necessarily be infringed by implementations of this specification by a patent 75holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR 76Mode of the OASIS Technical Committee that produced this specification. OASIS may include such 77claims on its website, but disclaims any obligation to do so. 78OASIS takes no position regarding the validity or scope of any intellectual property or other rights that 79might be claimed to pertain to the implementation or use of the technology described in this document or 80the extent to which any license under such rights might or might not be available; neither does it represent 81that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to 82rights in any document or deliverable produced by an OASIS Technical Committee can be found on the 83OASIS website. Copies of claims of rights made available for publication and any assurances of licenses 84to be made available, or the result of an attempt made to obtain a general license or permission for the 85use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS 86Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any 87information or list of intellectual property rights will at any time be complete, or that any claims in such list 88are, in fact, Essential Claims. 89The name "OASIS", is a trademark of OASIS, the owner and developer of this specification, and should 90be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and 91implementation and use of, specifications, while reserving the right to enforce its marks against 92misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
7SDO Core Specification Version 3.0 16 December 2008 8Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 3 of 141 93Table of Contents
94 951 Introduction ...... 8 96 1.1 Terminology ...... 8 97 1.2 Normative References ...... 8 98 1.3 Non-Normative References ...... 9 992 Overview ...... 10 100 2.1 Key Concepts ...... 10 101 2.2 Requirements ...... 10 102 2.3 Organization of this Document ...... 12 1033 Architecture ...... 13 1044 Programming Model ...... 15 105 4.1 DataObject ...... 16 106 4.1.1 DataObject Concepts ...... 17 107 4.1.2 DataObject Values and Properties ...... 17 108 4.1.3 Type Conversion ...... 17 109 4.1.4 Many-valued DataObject Properties ...... 18 110 4.1.5 Determining whether a Property is Set ...... 18 111 4.1.6 Containment ...... 19 112 4.1.7 Creating and Deleting DataObjects ...... 19 113 4.1.8 Sequenced DataObjects ...... 19 114 4.1.9 Open Content DataObject Properties ...... 20 115 4.1.10 Property Indexes ...... 21 116 4.1.11 Current State for a DataObject ...... 21 117 4.1.12 DataObject Interface ...... 22 118 4.1.13 DataObject Accessor Exceptions ...... 22 119 4.1.14 Validation of Facets and Constraints ...... 23 120 4.2 ChangeSummary ...... 24 121 4.2.1 Starting and Stopping Change Logging ...... 24 122 4.2.2 ChangeSummary Root ...... 25 123 4.2.3 ChangeSummary Scope ...... 25 124 4.2.4 OrphanHolder Properties ...... 25 125 4.2.5 Old Values ...... 26 126 4.2.6 Sequenced DataObject ...... 26 127 4.2.7 ChangeSummary Interface ...... 27 128 4.3 Sequence ...... 27 129 4.3.1 Unstructured Text ...... 27 130 4.3.2 Using Sequences ...... 27 131 4.3.3 Relationship between Sequences with DataObjects ...... 28 132 4.3.4 Sequence Methods ...... 28 133 4.3.5 Sequence Interface ...... 29 134 4.4 Type ...... 29 135 4.4.1 Mapping SDO Types to Programming and Data Modeling Languages ...... 29
10SDO Core Specification Version 3.0 16 December 2008 11Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 4 of 141 136 4.4.2 Type Contents ...... 30 137 4.4.3 Name Uniqueness ...... 30 138 4.4.4 Compatibility Between Types ...... 30 139 4.4.5 Data Types ...... 31 140 4.4.6 Data Type Wrappers ...... 31 141 4.4.7 Multiple Inheritance ...... 31 142 4.4.8 Type Instance Properties ...... 31 143 4.4.9 Type Methods ...... 32 144 4.4.10 Type Interface ...... 33 145 4.5 Property ...... 33 146 4.5.1 Property Index ...... 34 147 4.5.2 Containment ...... 34 148 4.5.3 Key Properties ...... 34 149 4.5.4 Read-Only Properties ...... 35 150 4.5.5 Nullable Properties ...... 35 151 4.5.6 Open Content Properties ...... 35 152 4.5.7 Property Instance Properties ...... 36 153 4.5.8 Property Interface ...... 36 154 4.6 HelperContext ...... 37 155 4.6.1 Default HelperContext ...... 37 156 4.6.2 Non-DefaultHelperContext ...... 37 157 4.6.3 HelperContext Interface ...... 37 158 4.7 DataFactory ...... 37 159 4.7.1 Default DataFactory ...... 37 160 4.7.2 Creating DataObjects ...... 37 161 4.7.3 DataFactory Interface ...... 38 162 4.8 TypeHelper ...... 38 163 4.8.1 Default TypeHelper ...... 38 164 4.8.2 Defining SDO Types Dynamically ...... 38 165 4.8.3 Using SDO Dynamic Types ...... 39 166 4.8.4 Defining and Using Open Content Properties ...... 40 167 4.8.5 TypeHelper Methods ...... 40 168 4.8.6 TypeHelper Interface ...... 41 169 4.9 CopyHelper ...... 41 170 4.9.1 Default CopyHelper ...... 41 171 4.9.2 Shallow Copies ...... 41 172 4.9.3 Deep Copies ...... 41 173 4.9.4 CopyHelper Methods ...... 42 174 4.9.5 CopyHelper Interface ...... 42 175 4.10 EqualityHelper ...... 42 176 4.10.1 Default EqualityHelper ...... 42 177 4.10.2 EqualityHelper Methods ...... 42 178 4.10.3 EqualityHelper Interface ...... 42 179 4.11 XMLHelper ...... 42 180 4.11.1 Default XMLHelper ...... 43 13SDO Core Specification Version 3.0 16 December 2008 14Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 5 of 141 181 4.11.2 Loading and Saving XML Documents ...... 43 182 4.11.3 Determining the Type of XML Elements ...... 43 183 4.11.4 Creating DataObjects from XML ...... 43 184 4.11.5 Creating DataObjects from XML documents ...... 44 185 4.11.6 Creating XML without an XSD ...... 45 186 4.11.7 XMLHelper Methods ...... 46 187 4.11.8 Orphan Serialization ...... 46 188 4.11.9 XMLHelper Interface ...... 47 189 4.12 XMLDocument ...... 47 190 4.12.1 Example XMLDocument ...... 47 191 4.12.2 XMLDocument Methods ...... 47 192 4.12.3 XMLDocument Interface ...... 48 193 4.13 XSDHelper ...... 48 194 4.13.1 Default XSDHelper ...... 49 195 4.13.2 Generating XSDs ...... 49 196 4.13.3 XSDHelper Methods ...... 49 197 4.13.4 XSDHelper Interface ...... 50 198 4.14 DataHelper ...... 50 199 4.14.1 Default DataHelper ...... 50 200 4.14.2 DataHelper Interface ...... 50 201 4.14.3 The Project method ...... 50 202 4.14.4 Keys and Projection ...... 51 203 4.14.5 ChangeSummary and Projection ...... 54 204 4.15 SDO ...... 56 205 4.15.1 Default HelperContext ...... 56 206 4.15.2 HelperContext by Identifier ...... 56 207 4.15.3 Default HelperContextFactory ...... 56 208 4.15.4 Implementation Specific HelperContextFactory ...... 56 209 4.15.5 SDO Class ...... 56 210 4.16 HelperContextFactory ...... 56 211 4.16.1 Creating a HelperContext ...... 56 212 4.16.2 HelperContextFactory Interface ...... 57 2135 SDO Model for Types and Properties ...... 58 214 5.1 API for DataObjects Representing Type and Properties ...... 58 215 5.2 SDO Type and Property constraints ...... 60 216 5.3 XML Representation of SDO Type and Property ...... 61 2176 Standard SDO Types ...... 62 218 6.1 SDO Data Types ...... 62 219 6.1.1 Conversion from SDO type Bytes to SDO type String ...... 64 220 6.1.2 Conversion from SDO type String to SDO type Bytes ...... 64 221 6.1.3 Conversion between Character and String ...... 64 222 6.2 SDO Abstract Types ...... 64 2237 XML Schema to SDO Mapping ...... 66 224 7.1 Mapping Principles ...... 66 225 7.2 Generating static SDOs from an XSD ...... 67 16SDO Core Specification Version 3.0 16 December 2008 17Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 6 of 141 226 7.3 Mapping from XSD to SDO Types ...... 67 227 7.3.1 XML Schemas ...... 68 228 7.3.2 XML Simple Types ...... 69 229 7.3.3 XML Complex Types ...... 70 230 7.4 Mapping of XSD Attributes and Elements to SDO Properties ...... 73 231 7.4.1 Mapping of XSD Attributes ...... 73 232 7.4.2 Mapping of XSD Elements ...... 75 233 7.5 Mapping of XSD Built in Data Types ...... 79 234 7.5.1 Conversion between XSD QName and SDO URI ...... 81 235 7.5.2 Dates ...... 81 236 7.6 Examples of XSD to SDO Mapping ...... 82 237 7.6.1 Example of SDO Annotations ...... 85 238 7.7 XML use of Sequenced Data Objects ...... 86 239 7.8 XSD Mapping Details ...... 86 240 7.9 Compliance ...... 87 241 7.10 Corner cases ...... 87 242 7.11 XML without Schema to SDO Type and Property ...... 87 2438 Generation of XSD from SDO Type and Property ...... 89 244 8.1 Mapping of SDO DataTypes to XSD Built in Data Types ...... 93 245 8.2 Tuning the Default Mapping using Open Content Properties ...... 94 246 8.3 Generating XSD from Types using Keys ...... 95 247 8.4 Example Generated XSD ...... 96 248 8.5 Customizing Generated XSDs ...... 97 2499 SDO Path Expression for DataObjects ...... 98 25010 ChangeSummary XML format ...... 101 251 10.1 ChangeSummary Creation and Deletion Attributes ...... 101 252 10.2 Serialization Format for References ...... 101 253 10.3 Serialization Format for Sequenced DataObjects ...... 102 254 10.4 Serialization Format for DataObject Modifications ...... 102 255 10.5 Example Use of ChangeSummary on a DataObject ...... 104 25611 DataType Conversions ...... 106 25712 Conformance ...... 109 258 12.1 SDO Implemenation ...... 109 259 12.1.1 Optional Items ...... 109 260A. Complete Data Graph Examples ...... 110 261 A.1 Complete Data Graph Serialization ...... 110 262 A.2 Complete Data Graph for Company Example ...... 110 263 A.3 Complete Data Graph for Letter Example ...... 111 264 A.4 Complete WSDL for Web services Example ...... 111 265B. Conformance Items ...... 113 266C. Acknowledgements ...... 123 267D. Non-Normative Text ...... 124 268E. Revision History ...... 125 2691 Introduction ...... 8 270 1.1 Terminology ...... 8 19SDO Core Specification Version 3.0 16 December 2008 20Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 7 of 141 271 1.2 Normative References ...... 8 272 1.3 Non-Normative References ...... 9 2732 Overview ...... 10 274 2.1 Key Concepts ...... 10 275 2.2 Requirements ...... 10 276 2.3 Organization of this Document ...... 12 2773 Architecture ...... 13 2784 Programming Model ...... 15 279 4.1 DataObject ...... 16 280 4.1.1 DataObject Concepts ...... 17 281 4.1.2 DataObject Values and Properties ...... 17 282 4.1.3 Type Conversion ...... 17 283 4.1.4 Many-valued DataObject Properties ...... 18 284 4.1.5 Determining whether a Property is Set ...... 18 285 4.1.6 Containment ...... 19 286 4.1.7 Creating and Deleting DataObjects ...... 19 287 4.1.8 Sequenced DataObjects ...... 19 288 4.1.9 Open Content DataObject Properties ...... 20 289 4.1.10 Property Indexes ...... 21 290 4.1.11 Current State for a DataObject ...... 21 291 4.1.12 DataObject Interface ...... 22 292 4.1.13 DataObject Accessor Exceptions ...... 22 293 4.1.14 Validation of Facets and Constraints ...... 23 294 4.2 ChangeSummary ...... 24 295 4.2.1 Starting and Stopping Change Logging ...... 24 296 4.2.2 ChangeSummary Root ...... 25 297 4.2.3 ChangeSummary Scope ...... 25 298 4.2.4 OrphanHolder Properties ...... 25 299 4.2.5 Old Values ...... 26 300 4.2.6 Sequenced DataObject ...... 26 301 4.2.7 ChangeSummary Interface ...... 27 302 4.3 Sequence ...... 27 303 4.3.1 Unstructured Text ...... 27 304 4.3.2 Using Sequences ...... 27 305 4.3.3 Relationship between Sequences with DataObjects ...... 28 306 4.3.4 Sequence Methods ...... 28 307 4.3.5 Sequence Interface ...... 29 308 4.4 Type ...... 29 309 4.4.1 Mapping SDO Types to Programming and Data Modeling Languages ...... 29 310 4.4.2 Type Contents ...... 30 311 4.4.3 Name Uniqueness ...... 30 312 4.4.4 Compatibility Between Types ...... 30 313 4.4.5 Data Types ...... 31 314 4.4.6 Data Type Wrappers ...... 31 315 4.4.7 Multiple Inheritance ...... 31 22SDO Core Specification Version 3.0 16 December 2008 23Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 8 of 141 316 4.4.8 Type Instance Properties ...... 31 317 4.4.9 Type Methods ...... 32 318 4.4.10 Type Interface ...... 33 319 4.5 Property ...... 33 320 4.5.1 Property Index ...... 34 321 4.5.2 Containment ...... 34 322 4.5.3 Key Properties ...... 34 323 4.5.4 Read-Only Properties ...... 35 324 4.5.5 Nullable Properties ...... 35 325 4.5.6 Open Content Properties ...... 35 326 4.5.7 Property Instance Properties ...... 36 327 4.5.8 Property Interface ...... 37 328 4.6 HelperContext ...... 37 329 4.6.1 Default HelperContext ...... 37 330 4.6.2 Non-DefaultHelperContext ...... 37 331 4.6.3 HelperContext Interface ...... 37 332 4.7 DataFactory ...... 38 333 4.7.1 Default DataFactory ...... 38 334 4.7.2 Creating DataObjects ...... 38 335 4.7.3 DataFactory Interface ...... 39 336 4.8 TypeHelper ...... 39 337 4.8.1 Default TypeHelper ...... 39 338 4.8.2 Defining SDO Types Dynamically ...... 39 339 4.8.3 Using SDO Dynamic Types ...... 40 340 4.8.4 Defining and Using Open Content Properties ...... 40 341 4.8.5 TypeHelper Methods ...... 41 342 4.8.6 TypeHelper Interface ...... 41 343 4.9 CopyHelper ...... 41 344 4.9.1 Default CopyHelper ...... 41 345 4.9.2 Shallow Copies ...... 42 346 4.9.3 Deep Copies ...... 42 347 4.9.4 CopyHelper Methods ...... 42 348 4.9.5 CopyHelper Interface ...... 42 349 4.10 EqualityHelper ...... 42 350 4.10.1 Default EqualityHelper ...... 43 351 4.10.2 EqualityHelper Methods ...... 43 352 4.10.3 EqualityHelper Interface ...... 43 353 4.11 XMLHelper ...... 43 354 4.11.1 Default XMLHelper ...... 43 355 4.11.2 Loading and Saving XML Documents ...... 43 356 4.11.3 Determining the Type of XML Elements ...... 43 357 4.11.4 Creating DataObjects from XML ...... 44 358 4.11.5 Creating DataObjects from XML documents ...... 45 359 4.11.6 Creating XML without an XSD ...... 46 360 4.11.7 XMLHelper Methods ...... 46 25SDO Core Specification Version 3.0 16 December 2008 26Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 9 of 141 361 4.11.8 Orphan Serialization ...... 46 362 4.11.9 XMLHelper Interface ...... 47 363 4.12 XMLDocument ...... 47 364 4.12.1 Example XMLDocument ...... 47 365 4.12.2 XMLDocument Methods ...... 48 366 4.12.3 XMLDocument Interface ...... 49 367 4.13 XSDHelper ...... 49 368 4.13.1 Default XSDHelper ...... 49 369 4.13.2 Generating XSDs ...... 49 370 4.13.3 XSDHelper Methods ...... 50 371 4.13.4 XSDHelper Interface ...... 50 372 4.14 DataHelper ...... 50 373 4.14.1 Default DataHelper ...... 50 374 4.14.2 DataHelper Interface ...... 50 375 4.14.3 The Project method ...... 51 376 4.14.4 Keys and Projection ...... 52 377 4.15 SDO ...... 54 378 4.15.1 Default HelperContext ...... 54 379 4.15.2 HelperContext by Identifier ...... 54 380 4.15.3 Default HelperContextFactory ...... 55 381 4.15.4 Implementation Specific HelperContextFactory ...... 55 382 4.15.5 SDO Class ...... 55 383 4.16 HelperContextFactory ...... 55 384 4.16.1 Creating a HelperContext ...... 55 385 4.16.2 HelperContextFactory Interface ...... 55 3865 SDO Model for Types and Properties ...... 56 387 5.1 Type Properties ...... 56 388 5.2 Property Properties ...... 57 3896 Standard SDO Types ...... 58 390 6.1 SDO Data Types ...... 58 391 6.1.1 Conversion from SDO type Bytes to SDO type String ...... 60 392 6.1.2 Conversion from SDO type String to SDO type Bytes ...... 60 393 6.1.3 Conversion between Character and String ...... 60 394 6.2 SDO Abstract Types ...... 60 395 6.3 SDO Model Types ...... 61 396 6.4 SDO Type and Property constraints ...... 62 3977 XML Schema to SDO Mapping ...... 64 398 7.1 Mapping Principles ...... 64 399 7.2 Generating static SDOs from an XSD ...... 65 400 7.3 Mapping from XSD to SDO Types ...... 65 401 7.3.1 XML Schemas ...... 66 402 7.3.2 XML Simple Types ...... 67 403 7.3.3 XML Complex Types ...... 68 404 7.4 Mapping of XSD Attributes and Elements to SDO Properties ...... 71 405 7.4.1 Mapping of XSD Attributes ...... 71 28SDO Core Specification Version 3.0 16 December 2008 29Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 10 of 141 406 7.4.2 Mapping of XSD Elements ...... 73 407 7.5 Mapping of XSD Built in Data Types ...... 77 408 7.5.1 Conversion between XSD QName and SDO URI ...... 79 409 7.5.2 Dates ...... 80 410 7.6 Examples of XSD to SDO Mapping ...... 80 411 7.6.1 Example of SDO Annotations ...... 83 412 7.7 XML use of Sequenced Data Objects ...... 84 413 7.8 XSD Mapping Details ...... 84 414 7.9 Compliance ...... 85 415 7.10 Corner cases ...... 85 416 7.11 XML without Schema to SDO Type and Property ...... 85 4178 Generation of XSD from SDO Type and Property ...... 87 418 8.1 Mapping of SDO DataTypes to XSD Built in Data Types ...... 91 419 8.2 Tuning the Default Mapping using Open Content Properties ...... 92 420 8.3 Generating XSD from Types using Keys ...... 93 421 8.4 Example Generated XSD ...... 94 422 8.5 Customizing Generated XSDs ...... 95 4239 SDO Path Expression for DataObjects ...... 96 42410 ChangeSummary XML format ...... 99 425 10.1 ChangeSummary Creation and Deletion Attributes ...... 99 426 10.2 Serialization Format for References ...... 99 427 10.3 Serialization Format for Sequenced DataObjects ...... 100 428 10.4 Serialization Format for DataObject Modifications ...... 100 429 10.5 Example Use of ChangeSummary on a DataObject ...... 102 43011 DataType Conversions ...... 104 431A. Complete Data Graph Examples ...... 107 432 A.1 Complete Data Graph Serialization ...... 107 433 A.2 Complete Data Graph for Company Example ...... 107 434 A.3 Complete Data Graph for Letter Example ...... 108 435 A.4 Complete WSDL for Web services Example ...... 108 436B. Conformance Items ...... 110 437C. Acknowledgements ...... 118 438D. Non-Normative Text ...... 119 439E. Revision History ...... 120 440 441
31SDO Core Specification Version 3.0 16 December 2008 32Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 11 of 141 4421 Introduction 443SDO provides a unifying API and architecture that allows SOA applications handle data from 444heterogeneous sources, including relational databases, Web services, and enterprise information 445systems. This document describes the architecture and programming model for SDO.
4461.1 Terminology 447The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD 448NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described 449in [RFC2119]. 450 451The following standard namespace URIs are associated with this specification: 452 453 “http://docs.oasis-open.org/ns/opencsa/sdo/200812” contains the standard SDO types and 454 properties. Previous implementations of SDO used “commonj.sdo” for this namespace. An SDO 455 iImplementations may MAY choose to continue to support “commonj.sdo” as an alias URI for this 456 namespace. [COR01010001] 457 “http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812” contains XML specific SDO types and 458 properties. Previous implementations of SDO used “commonj.sdo/xml” for this namespace. An 459 SDO iImplementations may MAY choose to continue to support “commonj.sdo/xml” as an alias 460 URI for this namespace. [COR01010002] 461 462When not explicitly stated, this specification uses a default mapping for each of the following XML 463namespace prefixes: 464 465 “sdo” is mapped to namespace “http://docs.oasis-open.org/ns/opencsa/sdo/200812” 466 “sdox” is mapped to namespace “http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812” 467 “xsd” is mapped to namespace “http://www.w3.org/2001/XMLSchema (the default prefix can also 468 be used when the context is clear) 469 “xsi” is mapped to namespace “http://www.w3.org/2001/XMLSchema-instance 470 471Although this specification is language-neutral, for simplicity we use the Java programming language to 472illustrate code patterns and for the examples. In cases where the language mapping is not obvious, some 473of these examples or patterns are reproduced in the Llanguage-specific specifications. may reproduce 474some of these examples or patterns, in cases where the language mapping is not obvious.
4751.2 Normative References 476 [RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, 477 http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997. 478 479 [Schema1] XML Schema Part 1: Structures, http://www.w3.org/TR/xmlschema-1 480 481 [Schema2] XML Schema Part 2: Datatypes http://www.w3.org/TR/xmlschema-2 482 483 [XPath] XPath 1.0 specification http://www.w3.org/TR/xpath 484
34SDO Core Specification Version 3.0 16 December 2008 35Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 12 of 141 485 [SDOJava] F. Budinsky, et al., Service Data Objects For Java Specification Version 3.0, 486 http://docs.oasis-open.org/opencsa/sdo/sdo-java-3.0-spec.pdf, OASIS Service 487 Data Objects For Java Specification Version 3.0, XXX 2008 488
4891.3 Non-Normative References 490 [NextGen] Next-Generation Data Programming with Service Data Objects, 491 Any one of: 492 http://www.ibm.com/developerworks/library/specification/ws-sdo/ 493 http://oracle.com/technology/webservices/sca 494 https://www.sdn.sap.com/ 495
37SDO Core Specification Version 3.0 16 December 2008 38Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 13 of 141 4962 Overview 497Service Data Objects (SDO) is a data programming architecture and an API. 498The main purpose of SDO is to simplify data programming, so that developers can focus on business 499logic instead of the underlying technology. 500 501SDO simplifies data programming by: 502 unifying data programming across data source types 503 providing support for common application patterns 504 enabling applications, tools and frameworks to more easily query, view, bind, update, and 505 introspect data. 506 507For a high-level overview of SDO, see the white paper titled “Next-Generation Data Programming: 508Service Data Objects” [NextGen].
5092.1 Key Concepts 510The key concepts in the SDO architecture are the Data Object and the data graph. 511A Data Object holds a set of named properties, each of which contains either a simple data-type value or 512a reference to another Data Object. The Data Object API provides a dynamic data API for manipulating 513these properties. 514The data graph provides an envelope for Data Objects, and is the normal unit of transport between 515components. Data graphs can track changes made to the graph of Data Objects. Changes include 516inserting Data Objects, deleting Data Objects and modifying Data Object property values. 517In most cases, data graphs are ultimately derived from a data source, such as XML files, language 518structures, XML databases and relational databases. Within a Service Oriented Architecture (SOA) data 519graphs can be passed between and used by services that are unaware of the original source of the data.
5202.2 Requirements 521The scope of the SDO specification includes the following requirements: 5221. Dynamic Data API. DataObjects often have typed interfaces. Typed interface provide type-safe, 523 programmer friendly access to the data, and are appropriate when programming business logic in the 524 target language. The Dynamic API, on the other hand, is more appropriate to generically 525 programmed framework components, such as mapping and rules engines. HoweverFurthermore, 526 sometimes it is either impossible or undesirable to create typed interfaces to represent the 527 DataObjects. One common reason for this is when the data being transferred is defined by the output 528 of a query. Examples would be: 529 – A relational query against a relational persistence store. 530 – An EJBQL queries against an EJB entity bean domain model. 531 – Web services. 532 – XML queries against an XML source. 533 – When deployment of generated code is not practical. 534 In these situations, it is necessary to use a dynamic store and associated API. SDO has the ability to 535 represent Data Objects through a standard dynamic data API.
40SDO Core Specification Version 3.0 16 December 2008 41Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 14 of 141 5362. Support for Static Data API. In cases where metadata is known at development time (for example, 537 the XML Schema definition or the SQL relational schema is known), SDO supports code-generating 538 interfaces for Data Objects. When static data APIs are used, the dynamic data APIs are still available. 539 SDO enables static data API code generation from a variety of metamodels, including: 540 – Popular XML schema languages. 541 – Relational database schemas with queries known at the time of code generation. 542 – Web services, when the message is specified by an XML schema. 543 – JCA connectors. 544 – JMS message formats. 545 – UML models 546 While code-generation rules for static data APIs is outside the scope of this core SDO specification, it 547 is the intent that SDO supports code-generated approaches for Data Objects. 5483. Complex Data Objects. It is common to have to deal with “complex” or “compound” Data Objects. 549 This is the case where the Data Object is the root of a tree, or even a graph of objects. An example of 550 a tree would be a Data Object for an Order that has references to other Data Objects for the Line 551 Items. If each of the Line Items had a reference to a Data Object for Product Descriptions, the set of 552 objects would form a graph. When dealing with compound data objects, the change history is 553 significantly harder to implement because inserts, deletes, adds, removes and re-orderings have to 554 be tracked, as well as simple changes. Service Data Objects support arbitrary graphs of Data Objects 555 with full change summaries. 5564. Change Summary. It is a common pattern for a client to receive a Data Object from another program 557 component, make updates to the Data Object, and then pass the modified Data Object back to the 558 other program component. To support this scenario, it is often important for the program component 559 receiving the modified Data Object to know what modifications were made. In simple cases, knowing 560 whether or not the Data Object was modified can be enough. For other cases, it can be necessary (or 561 at least desirable) to know which properties were modified. Some standard optimistic collision 562 detection algorithms require knowledge not only of which columns changed, but what the previous 563 values were. Service Data Objects support full change summary. 5645. Navigation through graphs of data. SDO provides navigation capabilities on the dynamic data API. 565 All Data Objects are reachable by breadth-first or depth-first traversals, or by using a subset of XPath 566 1.0 expressions. 5676. Metadata. Many applications are coded with built-in knowledge of the shape of the data being 568 returned. These applications know which methods to call or fields to access on the Data Objects they 569 use. However, in order to enable development of generic or framework code that works with Data 570 Objects, it is important to be able to introspect on Data Object metadata, which exposes the data 571 model for the Data Objects. As Java reflection does not return sufficient information, SDO provides 572 APIs for metadata. SDO metadata may can be derived from: 573 – XML Schema 574 – Language structures 575 – Relational databases 576 – Other structured representations. 577 Applications that run on application servers commonly share memory with other applications. In such 578 environments, it is essential that each application can define its own type system and be assured that 579 the metadata is protected from influence from other applications that may potentially have conflicting 580 definitions for some types. This concept of a registry of types that is local to each application is 581 supported by SDO's HelperContext. 5827. Validation and Constraints. 583 – Supports validation of the standard set of constraints captured in the metadata. The metadata 584 captures common constraints expressible in XML Schema and relational models (for example, 585 occurrence constraints). 43SDO Core Specification Version 3.0 16 December 2008 44Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 15 of 141 586 – Provides an extensibility mechanism for adding custom constraints and validation. 5878. Relationship integrity. 588 – An important special case of constraints is the ability to define relationships between objects and 589 to enforce the integrity of those constraints, including cardinality, ownership semantics and 590 inverses. For example, consider the case where an employee has a relationship to its department 591 and a department inversely has a list of its employees. If an employee’s department identifier is 592 changed then the employee should be removed, automatically, from the original department’s list. 593 Also, the employee should be added to the list of employees for the new department. Data Object 594 relationships use regular Java objects as opposed to primary and foreign keys with external 595 relationships. 596 – Support for containment tree integrity is also important. 597 598NOTE the following areas are out of scope: 5999. Complete metamodel and metadata API. SDO includes a minimal metadata access API for use by 600 Data Object client programmers. The intention is to provide a very simple client view of the model. 601 For more complete metadata access, it is possible to use SDO may be used in conjunction with 602 common metamodels and schema languages, such as XML Schema [Schema1] [Schema2]. Java 603 annotations in JSR 175 may be a future source of metadata. 60410. Data Access Service (DAS) specification. Service Data Objects can be used in conjunction with 605 “data accessors”. Data accessors can populate data graphs with Data Objects from back-end data 606 sources, and then apply changes to a data graph back to a data source. A data access service 607 framework is out of scope but will be included in a future Data Access Service specification.
6082.3 Organization of this Document 609This specification is organized as follows: 610Architecture: Describes the overall SDO system. 611Programming Model: Defines and describes the programming model for SDO. 612SDO Model for Types and Properties: Shows the SDO Type and Property in model form. 613Standard SDO Types: Defines and describes the Standard SDO Types. 614XML Schema to SDO Mapping: Defines and describes how XML Schema declarations (XSD) are 615mapped to SDO Types and Properties. 616Generation of XSD from SDO Type and Property: Describes how to generate XSDs from SDO Types 617and Properties. 618SDO Path Expression for DataObjects: Defines an augmented subset of XPath that can be used with 619SDO for traversing through Data Objects. 620ChangeSummary XML format: Describes how change summary information is represented in an XML 621message. 622DataType Conversion Tables: Shows the set of defined datatype conversions. 623Examples: Provides a set of examples showing how SDO is used.
46SDO Core Specification Version 3.0 16 December 2008 47Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 16 of 141 6243 Architecture
625The core of the SDO framework is the DataObject, which is a generic representation of a business object 626and is not tied to any specific data source.
627A data graph is a set of interrelated DataObjects. Data graphs are often enclosed in envelope objects. 628These envelopes are in fact normal DataObjects but have special technical properties, for instance, to 629enable change tracking. Such properties are termed “technical” because they do not represent business 630data.
631The relationship between DataObjects can be through containment and non-containment references. 632Containment references are special in that a DataObject is contained by at most one other DataObject. 633DataObjects related through containment form a tree having a single root DataObject that directly or 634indirectly contains all the other DataObjects in the tree. A closed data graph is a data graph having such 635a tree-like form, where even the non-containment references refer only to DataObjects in the tree. Earlier 636versions of SDO viewed closure as the normative state for data graphs and required closure for serveral 637fundamental operations , for instance, for serialiizationwere defined only for closed graphs. In SDO 638version 3, envelopes can be given technical properties that enable SDO operations to workfunctionalities 639even if the embedded data graph is not closed.
640Most DataObjects come directly or indirectly from some persistent storage. The persistence mechanism 641is typically exposed as a service. SDO supports the use of a disconnected interaction model, in which 642changes made by the client are not written back onto the persistent storage unless some explicit service 643call is made to the storage mechanism. During both read and update operations, potentially large and 644complex data graphs are transmitted between the persistence mechanism and the client application. 645Thus, a typical scenario for using a data graph involves the following steps:
49SDO Core Specification Version 3.0 16 December 2008 50Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 17 of 141 646 Data Access call Service Service Consumer (actually a (PresentationClient specific provide Layer, business(persistence logic mechanism) Composite...) encapsulation , e.g. the Order service)
keep Data Access Service Consumer Service (actually a (Presentation operate specific ClientLayer, (persistence business logic Composite, mechanism) encapsulation ...) , e.g. the Order service)
Data Access call for update ServiceService Consumer (actually a (Presentation specific Client (persistence Layer, businessmechanism) logic Composite...) encapsulation , e.g. the Order service)
647 1. The client application sends a request to a service to load a data graph. 648 2. The service retrieves data and creates a data graph that represents the data. 649 3. The service returns the data graph to an client application. 650 4. The client application processes and modifies the data graph. 651 5. The client application calls the service, passing it the modified data graph. 652 6. The service updates the data in the persistent store.
653One way that SDO supports the disconnected model is by providing a mechanism though which the 654server can find the client's modifications to the graph and retrieve old values. All the changes made by the 655client, including creations, deletions and modifications of DataObjects are contained in the 656ChangeSummary.
657SDO specifies minimum functionality for implementations. An SDO implementation may MAY provide 658additional functionality so that valid results would be returned where this specification would produce an
52SDO Core Specification Version 3.0 16 December 2008 53Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 18 of 141 659error, provided that the functionality is a strict superset and all valid uses of the SDO specification operate 660correctly. [COR03000001]
661
55SDO Core Specification Version 3.0 16 December 2008 56Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 19 of 141 6624 Programming Model 663The SDO programming model includes interfaces that relate to instance data: 664 DataObject – A business data object. 665 ChangeSummary – Summary of changes to the DataObjects in a data graph. 666 Sequence – A sequence of settings. 667 668The SDO also contains a lightweight metadata API that can be used for introspecting the model of 669DataObjects: 670 Type – The Type of a DataObject or Property. 671 Property – A Property of a DataObject. 672 673SDO has a number of helper interfaces: 674 HelperContext 675 TypeHelper 676 CopyHelper 677 EqualityHelper 678 XMLHelper 679 XMLDocument 680 XSDHelper 681 DataHelper 682 683Instances of the helpers can be accessed from context objects: 684 SDO 685 HelperContextFactory 686 ChangeSummary and Projection 687 688The APIs are shown in figure 3 below. 689The UML API representations in the following sections define base functionality. The UML representation 690as classes does not prohibit a language specification from providing the functionality as a collection of 691functions. Since it is the objective of a Individual language specifications to present the SDO functionality 692in a manner that is appropriate to the language, a language specification might MAY add additional 693methods or functions to any of the interfaces or . Further, individual language specifications MAY modify 694the names, parameters and return types of the methods to fit the requirements of the language, provided 695that the equivalent functionality is maintained. Unless otherwise specified, all public attributes in the URL 696UML representations of the interfaces are read only. 697The notation
58SDO Core Specification Version 3.0 16 December 2008 59Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 20 of 141 702 Double 703 Float 704 Integer 705 Long 706 Short 707 Bytes 708 DataObject 709 Date 710 String 711Individual language specifications MAYmight adnd additional types to this list. If a language provides a 712mechanism for the various types to be treated as a single type, then the set of methods MAYcould be 713replaced with a single one. 714Note that unless an SDO API explicitly states that null is a legal value for a parameter, passing null will 715results in an implementation-dependent runtime exception.
716 717Figure 1: SDO Core Interfaces
7184.1 DataObject 719DataObjects represent business data. They hold their data in properties. 720The DataObject interface is designed to make programming easier because it provides access to 721business data of all the common types and access patterns, such as name, index, and path. 722The DataObject interface includes methods that: 723 Get and set the properties of a DataObject. 724 Query whether a Property is set. 725 Create a new instance of a contained DataObject. 726 Delete a DataObject from its container. 727 Detach a DataObject from its container. 728 Get the container of a DataObject and the containing property. 729 Get the root DataObject. 730 Get the DataObject’s Type. 731 Get the DataObject’s Sequence (if present). 732 Get the DataObject’s additional Properties (if present).
61SDO Core Specification Version 3.0 16 December 2008 62Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 21 of 141 733For many applications that do not use generated code, the DataObject interface is the only part of SDO 734that is used to write applications. For manyOther applications that use generated code, the generated 735interfaces themselves are what is usedprimarilly use the type safe, programmer friendly static APIs, 736casting to DataObject only for specific operations, e.g., serialization to XML. The otherWhich parts of 737SDO APIs are used will vary based on the needs of the applicationare primarily use-as-you-go. For 738example, if XML is part of your an application, then the XMLHelper is valuable, but otherwise might never 739be used.
7404.1.1 DataObject Concepts 741DataObjects can be thought of as falling into the following categories. The open and sequenced concepts 742can be used independently or together. 7431. Basic. A DataObject is similar to a class with a field for each Property. The set of allowed Properties 744 is defined by getType().getProperties(). Values are accessed through get
7574.1.2 DataObject Values and Properties 758DataObjects have data values assigned to Properties. For example, a purchase order DataObject 759representing a purchase order could have the value “2005-06-30” assigned to a property namedthe 760“orderDate” property. Values for the orderDate property can be returned or changed using the 761getString("orderDate") and setString("orderDate", …) accessors on the DataObject. When code is 762generatedusing static APIs, values can also be accessed through getOrderDate() and setOrderDate() 763methods on a PurchaseOrder interface. 764On the DataObject interface, values can be accessed using the name of the property with get
7714.1.3 Type Conversion 772Sometimes the Type of a Property is different than the most convenient type for use in an application 773program. For example, when displaying an integer quantity in a user interface, the string representation 774is more useful than the int. The method getString("quantity") for accessing an int quantity property 775conveniently returns the value as a String. This simplifies a common task in many applications. 776When a DataObject’s typed accessors get
64SDO Core Specification Version 3.0 16 December 2008 65Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 22 of 141 781An SDO implementation of SDO is expected toMUST convert between any the data type of the property 782and the requested data type for all conversions defined in Chapter 11: DataType Conversions. 783[COR04010301] Some conversions MAYcan lose and the set defined in DataObject, with possible loss of 784information. The supported data type set is defined in 6.1: SDO Data Types. These types include: 785 Primitive data types 786 String 787 Date and time types 788 URI 789 byte[] 790 791A base set of supported conversions is specified in DataType Conversions. The details of the conversions 792are left to the individual language specifications. 793An SDO iImplementation MUST Cconversiont between DataType values and wrapper DataObjects (i.e., 794Data Type Wrappers DataTypeWrappers) is also supported. [COR04010302] For example, 795getDataObject() on a String-type property will returns a wrapper DataObject for the string value, and 796getString() on a DataObject property will does the reverse. Generated wrapper DataObjects contain 797disconnected copies of their corresponding converted property values. An SDO iImplementations MUST 798also The set of supportedsupport all conversions specified in DataType ConversionsDataType 799Conversions DataType Conversions applies MUSTwhen converting from DataWrappers to DataTypes, 800e.g., an integer wrapper can be used when setting a string propertysimilarly to wrappers, that is, if the 801type of a DataTypeWrapper value property (e.g., Int), is compatible with some other DataType (e.g., 802String), then conversion from the wrapper to the DataType is allowed. [COR04010303] For example, an 803integer wrapper can be used when setting a string property
8044.1.4 Many-valued DataObject Properties 805A Property can have one or many values. If a Property is many-valued then property.many is true. 806An SDO iImplementation MUST return an empty list, rather than a null value, for all property accessors 807that haveDataObject methods with a return type of List, whether ion the DataObject interface or 808generatedin a static API, even iof the propertiy hasreturn empty lists rather than null when there is no 809value. [COR04010401] Returned Lists actively represent any changes to the DataObject's values. The 810details of the returned List are dependent on the language implementation of DataObject. 811The getList(property) accessor is especially convenient for many-valued properties. If property.many is 812true then set(property, value) and setList(property, value) require that “value” be a Collection and List 813respectively, as defined for the implementation language. 814For many-valued Properties, get() and getList() return a List containing the current values. An SDO 815implementation MUST make all modifications to thea returned List visible in the DataObjectUpdates 816through the List interface operate on the current values of the DataObject, so that all operations, e.g., 817serialization to XML, reflect the updated list contents immediately. [COR04010402] Conversely, An SDO 818implementations MUST make all updates to the DataObject are immediately reflected visible thoughin 819the a returned List object. [COR04010403] 820A multi-valued property whose elements are DataObjects (i.e., property.type.dataType is false) can not 821contain null values. The behavior of an SDO implementation is undefined if an attempt is made to set the 822value of the property to a list containing null, or to append a null value to an existing list. 823A multivalued property that is bidirectional (i.e., has an opposite property, or is indicated as the opposite 824of another property) cannot cannot contain duplicates. The behavior of an SDO implementation is 825undefined if an attempt is made to set the value of the property to a list containing duplicates, or to 826append a element to a list that already contains the value. 827
67SDO Core Specification Version 3.0 16 December 2008 68Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 23 of 141 8284.1.5 Determining whether a Property is Set 829For many-valued properties, isSet(property) MUST returns: 830 True, if the List is not empty. 831 False, if the List is empty. [COR04010501] 832 833For single-valued properties, isSet(property) MUST returns: 834 True, if the Property has been set(), and not unset(). 835 False, if the Property has not been set(), or has been unset(). [COR04010502] 836 837For single valued properties, any call to set
8704.1.6 Containment 871DataObjects in a closed data graph are arranged in a tree structure. One DataObject forms the root of the 872tree and the other DataObjects make up the nodes of the tree.
70SDO Core Specification Version 3.0 16 December 2008 71Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 24 of 141 873The tree structure is created using containment references which start at the root DataObject. The root 874DataObject refers to other DataObjects, which can refer to further DataObjects. Each DataObject in the 875data graph, except for the root DataObject, must haveis pointed to by a containment reference from 876another node in the tree. Each DataObject in the graph keeps track of of the location of its containment 877reference, of which there can be at most one... 878It is possible for a data graph to have non-containment references. These are references to DataObjects 879which are part of the same data graph, (the referenced DataObjects must be part of the same tree), but 880these referencesthat do not affect the tree structure of the data graph imposed by the containment 881structure. A DataObject can be referenced by many non-containment references, but by at most one 882containment reference.. 883Both containment and non-containment references are Properties of a DataObject. The Type of the 884Properties is any DataObject Type. 885Whether a particular DataObject reference Property is a containment reference or a non-containment 886reference is defined by the data model for the data graphmetadata, for example the XSD which defines 887the data types for an XML document. This cannot be changed once the data model has been defined. 888You can query wWhether a particular reference is a containment reference can be queried by accessing 889property.containment. 890A container DataObject is one that contains other DataObjects. A DataObject can have a maximum of 891one container DataObject. If a DataObject has no container, it is considered to be a root DataObject. 892Simple navigation, up and down the DataObject containment tree, is provided by getContainer() and 893getContainmentProperty(). The getContainer() method returns the parent DataObject and the 894getContainmentProperty() method returns the Property of the container that contains this object. A 895DataObject can be removed from its container, without making any other changes, using the detach() 896method. 897Containment is managed. When a DataObject is set or added to a containment Property, the SDO 898iImplementation it isMUST remove itd from any previous containment Property. [COR04010601] 899Containment cannot have cycles. If a set or add would produce a containment cycle, an SDO 900implemenation MUST raise an erroran exception MAY beis thrown.. [COR04010602]
9014.1.7 Creating and Deleting DataObjects 902The DataObject.create methods create an appropriately typed DataObject of the Type of the Property, or 903the Type specified in the arguments, and add the created object to the Property specified. If the 904DataObject's Type is a sequenced type (that is, if getType().isSequenced() is true) then the SDO 905iImplementation MUST place the created DataObject is put at the end of the Sequence. [COR04010701] 906If the Property is single-valued, an SDO iImplementation MUST set the value of the Property , to the 907object created by DataObject.create().is set to the created object. [COR04010702] If the Property is multi- 908valued, an SDO iImplementation MUST add the object created by DataObject.create() as the last object 909in the value list.the created object is added as the last object. [COR04010703] Only containment 910properties may be specified for creation. A created object begins with all its properties unset. 911The delete() method MUST unsets all the DataObject’s non-readonly properties. [COR04010704] If the 912containment Property is not read-only, tThe delete() method MUSTwill also remove the DataObject from 913its containing DataObject if the containment Property is not read-only. [COR04010705] WhenThe 914delete() method MUST delete is called, aAll DataObjects recursively directly or indirectly contained by 915containment properties will MUST also be deletedof the DataObject. [COR04010706] 916If other DataObjects have one-way, non-containment properties that refer to deleted DataObjects, then 917these references are MUST NOT be not modified. [COR04010707] However, it will probably be 918necessary to change these properties can need changing to other values, in order to restore closure to 919the data graph. A deleted DataObject can be used again, have its values set, and again be added into the 920data graph again.
73SDO Core Specification Version 3.0 16 December 2008 74Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 25 of 141 9214.1.8 Sequenced DataObjects 922A DataObject can be of a sequenced or unsequenced type (see Sequence). The 923getType().isSequenced() method tells youdetermines whether the DataObject's Type is sequenced or not. 924If a DataObject's Type is not sequenced then getSequence() MUST returns that its Sequence, otherwise 925getSequence() returns null. [COR04010801]. 926The Sequence of a DataObject corresponds to the XML elements representing the values of its 927properties. Updates through DataObject, and the Lists or Sequences returned from DataObject, operate 928on the same data. Returned Sequences actively represent any changes to the DataObject's values.
9294.1.9 Open Content DataObject Properties 930DataObjects can have two kinds of Properties: 9311. Those specified by their Type (see Type) 9322. Those not specified by their Type. These additional properties are called open content. 933Properties which are specific to a DataObject’s Type are returned in a List by getType().getProperties(). 934DataObjects can have Properties beyond those specified by their Type when either: 9353. Handling XML open content. 9364. Encountering new Properties dynamically. 937 Open content Properties are allowed only when Type.open is true. Some Types set open to false so 938 they do not have to accept additional Properties. 939 A Property of a DataObject can be identified as open content if Property.isOpenContent() returns 940 true. Open content properties only appear in getInstanceProperties() but not in 941 getType().getProperties(). If a Property is from open content then isSet(property) must be true. 942 All Properties currently used in a DataObject are returned, in a read-only List, when you invokeby 943 getInstanceProperties(). This includes properties that are open content. The order of the Properties 944 begins with all the Properties specified by the DataObject’s TypegetType().getProperties() whether 945 set or not; the order of the remaining Properties is determined by the implementation dependent. The 946 Calling isSet(property) method invoked on an open content property in the list of instance properties 947 MUST return true. [COR04010901]. 948The property name can be used to find the corresponding Property active on the DataObject within the 949instance properties by calling getInstanceProperty(String name). 950In order to set an open content value when that Property is not set (it does not appear in 951getInstanceProperties()), a set or create accessor on DataObject, or add on List or Sequence, with a 952Property parameter can be used, typically found by accessing the TypeHelper or XSDHelper. 953Open content properties can also be created automatically (on-demand) by setting an undefined property 954on a DataObject of a Type that isOpen. For example, when a client calls: 955 956 openTypeDataObject.set
959 960If the specified property name does not already exist in the typea DataObject - that is, 961openTypeDataObject.getInstanceProperty("someProperty") returns null - an SDO Implementaion MUST 962dynamically define thean open content property named "someProperty" will be defined on-the-fly and 963added it as an instance property by the implementationof the DataObject. [COR04010902] TheA 964demand-created property created by thean SDO Implemention MUST Instances of demand created 965properties will be serialized to XML as XML elements. The demand-created property BEisbe equivalent to
76SDO Core Specification Version 3.0 16 December 2008 77Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 26 of 141 966an open content property explicitly created by calling TypeHelper.defineOpenContentProperty(null, 967property) where property is initialized as followsaccording to the following rules: 968 969 The property name is is the name passed to the DataObject.set
9924.1.10 Property Indexes 993When a DataObject has multiple Properties, each of the Properties can be referenced by an index 994number, starting at 0 for the first Property. 995The Property index used in get(int property), is the position in the List returned by getInstanceProperties(). 996Using index parameter accessors for open content is not recommendeddiscouraged if the data is being 997modified, unless the index is used in coordination with getInstanceProperties(). This is because the index 998of properties for open content in getInstanceProperties() can change, if the values of several open content 999properties are set and unset repeatedly. 1000The following example is acceptable because the index is used in coordination with 1001getInstanceProperties(). Note that DataObjects are not synchronized so the user should not have updates 1002going on at the same time as reads. This example shows a common pattern, looping through all instance 1003properties and printing the property name and value: 1004 for (int i=0; i 82SDO Core Specification Version 3.0 16 December 2008 83Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 28 of 141 10304.1.12 DataObject Interface 1031 10324.1.13 DataObject Accessor Exceptions 1033The following exceptions are defined for DataObject accessors. The actual manifestation of the 1034exceptions is language specific. 1035The get(String path) method willMUST return null instead of throwing an exceptionraising an error for 1036error conditions, for example if “path” refers to a non-existing property. [COR04011301] This avoids the 1037need for defensive programming and helps simple programs access data that has a flexible structure. 1038SimilarlyThe, get 85SDO Core Specification Version 3.0 16 December 2008 86Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 29 of 141 1045Open content DataObjects will notMUST NOT throw exceptionsraise an error for accessing properties 1046which are not set on the DataObject. [COR04011304] 1047 1048The following table lists the exceptionsconditions where an error is raised that MAY be thrown when a 1049propertiy areis improperly accessed Condition Exception For Types without open content (open=false), Property is not a IllegalArgumentException member of getInstanceProperties() in get 10514.1.14 Validation of Facets and Constraints 1052XML elements can have facets, that is, restrictions. If the value set on a Property does not meet a facet or 1053constraint, such as an XSD range restriction, the accessoran SDO implementation may MAY throw raise 88SDO Core Specification Version 3.0 16 December 2008 89Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 30 of 141 1054an implementation specific exceptionerror or . However, implementations are not required toMAY also 1055delay throwraising exceptionsan error to a later time when validation is because it can be more practical 1056to perform validationappropriate at a later time. [COR04011401] 1057Validation that occurs during the execution of an accessor method is called immediate validation. 1058Validation that is externally triggered is called deferred validation. In general, deferred validation is more 1059efficient because checking is typically invoked once, after all values are set. Most constraints can only be 1060enforced with deferred validation because more than a single property value is being validated. Underflow 1061constraints (that is, properties that must be assignedfor which values are needed for valid input to an 1062applicationobjects) are always deferred when building new DataObjects. SDO leaves it to 1063implementations, applications, and services to determine when and how validation should be performed. 1064Deferred validation is defined by services which perform validation on their input parameters, for example 1065before the service makes updates to a database. Deferred validation does not occur through the 1066DataObject APIs. 1067If an exception error is thrownraised, no change to the DataObject takes place and therefore there is no 1068change to any ChangeSummary. 10694.2 ChangeSummary 1070A ChangeSummary provides access to the changes made to the DataObjects in a data graph, comparing 1071the data graph’s “before” state to its “after” state. The “before” state is the state of the data graph at the 1072time when logging was activated. If logging is no longer active, the “after” state is the state of the graph 1073when logging was deactivated. This means that only changes that were made up to the point when 1074logging was deactivated are included in the ChangeSummary. Otherwise, the ChangeSummary includes 1075all changes up to the point at which the it is interrogated. The ChangeSummary contains only net 1076changes, transient values that are assigned to properties after logging begins, but which are overwritten 1077before logging is deactivated are not visible throught the change summary. Although change information 1078is only gathered when logging is on, the ChangeSummary can be queried whether logging is on or off. All 1079of the information returned is read-only. 1080The ChangeSummary interface has methods that: 1081 Activate and deactivate logging. 1082 Restore a tree of DataObjects to the state it was in when logging began and clear the log. 1083 Query the logging status. 1084 Get the ChangeSummary’s root DataObject. 1085 Get the list of changed DataObjects. 1086 Indicate whether a DataObject in the list of changed DataObjects has been created, deleted or 1087 modified. 1088 Get a DataObject’s container DataObject at the point when logging began. 1089 Get a DataObject’s containment property at the point when logging began. 1090 Get a DataObject’s Sequence at the point when logging began. 1091 Get a specific old value. 1092 Get a list of old values. 10934.2.1 Starting and Stopping Change Logging 1094ChangeSummary.beginLogging() clears the ChangeSummary’s list of changed DataObjects and starts 1095change logging. ChangeSummary.endLogging() stops change logging. ChangeSummary.undoChanges() 1096restores the data graph to its state when logging began. ChangeSummary.undoChanges() also clears the 1097log, but does not affect isLogging(). 91SDO Core Specification Version 3.0 16 December 2008 92Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 31 of 141 1098NOTE: The beginLogging(), endLogging() and undoChanges() methods are intended primarily for the use 1099of service implementations since services define how the processing of a ChangeSummary relates to 1100external resources. Making changes that are not captured in the ChangeSummary may cause services 1101that drive updates from a ChangeSummary to act on incomplete information. The results of calling 1102undoChanges() after endLogging() are similarly unpredictable. 11034.2.2 ChangeSummary Root 1104ChangeSummaries become associated with DataObjects when the DataObject includes a Property with 1105type ChangeSummaryType. The ChangeSummary root is the DataObject having the ChangeSummary 1106property. ChangeSummary.getRootObject() MUST returns the ChangeSummary root. Calling 1107DataObject.getChangeSummary() invoked on the ChangeSummary root, or on any DataObject 1108contained, directly or indirectly, by the ChangeSummary root, MUST return the same ChangeSummary 1109object. [COR04020201] It MUST also be possible to retrieve this object using 1110DataObject.get(“changeSummaryProperty”) where “changeSummaryProperty” is the name of a property 1111whose Type is ChangeSummaryType MUST return the same ChangeSummary object as 1112DataObject.getChangeSummary(). [COR04020202] The following rules and restrictions apply to 1113ChangeSummary properties: 11141. An SDO implementation MUST raise an error if a Type is defined that s are allowed to contains at 1115 mostmore than one property with type ChangeSummaryType. [COR04020204] 11162. An SDO implementation MUST raise an error if a Type is defined with aA property with type 1117 ChangeSummaryType that has must haveis restricted to many=falsetrue and readOnly=truefalse. 1118 [COR04020205] 11193. The scope of ChangeSummaries may never overlap. An SDO implementation MUST raise an error iIf 1120 a DataObject has a property of type ChangeSummary, it is illegal for it tocannot be directly or 1121 indirectly contained or otherwised referenced by any other DataObjects that hasve a property of type 1122 ChangeSummary. [COR04020206] 11234. When the an SDO implementation creates a DataObject containing the a ChangeSummary is 1124 created, the initial logging state MUST is by defaultbe off. [COR04020203] Before any cChanges will 1125 beare logged only after , ChangeSummary.beginLogging() must beis called. 11265. The ChangeSummary will not contain the creation or deletion of its containing DataObject. 11276. Using tThe ChangeSummaryType toe MAY NOT be used to define OpenContentis restricted to 1128 defined properties, and is not allowed as toMUST NOTbe defined as an open content property is not 1129 supported. [COR04020207] 11304.2.3 ChangeSummary Scope 1131The scope of a ChangeSummary is defined as the set of DataObjects reachable from the 1132ChangeSummary root either through containment or over any orphanHolder properties. In other words 1133the scope of the change summary is the same set of DataObjects that would be in the sub-tree whose 1134root node is ChangeSummary root, if the graph were serialized to XML. 1135An SDO implementation MUST include in the ChangeSummary.changedObjects list all DataObjects that 1136were in the ChangeSummary scope when logging was activated but are not in the scope when logging 1137was deactivated (or when ChangeSummary.getChangedObjects() was called, if logging is still active) and 1138which are not themselves contained by a deleted DataObject; the implementation MUST return true when 1139such an object is passed to ChangeSummary.isDeleted. [COR04020301] An SDO implementation MUST 1140include in the ChangeSummary.changedObjects list all DataObjects that were not in the 1141ChangeSummary scope when logging was activated, but are in scope when logging was deactivated (or 1142when ChangeSummary.getChangedObjects() was called, if logging is still active) and which are not 1143themselves contained by a created DataObject; the implementation MUST return true when such an 94SDO Core Specification Version 3.0 16 December 2008 95Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 32 of 141 1144object is passed to ChangeSummary.isCreated. [COR04020302] An SDO implementation MUST include 1145in the ChangeSummary.changedObjects list all DataObjects that remained in the ChangeSummary scope 1146and whose property values changed during the time that logging was activated; the implementation 1147MUST return true when such an object is passed to ChangeSummary.isModified. [COR04020303]. The 1148changeObject MUST NOT contain any objects other than those meeting the defined criteria. 1149[COR04020304]. 1150An SDO implementation MUST return DataObjects that were in the ChangeSummary scope when logging 1151was activated but are not in the scope when logging was deactivated (or when 1152ChangeSummary.getChangedObjects() was called, if logging is still active) and which are not themselves 1153contained by a deleted DataObject MUST appear in the ChangeSummary when passed such a 1154DataObject. as deleted.An SDO implementation MUST return DataObjects that were not in the 1155ChangeSummary scope when logging was activated , but are in scope when logging was deactivated (or 1156when ChangeSummary.getChangedObjects() was called, if logging is still active) and which are not 1157themselves contained by a created DataObject MUST be appear in the when passed such a 1158DataObjectChangeSummary as created. An SDO implementation MUST return Other DataObjects within 1159the ChangeSummary scope whose property values changed during the time that logging was activated 1160MUST appear in the ChangeSummary when passed such a DataObjectas modified. 1161ChangeSummary.dDataObject 11624.2.4 OrphanHolder Properties 1163Although orphanHolder properties play a role in determining the scope of the ChangeSummary, changes 1164to the orphanHolder properties themselves are not tracked. If the only change to to the ChangeSummary 1165roota DataObject is to the contents of its orphanHolder properties, an SDO implementation MUST not 1166include the object DataObject itself MUST NOT be contained in the ChangeSummary as a modified. . 1167[COR04020401] 1168An SDO implementation MUST NOT include OrphanHolder properties MUST NOT appear in the 1169getOldValues or , getOldSequence lists. .[COR04020402] 1170The following restrictions apply to the use of orphanHolder properties together with ChangeSummaries. 11711. If an orphan DataObject is referenced from within the scope of a ChangeSummary, and if an object 1172 with a matching orphanHolder property is contained, either directly or indirectly, then the object is in 1173 scope of the ChangeSummary then . Wwhen the change summary root is serialized using 1174 XMLHelper.save, then an SDO implementation MUST serialze the orphan DataObject must MUST be 1175 serialized as being “contained” by the ChangeSummary root’s orphanHolder property. 1176 [COR04020403] 11772. All orphanHolders associated with the ChangeSummary root or any DataObjects contained, directly 1178 or indirectly by the ChangeSummary root MUST be considered in determining the scope. 11793. Orphan Holder properties are intended to be declared on envelopes and other technical DataObjects, 1180 rather than on DataObjects that are used to represent business entities. An SDO implemenation 1181 MAY ignore Defining orphanHolder properties defined on DataObjects that themselves are orphans, 1182 or that are contained by orphans., is not allowed, and MAY be ignored by implementations 1183 [COR04020404]. 11844. ChangeSummary properties are intended to be declared on envelopes and other 1185 technical DataObjects, rather than on DataObjects that are used to represent business entities. An 1186 SDO implemenation MAY ignore Defining ChangeSummary defined on DataObjects that themselves 1187 are orphans, or that are contained by orphans is not allowed, and MAY be ignored by 1188 implementations. [COR04020405] 97SDO Core Specification Version 3.0 16 December 2008 98Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 33 of 141 11894.2.5 Old Values 1190A List of old values can be retrieved using the getOldValues(DataObject dataObject) method. The order 1191of old values returned is implementation dependent. For a deleted DataObject, an SDO implementation 1192the old values List MUST containsinclude all the properties of the DataObject in the old values List. 1193[COR04020501] For a DataObject that has been modified, an SDO implementation the old values List 1194MUST containinclude only consists of the the modified properties in the the old values List. 1195[COR04020502]only. For a DataObject that has not been deleted or modified, getOLDldValues() MUST 1196return an empty the List of old values is MUST BE empty. [COR04020503]. 1197The elements of the list returned by getOldValue will be appropriate to the individual language. 1198Depending on the individual language characteristics, this mIndividual languages MAY returnethod will 1199return either a list of changed properties or a list of objects which contain the old value, the property, and 1200possibly additionalother information if desired. If a list of objects is returned, then getOldValue and 1201isOldSet are methods on the returned objects. 12024.2.6 Sequenced DataObject 1203getOldSequence(DataObject dataObject) returns the entire value of that a DataObject’s Sequence had, at 1204the point when logging began. This return value can willbe null if the Sequence was empty at the point 1205when logging began. If DataObject.getSequence() returns nullthe DataObject is not sequenced, then 1206getOldSequence(DataObject dataObject) MUSTwill return null. [COR04020601] 12074.2.7 Serialization and Deserialization 1208When a ChangeSummary is deserialized, the logging state will be on if a 1211 Changes have been logged (getChangedDataObjects().size() > 0). 1212 No changes have been logged but isLogging() is true at the time of serialization. In this case, an 1213 empty 1214The state of logging is recorded in the logging attribute of the changeSummary element. 1215The serialization of a ChangeSummary includes enough information to reconstruct the original state of all 1216DataObjects in its scope, at the point when logging was turned on. Each individual object removed from 1217the data graph must be recorded in the ChangeSummary serialization in order to perform this 1218reconstruction. The create attribute labels DataObjects currently in the data graph that were not present 1219when logging started, and the delete attribute labels objects contained in the change summary that are no 1220longer in the data graph. Labels are space-separated lists of either IDs, if available, or XPath expressions. 1221The contents of a ChangeSummary element are either deep copies of the objects at the point they were 1222deleted, or a prototype of an object that has had only data type changes, with values for the properties 1223that have changed value. 100SDO Core Specification Version 3.0 16 December 2008 101Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 34 of 141 12244.2.8 ChangeSummary Interface 1225 1226 1227The type returned by getOldValue, and the types in the List returned by getOldValues is implementation 1228language dependent. 12294.3 Sequence 1230A Sequence is an ordered collection of settings. Each entry in a Sequence has an index. 1231The key point about aA Sequence preserves is that the order of settings is preserved, even across 1232different properties. So, if Property A is updated, then Property B is updated and finally Property A is 1233updated again, a Sequence will reflect this. 1234Each setting is a property and a value. 12354.3.1 Unstructured Text 1236Unstructured text can be added to a Sequence. The addText(String text) method adds a new text entry to 1237the end of the Sequence. The addText(int index, String text) method adds a new text entry at the given 1238index of the sequence. Text entries appear in a Sequence as settings with property equal to null. 12394.3.2 Using Sequences 1240Sequences are used when dealing with semi-structured business data, for example mixed text XML 1241elements. Suppose that a Sequence has two many-valued properties, say “numbers” (a property of type 1242int) and “letters” (a property of type String). Also, suppose that the Sequence is initialized as follows: 12431. The value 1 is added to the numbers property. 12442. The String “annotation text” is added to the Sequence. 12453. The value “A” is added to the letters property 12464. The value 2 is added to the numbers property. 103SDO Core Specification Version 3.0 16 December 2008 104Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 35 of 141 12475. The value “B” is added to the letters property. 1248At the end of this initialization, the Sequence will contains the settings: 1249 { 12534.3.3 Comparing Relationship between Sequences with DataObjects 1254The way in which a DataObject keeps track of the order of properties and values is quite different from the 1255way in which a Sequence keeps track of the order. 1256The order in which different properties are added to a DataObject is not preserved. In the case of a many- 1257valued Property, the order in which different values are added to that one Property is preserved, but when 1258values are added to two different Properties, there is no way of knowing which Property was set first. In a 1259Sequence, the order of the settings across properties is preserved. 1260An SDO implementation MUST provide access to The samethe properties that appear in a Sequence are 1261MUST alsobe available through thea DataObject API. [COR04030301], The DataObject API does but 1262withoutnot provide information regarding preserving the order across properties. 1263If DataObject APIs are used to modify properties of a sequenced DataObject, then setting a Property 1264previously unset or adding a value as the last item of a many-valued Property the an SDO implementation 1265will MAY add thea value at the end of the Sequence or, if possible and at the implementation's discretion, 1266the value MAY be added in a more suitable position in the Sequence (according to the XSD definition of 1267the sequenced DataObject's Type). [COR04030306] Ifn contrast, using DataObject APIs are used to set a 1268Property that was already set an SDO implemenatation MUST happensdo so “in-place”. [COR04030302]; 1269Iin other words, setting the value of a Property using the DataObject API doesn’t does not have as side- 1270effect reordering of properties in a Sequence. For that, tThe Sequence API supports the explicit 1271reordering of values in the sequence.must be used. If a value is added to a many-valued Property as the 1272item with index “i” (rather than as the last item), then and SDO implemenation MUST insert the new value 1273MUST beis inserted in the Sequence right before the value corresponding to the item “i+1” of that many- 1274valued Property. [COR04030303]. 1275When theIf Sequence APIs are used to modify reorder a many-valued property, , then getList() invoked 1276on that property MUST have a the relative order of values in the List value for thereturned by retriving the 1277property value and in the Sequence is the sameMUSTthat reflects these changes. [COR04030304]. 1278Note that if a DataObject's Type is a sequenced type (that is, if getType().isSequenced() is true) then a 1279DataObject will have a Sequence.MUST 12804.3.4 Sequence Methods 1281The size() method returns the number of entries in the Sequence. 1282The getProperty(int index) accessor returns the Property at the given index, or null for unstructured text 1283entries. 1284The get 106SDO Core Specification Version 3.0 16 December 2008 107Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 36 of 141 1294The remove() method removes the entry at the specified index and shifts all later positions down. 1295The move() method moves the entry at the fromIndex to the toIndex, shifting entries later than fromIndex 1296down, and entries after toIndex up. 1297To create DataObjects at the end of a Sequence, the create() methods on DataObject creates 1298DataObjects at the end of a Sequence,may be used. 12994.3.5 Sequence Interface 1300 1301 13024.4 Type 1303The Type interface represents a common view of the model of a DataObject or of a data type. 1304The concept of a data type is shared by most programming languages and data modeling languages; and 1305SDO Types can be compared with other data types. An SDO Type has a set of Property objects, unless it 1306represents a simple data type. 13074.4.1 Mapping SDO Types to Programming and Data Modeling Languages 1308Java, C++ or UML Class 1309 Class can be represented by an SDO Type. 109SDO Core Specification Version 3.0 16 December 2008 110Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 37 of 141 1310 Each field of the Class can be represented by an SDO Property. 1311XML Schema 1312 Complex and simple types can be represented by SDO Types. 1313 Elements and attributes can be represented by SDO Properties. 1314C Struct 1315 C Struct can be represented by an SDO Type 1316 Each field of the Struct can be represented by an SDO Property. 1317Relational database 1318 Table can be represented by an SDO Type. 1319 Column can be represented by an SDO Property. 1320 1321All of these domains share certain concepts, a small subset of which is represented in the SDO Type and 1322Property interfaces. These interfaces are useful for DataObject programmers who need to introspect the 1323shape or nature of data at runtime. 1324More complete metamodel APIs (for example, to inspect XML Schema or UML model from which the 1325SDO metadata is derived) representing all the information of a particular domain are outside the scope of 1326this specification. 13274.4.2 Type Contents 1328A Type will always have: 1329 Name - A String that must isbe required to be unique among the Types that belong to the same 1330 URI in the same HelperContext. An SDO implemenation MUST raise an error if dDefining a 1331 Types with duplicate in the type names or aliases results in undefined behavior.would result in a 1332 duplicate name or the name would duplicate an alias of an existing Type. [COR04040201] 1333 URI - The logical URI of a package or a target namespace, depending upon your perspective. 1334 Boolean fields indicating if the type is open, abstract, sequenced, or a data type. 1335 1336A Type can have: 1337 Properties - a list of Property objects defined by this Type. Types corresponding to simple data 1338 types define no properties. 1339 Aliases - Strings containing additional names. Alias Names must beare required to be unique 1340 within a URI. An SDO implemenation MUST raise an error if defining a Type would result in a 1341 duplicate alias or an alias would duplicate the name of an existing Type. [COR04040202] 1342 Duplicates in the names or aliases of types results in undefined behavior. All methods that 1343 operate on a Type by name also accept alias names. For example, a Type might be assigned an 1344 alias name for the domains it is used in: an XML Schema name "PurchaseOrderType", a Java 1345 name "PurchaseOrder" and a database table name "PRCHORDR". 1346 Instance properties – open content metadata extensions attached to the Type instance. 1347 Base types – a list of base Types. All the properties declared on the base types are also inherited 1348 by the current Type and DataObjects of this Type are substitutable for DataObjects of any of the 1349 base Types. 1350 Key type - the Type of values that are used to uniquely identify instances of this Type. 112SDO Core Specification Version 3.0 16 December 2008 113Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 38 of 141 13514.4.3 Name Uniqueness 1352Within a single HelperContext, the combination of a URI and a Type name or alias name uniquely 1353identifies the Type. Other HelperContexts potentiallymay have different (and conflicting) definitions for 1354Types having the same URI and name. 1355 1356Property names and Property alias names are all unique within a Type and any base Types. 1357 4.4.4 Compatibility Between Types 1358Types in different HelperContexts may potentially represent the same underlying business data. Often 1359Types in different contexts are closely enough related that it is possible to transfer the business data 1360between the contexts using the DataHelper.project() method. Types that are closely enough related to 1361allow this are termed compatible Types. 1362Two types, T1 and T2, are considered compatible if their definitions are identical or differ only in the 1363following ways: 13641) If neither T1 nor T2 is a DataType, then the implementation type (in Java, the instanceClass) is 1365 allowed to may differ, or may bebe absent in one of the types. 13662) If both T1 and T2 are DataTypes, then they may are allowed to differ as long as the implementation 1367 type (in Java, the instanceClass) is the same, and the types are compatible according to the 1368 conversion table in Chapter11: 16 DataType Conversions. 13693) T1.name != T2.name or T1.aliasNames != T2.aliasNames, provided there is a matching name in the 1370 two sets of names 13714) Corresponding properties P1.name != P2.name or P1.aliasNames != P2.aliasNames, provided there 1372 is a matching name in the two sets of names 13735) Corresponding properties P1.containment != P2.containment 13746) Corresponding properties P1.type and P2.type, and P1.type not a data type, then P2.type could be 1375 the key type of P1.type (see section 4.5.3: Key Properties) 1376An SDO Iimplementations MUST not have a more restrictive set of conditions for compatibility than 1377defined by this specification, it MAYmay choose to loosen these conditions. [COR04040401] 1378requirements on compatibility, fFor instanceexample, an implementation may MAYmight choose to allow 1379the set of properties in T1 to be a subset of the properties in T2. An implementation definition of 1380compatibility may not cannot be made more restrictive. 13814.4.5 Data Types 1382A data type is used to represent the value of properties that are not DataObjects. A Type is a data type if 1383Type.isDataType() returns true. 1384SDO defines Types for the common data types supported in SDO, enabling more consistency in defining 1385the Types and Properties used by services. Refer to section 6.1: SDO Data Types, for more details. 1386Multiple calls to DataObject.get() for a data type property may MAYcan return different objects as long as 1387equals() is true. For mutable data values (Date and List of Strings for example), modification of those 1388values directly is implementation dependent. 13894.4.6 Data Type Wrappers 1390Wrapper types are special types used to hold a dataType value in situaltions where a DataObject is 1391required (for example, an XMLDocument rootObject or for the value of an xsd:anyType property). A 1392wrapper type contains a single property with name “value” and type equal to that of the dataType (or a 1393base type such as SDO Object) for which it is a wrapper. The “value” property is used to get or set the 1394dataType value. The actual type of a wrapper DataObject is implementation dependent, but it will 115SDO Core Specification Version 3.0 16 December 2008 116Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 39 of 141 1395alwaysMUST extend from the SDO type {http://docs.oasis- 1396open.org/ns/opencsa/sdo/200812}DataTypeWrapper. [COR04040601] Users can use test for this type to 1397determine when a DataObject is a wrapper. For example: 1398 1399 DataObject someObject = dataObject.getDataObject(someAnyTypeProperty); 1400 Type wrapperType = typeHelper.getType(TypeHelper.SDO_URI, "DataTypeWrapper"); 1401 if (wrapperType.isInstance(someObject)) { 1402 // "someObject" is a data type wrapper 1403 Object simpleValue = someObject.get("value"); // get the actual value 1404 ... 1405 } 14064.4.7 Multiple Inheritance 1407Type supports multiple inheritance by allowing multiple base types. When multiple inheritance is used, the 1408order of Properties in getProperties() may differ between a Type and the order in the base Types MAYcan 1409differ. 14104.4.8 Type Instance Properties 1411Open content (metadata extensions) can be added to SDO Type and Property instances. 1412For example, open content can be added to a Type when it is being defined: 1413 1414 // Create a new Type and with an open content property set 1415 DataObject myDataType = dataFactory.create(SDO_URI"commonj.sdo", "Type"); 1416 myDataType.set("name", "MyType"); 1417 ... 1418 Property openContentProperty = 1419 typeHelper.getOpenContentProperty("someURI", "someProperty"); 1420 myDataType.set(openContentProperty, someValue); 1421 1422 // Define the Type 1423 Type definedType = typeHelper.define(myDataType); 1424 1425Although an SDO implementation’s definedthe Types and Property objects returned from TypeHelper, 1426DataObject.getType, etc.,ies are need not required to implement the entire DataObject interface, theyan 1427SDO implemenation will MUST support access to open content using the getInstanceProperties() and 1428get(Property) methods on the objects. [COR04040801] For example, the open content property, added 1429above, can be retrieved from the defined type by calling a get 1433 1434In addition to the open content properties explicitly added by users, SDO implementations may, but are 1435not required toMAYmight provide additional instance properties. For example, XSD facet constraints for 1436Types defined using XSDHelpder.define(String) may MAYmight be included. If provided by an 1437implementation, such facets would SHOULD appear in the list returned by getInstanceProperties(). 1438[COR04040802]: 1439 1440 for (Iterator i = definedType.getInstanceProperties(); i.hasNext(); ) { 1441 Property property = (Property)i.next(); 1442 if (property.name().equals("maxInclusive")) { 1443 Object maxInclusive = myType.get(property); 118SDO Core Specification Version 3.0 16 December 2008 119Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 40 of 141 1444 ... // do something with maxInclusive 1445 } 1446 } 1447 1448Future versions of SDO are expected to define standard properties for XSD facets. 1449 1450 Property maxInclusiveProperty = ... // get the maxInclusive property 1451 Object maxInclusive = definedType.getString(maxInclusiveProperty); 14524.4.9 Type Methods 1453getName() returns the Type Name. 1454getURI() returns the Type URI. 1455getInstanceClass() returns the Class used to implement the SDO Type. 1456isInstance(Object object) returns true if the specified object is an instance of this Type. 1457isDataType() returns true if this Type specifies DataTypes and returns false for DataObjects. 1458isSequenced() returns true if this Type specifies Sequenced DataObjects. When true, a DataObject can 1459return a Sequence. 1460isOpen() returns true if this Type allows open content. If false, then dataObject.getInstanceProperties() 1461must isbe the same as dataObject.getType().getProperties() for any DataObject of this Type. 1462isAbstract() returns true if this Type is abstract, that is cannot be instantiated. Abstract types cannot be 1463used in DataObject or DataFactory create methods. Abstract types typically serve as the base Types for 1464instantiable Types. 1465getBaseTypes() returns a List of base Types for this Type. The list is empty if there are no base Types. 1466XSD 121SDO Core Specification Version 3.0 16 December 2008 122Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 41 of 141 14774.4.10 Type Interface 1478 1479 14804.5 Property 1481A DataObject is made up of Property values. 1482A Property has: 124SDO Core Specification Version 3.0 16 December 2008 125Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 42 of 141 1483 Name - a String that is unique among the Properties of the containing Type. An SDO 1484 implemenation MUST raise an error if defining a Property would result in a duplicate name or the 1485 name would duplicate an alias of an existing Property. [COR040501001] 1486 Type - the Type of this Property. A Property whose Type is for DataObjects is sometimes called a 1487 reference; otherwise it is called an attribute. 1488 Containment - whether the property is a containment property. A property with containment true 1489 is called a containment property. 1490 Many - whether the property is single-valued or many-valued. 1491 ReadOnly - whether it is allowed to modify the property may be modified through the DataObject 1492 or the generated API. 1493 Alias names - alternative names that must beare unique within the Type. An SDO implemenation 1494 MUST raise an error if defining a Property would result in a duplicate alias or an alias would 1495 duplicate the name of an existing Property. [COR0404502002] A Property might be assigned an 1496 alias name for the domains it is used in, such as an XMLSchema name "firstName", a Java name 1497 "first_name", and a database column name, "FRSTNAME". All Property names and all alias 1498 names for Properties must beare unique for all Properties in Type.getProperties(). 1499 Default value. 1500 Nullable – whether the property can be set to null. 1501 Key – whether the property is a key property. A property with key true is called a key property. 1502 Instance properties – open content metadata extensions attached to the Property instance. 1503 Numeric index within the Property’s Type. 15044.5.1 Property Index 1505Each Type assigns a unique index to each Property that belongs to a DataObject. The index can be 1506accessed in the List returned by Type.getProperties(). 15074.5.2 Containment 1508In the case of a reference, a Property may beis either a containment or non-containment reference. In 1509XML, elements with complex types are mapped to containment properties while elements and attributes 1510with type IDREF are mapped to non-containment properties. Containment also maps to the UML concept 1511of aggregation, and non-containment to association. 1512A Property with containment true is called a containment property. Containment properties show the 1513parent-child relationships in a tree of DataObjects. 15144.5.3 Key Properties 1515Key properties are used to identify one or more properties of a type that combine to form a value that 1516within a data graph uniquely identifies objects of the type. The concept of object identity also maps to 1517various data source technologies, for instance, to primary keys in a relational database, but such a 1518mapping is beyond the scope of this specification. Within SDO, keys influence the XML serialization of 1519non-containment references (see Section 8.3:Tuning the Default Mapping using Open Content 1520PropertiesGenerating XSD from Types using Keys) and also influence projection (see Keys and 1521Projection). 1522A property with key true is called a key property. A Property key can be set to true only when isMany is 1523false and either of the following is true: 1524 The type of the property is a DataType. The use of “approximate” types such as float and double is 1525 discouraged and may the resulting in non-portable code will not be portable. 1526 The type of the property is not a DataType, but itself has or is a key type. 127SDO Core Specification Version 3.0 16 December 2008 128Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 43 of 141 1527A key type is the type of the (possibly composite) key associated with a type. Any type with at least one 1528key property has a key type. In any type for which one or more keys has been defined, it is possible to 1529set Tthe key type may be set explicitly using the keyType property on a Type containing keys. If the key 1530typeit is not explicitly set, and SDO implemenation MUST derive its default value MUST BEis derived 1531according to the following algorithm [COR04050301]: 1532 If there is exactly one key property, and its type is a DataType, then the key type is the type of the key 1533 property. 1534 If there is exactly one key property and its type is not a DataType, then the key type is the key type of 1535 the key property’s type. [COR04050301] 1536If a type contains more than one key property, or the key property is an embedded key (see below), then 1537the type must is requiredhas to have the keyType property set. The value of this property must is 1538requiredhas to be a type such that for every key property (or key component of an embedded key) the key 1539type also contains a corresponding property. If a key property’s type is a DataType, then the 1540corresponding property in the keyType must is requiredhas to have the same type as the key property. If 1541the key property’s type is not a DataType, then the type of the corresponding property is the key type 1542associated with the key property’s type. An SDO implementation must MUST check that the specified key 1543type matches the defined key properties, and throw raise an exception error if the key type and the key 1544properties do not match. [COR04050302] 1545Example 1546OrderType 1547 - id (type=String, key=true) 1548 - customer (type=CustomerType) 1549 - lineItems (type=LineItemType, many=true, opposite=order) 1550 1551LineItemType (keyType=LineItemKeyType) 1552 - order (type=OrderType key=true opposite=lineItems) 1553 - lineNumber (type=Int, key=true) 1554 - productID, etc. 1556LineItemKeyType 1557 - order (type=String) 1558 - lineNumber (type=Int) 1559 1560In the example, “id” has been specified as the single key property for OrderType, giving OrderType a 1561keyType of String. LineItemType has a two-part key, “order” and “lineNumber”. Because LineItemType 1562uses a multi-part key, it explicitly declares a key type. The complex key type, LineItemKeyType, has 1563properties corresponding to each of LineItemType’s key properties. Notice that the order property in 1564LineItemKeyType has type String, the key type of the corresponding property in LineItemType. 1565 1566Some It is possible to declare a composite key be used DataObjects may wish to use their composite key 1567type directly as a property of a DataObject. This is referred to as an embedded key. In this case, 1568LineItemType can be defined as follows: 1569 1570LineItemType (keyType=LineItemKeyType) 1571 - lineItemKey (type=LineItemKeyType key=true, containment=”true”) 1572 - productID, etc. 1573 130SDO Core Specification Version 3.0 16 December 2008 131Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 44 of 141 1574Here the key type of LineItemType is set to the same type as the key property itself (lineItemKey), which 1575must is requiredhas to be a containment reference, indicating the use of an embedded key. 15764.5.4 Read-Only Properties 1577Read-Only Properties cannot be modified using the SDO APIs. When DataObject.delete() is invoked, 1578read-only Properties are not changed. Any attempt to alter read-only Properties using 1579DataObject.set(Property property, Object value) or unset() results in an exceptionerror. 1580Read-Only Properties can be modified by a service using implementation-specific means. For example, 1581suppose a relational database service returns a DataObject in which the customerName Property is 1582marked read-only. If the DataObject is passed back to the service, the value of the customerName could 1583be updated by the service to the current value in the database. 15844.5.5 Nullable Properties 1585It is possible that Ssetting the value of a property to null may or may not beis not allowed for a given 1586property. For example, a property that does not map to a nillable XML element or that maps to a non- 1587nullable RDB column, cannot be set to null. A property that can be set to null is called a nullable property. 1588Calling get() on a property that is not nullable may MAYmight still return a null value, if the default value of 1589the property is null and it is currently unset. Calling set(null) on a non-nullable property will produce 1590implementation dependent results; . either an error will be raised or It may MAY throw an exception or, 1591alternatively, it may MAY cause the property towill become unset. 1592For the particular case where a pair of opposite properties have differing values for nullable 1593 1. Calling o1.set(nullableProperty, null) has the secondary effect that o2.isSet(nonNullableProperty) 1594 returns false, and 1595 2. calling o2.unset(nonNullableProperty) has the secondary effect that o1.isSet(nullableProperty) 1596 returns false 15974.5.6 Open Content Properties 1598Open content properties are ones that can be used to set open content (instance properties) on an open 1599type. They are typically created using TypeHelper.defineOpenContentProperty() or demand-created by 1600calling DataObject.set() on an open object. XSD global properties (elements and attributes) also map to 1601open content properties. 16024.5.7 Property Instance Properties 1603Property instances can themselves include open content, that is, extended metadata in the form of 1604instance properties. The list of such extensions is available by calling Property.getInstanceProperties(). 1605The values of these properties are available by calling Property.get(Property). For more details, see 4.4.8 1606Type Instance Properties. 1607getName() returns the Property Name. 1608getType() returns the Property Type. 1609isMany() returns true if the Property is many-valued, or false if the Property is single-valued. 1610isContainment() returns true if the Property is a containment reference and always returns false for data 1611type properties. 1612isReadOnly() returns true if values for this Property cannot be modified using the SDO APIs. 1613getContainingType() returns the Type that declares this Property. 1614getAliasNames() returns a list of alias names for this Property. 1615getOpposite() returns the opposite Property, if the Property is bidirectional, otherwise returns null. 1616getDefault() returns the default value (as an Object). 1617isNullable() returns true if instances of this property can be set to null. 133SDO Core Specification Version 3.0 16 December 2008 134Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 45 of 141 1618isKey() returns true if the property is a key property for its containing Type. 1619isOpenContent() returns true if this is a Property for setting open content. 1620getInstanceProperties() returns a read-only List of instance Properties available on this Property. 1621get(Property property) returns the value of the specified instance property of this Property. 16224.5.8 Property Interface 1623 16244.6 HelperContext 1625A HelperContext provides access to a consistent set of SDO helpers. This is intended to allow 1626applications to define metadata that is independent of and protected from metadata in other applications. 1627The set of helpers returned by a single context have access to the same SDO metadata, that is, 1628HelperContexts define the scope or visibility of a set of SDO types. 1629Every SDO type is conceptually contained by (associated with) the HelperContext from which it is 1630retrieved. Since every DataObject has a type, every DataObject is, in turn, indirectly associated with a 1631HelperContext. In order to assure consistent behaviour, it is required thatan SDO implementation MUST 1632ensure that every DataObject in a data graph, that is, in the transitive closure reachable from some root 1633node,, must be is associated with the same HelperContext. [COR04060001] 16344.6.1 Default HelperContext 1635The default HelperContext is accessed in a language specific manner. 1636Default helpers can be accessed using the get() methods of the default HelperContext. 136SDO Core Specification Version 3.0 16 December 2008 137Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 46 of 141 16374.6.2 Non-DefaultHelperContext 1638HelperContext objects other than the default can be created using a HelperContextFactory. 1639 16404.6.3 HelperContext Interface 1641 1642 16434.7 DataFactory 1644A DataFactory is a helper for the creation of DataObjects. The created DataObjects are not connected to 1645any other DataObjects. 139SDO Core Specification Version 3.0 16 December 2008 140Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 47 of 141 16464.7.1 Default DataFactory 1647The default DataFactory is available from getDataFactory() of the default HelperContext (see 4.6: 1648HelperContext). It is configured in an implementation-specific fashion to determine which Types are 1649available and what instance classes are instantiated. 1650An SDO iImplementation MUST of create DataFactory instances thatMUST use the TypeHelper that is 1651associated with the same HelperContext as the DatFactory instance. [COR04070101] For 1652instanceexample, tThe default DataFactory usess the default TypeHelper 1653DataFactory.create(String, String) is a shortcut to 1654 DataFactory dataFactory = helperContext.getDataFactory(); 1655 TypeHelper typeHelper = HelperContext.getTypeHelper(); 1656 DataFactorydataFactory.create(TypeHelpertypeHelper.getType(String, String)). 1657A DataFactory other than the default may have access to a different type helper. 16584.7.2 Creating DataObjects 1659For all create methods: 1660 Type.abstract must is requiredhas to be false. 1661 If Type.dataType is true, then a wrapper DataObject is returned (see Data Type WrappersData 1662 Type Wrappers), on which a property with name “value” and type Type or SDO Object can then 1663 be set. 1664 The Type's getInstanceClass() method returns the same object as the interfaceClass parameter. 1665 Throw an IllegalArgumentException if the instanceClass does not correspond to a Type this 1666 factory can instantiate. 1667 The created DataObject implements the DataObject interface and the interface specified by the 1668 Type.instanceClass, if one exists. There is always an SDO Type and instance relationship and 1669 there can also be a Java Class and instance relationship. If there is a Java instance class 1670 specified on the Type then both the SDO and the Java relationships hold. 1671 The created object's getType() will MUST return the Type used in the call to DataFactory.create(), 1672 and the Type.isInstance() MUSTwill return true for the created object.[COR04070201] 1673 When instantiating a Type that has an InstanceClass then the object returned from the create 1674 MUST instantiate it. [COR04070202] 1675 1676 1677create(String uri, String typeName) 1678 Creates a DataObject of the Type specified by typeName with the given package uri. 1679 The uri and typeName parameters uniquely identify a Type from the metadata. 1680 The effect of this call is the same as determining the Type for the uri and typeName and calling 1681 the create(Type) method 1682 This method applies to Types whether they have instance classes or not. If the Type has an 1683 InstanceClass then the returned object will be an instance. 1684 1685create(Type type) 1686 Creates a DataObject of the Type specified. 1687 This method applies to Types whether they have instance classes or not. If the Type has an 1688 instance class then the returned object will be an instance. 1689 142SDO Core Specification Version 3.0 16 December 2008 143Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 48 of 141 1690NOTE: There is a special case iIf the Type used in a create() method has a property of type SDO 1691ChangeSummaryType. In this case, an SDO implementation MUST the created the DataOobject will 1692MUST be associated with a new ChangeSummary instance and with change logging will beturned off. 1693[COR04070203] 16944.7.3 DataFactory Interface 1695 16964.8 TypeHelper 1697A TypeHelper is a helper for looking up and dynamically defining new SDO Types. It also provides 1698constants for the namespaces containing predefined SDO types and properties: 1699 1700 SDO_URI = "http://docs.oasis-open.org/ns/opencsa/sdo/200812" 1701 SDO_XML_URI = "http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812" 17024.8.1 Default TypeHelper 1703The default TypeHelper is available from getTypeHelper() of the default HelperContext (see 4.6: 1704HelperContext) It is configured in an implementation-specific fashion to determine which Types are 1705available and what instance classes are known. 1706When SDO methods have String parameters to specify the name and URI of a Type, the behavior is the 1707same as if they had used TypeHelper getType() with the same parameters. The scope of the types 1708available through any SDO API includes all those available through the default TypeHelper. 17094.8.2 Defining SDO Types Dynamically 1710It is possible to define new SDO Types dynamically using TypeHelper. For example, to define a new 1711Customer Type, the you could use the TypeHelper can be used as follows: 1712 1713 HelperContext helperContext = SDO.getDefaultHelperContext(); 1714 1715 TypeHelper types = helperContext.getTypeHelper(); 1716 Type intType = types.getType(SDO_URI"commonj.sdo", "Int"); 1717 Type stringType = types.getType(SDO_URI"commonj.sdo", "String"); 1718 1719 // create a new Type for Customers 1720 DataObject customerType = helperContext.getDataFactory() 1721 .create(SDO_URI"commonj.sdo", "Type"); 1722 customerType.set("uri", "http://www.example.com/customer"); 1723 customerType.set("name", "Customer"); 1724 1725 // create a customer number property 1726 DataObject custNumProperty = customerType.createDataObject("property"); 1727 custNumProperty.set("name", "custNum"); 1728 custNumProperty.set("type", intType); 1729 1730 // create a first name property 1731 DataObject firstNameProperty = customerType.createDataObject("property"); 1732 firstNameProperty.set("name", "firstName"); 1733 firstNameProperty.set("type", stringType); 1734 145SDO Core Specification Version 3.0 16 December 2008 146Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 49 of 141 1735 // create a last name property 1736 DataObject lastNameProperty = customerType.createDataObject("property"); 1737 lastNameProperty.set("name", "lastName"); 1738 lastNameProperty.set("type", stringType); 1739 1740 // now define the Customer type so that customers can be made 1741 types.define(customerType); 1742 1743An SDO iWhen calling the property.set(“type”, sdotype) method, tImplementations MUST allow the 1744“sdotype” argument in the property.set(“type”, sdotype) method, and in all setters that take Types as 1745arguments, tocan be either an instance of {http://docs.oasis- 1746open.org/ns/opencsa/sdo/200812}commonj.sdo.commonj.sdo.Type or a DataObject of type 1747{http://docs.oasis-open.org/ns/opencsa/sdo/200812}Type. [COR04080201] If the latter, the defined type is 1748implicitly registered when the Property is created, just as the Property is implicitly created when the Type 1749is registered (e.g., through a call to TypeHelper.define(). Similarly, any base types referenced in the 1750property definition may be either Type objects or DataObejcts where getType is “{http://docs.oasis- 1751open.org/ns/opencsa/sdo/200812}Type. An SDO implementation MUST define all directly or indirectly 1752referenced Types, and their properties when the referencing Type is defined (e.g., through a call to 1753TypeHelper.define()). [COR04080202] that DataObject must also be passed to the same 1754TypeHelper.define() call as the DataObject containing the property. 17554.8.3 Using SDO Dynamic Types 1756To use the dynamically created Customer Type you could dothe DataFactory API could be used as 1757follows: 1758 1759 1760 DataFactory factory = SDO.getDefaultHelperContext().getDataFactory(); 1761 1762 DataObject customer1 = factory.create("http://www.example.com/customer", 1763 "Customer"); 1764 customer1.setInt("custNum", 1); 1765 customer1.set("firstName", "John"); 1766 customer1.set("lastName", "Adams"); 1767 1768 DataObject customer2 = factory.create("http://www.example.com/customer", 1769 "Customer"); 1770 customer2.setInt("custNum", 2); 1771 customer2.set("firstName", "Jeremy"); 1772 customer2.set("lastName", "Pavick"); 17734.8.4 Defining and Using Open Content Properties 1774Clients use open content properties to set instance properties on a data object. For example: 1775 1776 // Define a new SDO open content property with simple type 1777 DataObject p = dataFactory.create(SDO_URI"commonj.sdo", "Property"); 1778 p.set("type", typeHelper.getType(SDO_URI"commonj.sdo", "Decimal")); 1779 p.set("name", "someName"); 1780 Property openProperty = 1781 typeHelper.defineOpenContentProperty("someURI", p); 1782 1783 // Set an instance property on an open type DataObject 1784 openDataObject.setBigDecimal(openProperty, new BigDecimal("1100.0")); 1785 148SDO Core Specification Version 3.0 16 December 2008 149Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 50 of 141 1786Properties defined through Calling TypeHelper.defineOpenContentProperty(uri, p) with a non-null 1787uridefine a Property as if , has the same effect as a global element declaration with a type compatible with 1788p existed in a sccan be used like global properties defined through loading schema with targetNamespace 1789equal to the specified uri. [COR04080401] Therefore, sSuch an open content property MUSTis also be 1790available by calling XSDHelper.getGlobalProperty(uri, propertyName, true). and, just as [COR04080402] 1791Conversely, XSD global properties created by XSDHelper.define() are MUST also be available by calling 1792TypeHelper.getOpenContentProperty()., [COR040804013] 1793 1794 openProperty = typeHelper.getOpenContentProperty("someURI", "someName"); 1795 1796A null uri can also be passed to the TypeHelper.defineOpenContentProperty() method: 1797 1798 openProperty = typeHelper.defineOpenContentProperty(null, p); 1799 1800In this case, the created property's location (containingType) is implementation dependent. Such open 1801content properties are not available by calling TypeHelper.getOpenContentProperty() or 1802XSDHelper.getGlobalProperty(). This type of property is equivalent to an on-demand open content 1803property, as described in 4.1.9: Open Content DataObject Properties. 1804The XSD representation of an open content property that was created with a non-null uri argument, can 1805be generated by calling: 1806 1807 xsdHelper.generate( 1808 Collections.singletonList(openProperty.getContainingType()) 1809 ); 1810 1811An XSD representation cannot be generated for open content properties, created with a null uri. 18124.8.5 TypeHelper Methods 1813getType(String uri, String typeName) returns the Type specified by typeName with the given uri, or null if 1814not found. 1815getOpenContentProperty(String uri, String propertyName) returns the open content (global) Property with 1816the specified uri and name, or null if not found. 1817define(DataObject type) defines the DataObject as a Type.; IAn SDO implemenation MUST raise an 1818error iIif a type with the same name and URI already exists, the SDO implementation MUST NOT redefine 1819the existing type, this operation has MUST NOT no effectmodify the existing type. [COR04080501] 1820define(List types) defines the list of DataObjects as Types.; Iif some of the types in the list have the same 1821name/URI combination as types that already exist, the SDO implementation MUST NOTn thoseredefine 1822the existing types and are not processed; the corresponding entries in the List returned will MUST have 1823references to the already-existing types. [COR04080502] 1824defineOpenContentProperty(String uri, DataObject property) defines the DataObject as a Property for 1825setting open content. 151SDO Core Specification Version 3.0 16 December 2008 152Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 51 of 141 18264.8.6 TypeHelper Interface 1827 18284.9 CopyHelper 1829A CopyHelper creates copies of DataObjects. 18304.9.1 Default CopyHelper 1831The default CopyHelper is available from getCopyHelper() of the default HelperContext HelperContext 1832(see 4.6: HelperContext). 18334.9.2 Shallow Copies 1834copyShallow(DataObject dataObject) creates a new DataObject. The copyShallow() method MUST 1835create a DataObject with the For each Property where property.type.dataType is true, the created 1836DataObject MUST have with the same values as the source dataObject for each Property of the source 1837DataObject where property.type.dataType is true, including read-only properties, and for each Propertyt of 1838the Data Object were property.type.dataType is false, that property MUST be unset in the new 1839DataObject.,. [COR04090201] for each Property where property.type.dataType is true. Read-only 1840properties MUST be copied. [COR04090202] 1841If the source’s property.type.dataType is false, then that property MUST beis unset in the copied 1842DataObject. [COR04090203]Read-only properties are copied. 1843For single-valued Properties: 1844 copiedDataObject.get(property) <==> dataObject.get(property). 1845For many-valued Properties: 1846 copiedDataObject.getList(property).get(i) <==> dataObject.getList(property).get(i). 1847Where <==> means equals() for DataType Properties or the corresponding copied DataObject for 1848DataObject Properties. 1849A copied object shares metadata with the source object. For example: 1850 sourceDataObject.getType() == copiedDataObject.getType(). 1851If a ChangeSummary is part of the source DataObject then copyShallow() the copy has MUST 1852havecreate a new, empty ChangeSummary that is associated with the new DataObject and t. The logging 1853state of the new ChangeSummary MUST BEis the same as the source ChangeSummary. 1854[COR04090204] 18554.9.3 Deep Copies 1856copy(DataObject dataObject) creates a deep copy of the DataObject tree, that is it copies the dataObject 1857and all its contained DataObjects recursively. 1858The copy() method MUST create a DataObject with the same values as in the shallow copy fFor each 1859Property of the source DataObject where property.getType().isDataType() is true, the deep copy 1860operation MUST the values of the Properties are copied as in the shallow copy. Read-only properties are 1861copied. [COR04090301] 154SDO Core Specification Version 3.0 16 December 2008 155Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 52 of 141 1862The copy() method MUST make a deep copy of the value fFor each containment Property of the source 1863DatObject where the value is a DataObject, the deep copy operation MUST making a deep copy of the 1864value property.getType().isDataType() is false, the value is copied. [COR04090302] if it is a DataObject 1865contained by the source dataObject. 1866The copy() method MUST NOT copy a value that is a reference to If a property’s value is a reference to a 1867DataObject is outside the copy tree for any bidirectional property of the source DataObject and the 1868property is bidirectional, then the DataObjectdeep copy operation is MUST NOTnot copy the data 1869objectcopied and references to the object are also not copied. [COR04090303] If a unidirectional 1870property’s value is a reference to a DataObject is outside the copy tree and the property is unidirectional, 1871then the same DataObject the copy() method deep copy operation MUST is set the value in the new 1872DataObject to reference the same DataObject as the source DataObjectd. [COR04090304]. 1873If a ChangeSummary is part of the copy tree, the copy() method MUST create a new ChangeSummary 1874with then the contents of the copied ChangeSummary (e.g., the list of changedObjects) MUSTthat 1875correspond to the values in the source ChangeSummary, with the copiednew ChangeSummary referrings 1876to objects in the copiednew DataObject tree and logging state the same as the source Change Summary. 1877[COR04090305] The logging state is the same as for the source ChangeSummary. 18784.9.4 CopyHelper Methods 1879DataObject copyShallow(DataObject dataObject) creates a shallow copy of the dataObject. 1880DataObject copy(DataObject dataObject) creates a deep copy of the dataObject tree. 18814.9.5 CopyHelper Interface 1882 18834.10 EqualityHelper 1884An EqualityHelper compares DataObjects to decide if they are equal. 18854.10.1 Default EqualityHelper 1886The default EqualityHelper is available from getEqualityHelper() of the default HelperContext (see 4.6: 1887HelperContext). 18884.10.2 EqualityHelper Methods 1889equalShallow(DataObject dataObject1, DataObject dataObject2) returns true if two DataObjects have the 1890same Type, and all their compared datatype Properties are equal. 1891equal(DataObject dataObject1, DataObject dataObject2) returns true if two DataObjects are 1892equalShallow(), all their compared Properties are equal, and all the values of their compared DataObject 1893Properties are equal, recursively. 1894When testing for equality of the values of Properties for which isMany() is true, the order in which the 1895values appear is significant. 1896When testing for equality of values of Types for which isSequenced() is true, order of property/value pairs 1897inside the sequence is significant. 157SDO Core Specification Version 3.0 16 December 2008 158Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 53 of 141 18984.10.3 EqualityHelper Interface 1899 19004.11 XMLHelper 1901An XMLHelper converts XML to and from graphs of DataObjects. 1902XMLHelper can be used with or without an XSD. All closed trees of DataObjects are supported, whether 1903or not an XSD was specified. However, the XML will use an XSD if one is used to define the DataObjects. 1905XMLHelper supports the case where a DataObjects's Types and Properties did not originate in an XSD. It 1906does this by writing XML documents that follow the Generation of XSDs portion of this specification. 19074.11.1 Default XMLHelper 1908The default XMLHelper is available from getXMLHelper() of the default HelperContext (see Section 4.6: 1909HelperContext). It is configured in an implementation-specific fashion to determine which Types are 1910available. 19114.11.2 Loading and Saving XML Documents 1912The XMLHelper and XMLDocument do not change the state of the input DataObject and ignore any 1913containers. After load, the root DataObject created does not have a containing DataObject. 1914When loading XML documents, typically the Types and Properties are already defined, for example from 1915an XSD. If there are no definitions, the Section 7.11, XML without Schema to SDO Type and 1916Property,XML without Schema to XSD is used defines the behaviour when metadata is not available. In 1917some situations, the definitions of the Types and Properties have changed relative to the software that 1918has originally written the document, often called schema evolution. SDO does not directly address 1919schema evolution, which is an issue broader than SDO, but the general guideline is to use the same URI 1920for compatible XML documents and different URIs for incompatible XML documents. 19214.11.3 XML SchemasDetermining the Type of XML Elements 1922Often, it is desirable to validate XML documents with an XSD. To ensure validation, it is required that the 1923root element name and URI must correspond to a global element name and target namespace in an XSD. 1924If an XSD is not being used, for example when the schema types were created dynamically with 1925TypeHelper, then it is recommended that root elements also be created, using 1926TypeHelper.defineOpenContentProperty() be used to define the root element. This improves integration 1927with software that does make use of XSDs. 1928In cases where the schema is unavailable, or does not give sufficient information regarding a value’s type, 1929or where global elements are not appropriate, xsi:type may also be used as provides an alternate means 1930for specifying the type of an document’s root element. An SDO Implementaion MUST generate an 1931xsi:type annotation in the serialization of DataObjects whenever the Type of the DataObject is not the 1932same as the type of the element, e.g., when polymorphism occurs in the object model, but there are no 1933corresponding substitution group defined in the XSD. [COR04110301]The following conventions apply: 1934 1935The same rule applies wWhen saving the root element, an xsi:type may always be written in the XML to 1936record the root DataObject's Type. If the schema already provides enough information to determine the 1937type, for instance, if rootElementURI and rootElementName correspond to a valid global element for the 1938root DataObject's Type, then thean implementation does not need to generate an xsi:type attribute. 1939Otherwise, should suppress anthe xsi:type attribute will be generated. 160SDO Core Specification Version 3.0 16 December 2008 161Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 54 of 141 1940When marshalling anloading the root element having an xsi:type declaration into a DataObject, if an 1941xsi:type declaration is found, it is the SDO implementation MUST used as the type of the rootcreate an 1942DataObject with the indicated type. [COR04110302] Unless XSD validation is being performed, it is not 1943an error if the rootElementURI and rootElementName do not correspond to a valid global element. 1944It is possible to use Tthe root element "http://docs.oasis-open.org/ns/opencsa/sdo/200812", "dataObject" 1945may be used within combination with any DataObject if xsi:type is also written for the actual DataObject's 1946Typeto serialized or de-serialize any DataObject. 1947To enable XML support for DataObjects when multiple inheritance is used, an additional convention is 1948applied, since XSD cannot support multiple inheritance, but an SDO implementation MUST be able to 1949marshal and unmarshal between SDO objects that use multiple inheritance and well-formed XML 1950documents. [COR04110303] The serialization of the DataObject is the same as if the Type for the 1951DataObject had no inheritance at all, that is as if all the properties in Type.getProperties() were declared 1952within the type. The documents will resemble those where single inheritance is used, but will not validate 1953with an XSD because no XSD definition is possible. This convention applies when serializing an element 1954representing a DataObject where the DataObject's Type has more than one Base Type: 1955xsi:type is included in the serialization of the DataObject whenever the Type is not the same as the type 1956of the element. 1957The serialization of the DataObject is the same as if the Type for the DataObject had no inheritance at all, 1958that is as if all the properties in Type.getProperties() were declared within the type. 19594.11.4 Creating DataObjects from XML 1960Using XMLHelper it is easy to convert between XML and DataObjects. The following example shows how 1961to get a DataObject from XML, assuming that the purchaseOrder global element has been defined in the 1962IPO namespace: 1963 1964 String poXML = 1965 " 19854.11.5 Creating DataObjects from XML documents 1986It is possible to convert to and from XML documents to build DataObject trees, which is useful when 1987assembling DataObjects from several data sources. For example, suppose the global elements for shipTo 1988and billTo were declared in the PurchaseOrder XSD: 1989 163SDO Core Specification Version 3.0 16 December 2008 164Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 55 of 141 1990 1995 1996To create the shipTo DataObject from XML: 1997 1998 String shipToXML = 1999 " 2010 2011To convert the billTo DataObject to XML: 2012 2013 XMLHelper xmlHelper = SDO.getDefaultHelperContext().getXMLHelper(); 2014 String billToXML = 2015 xmlHelper.save(billTo, ”http://www.example.com/IPO”, "billTo"); 2016 System.out.println(billToXML); 2017 2018This produces: 2019 2020 2021 2027 2028Only properties that are isSet are included in the XML serialization of a DataObject. Absence of an 2029element or attribute indicates that the corresponding property is not set. For example, if we unset the 2030name property before serializing the billTo DataObject: 2031 2032 billTo.unset("name"); 2033 XMLHelper xmlHelper = SDO.getDefaultHelperContext().getXMLHelper(); 2034 String billToXML = xmlHelper. save(billTo, "http://www.example.com/IPO"null, 2035 "billTo"); 2036 System.out.println(billToXML); 2037 2038This now produces: 2039 166SDO Core Specification Version 3.0 16 December 2008 167Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 56 of 141 2040 2041 20464.11.6 Creating XML without an XSD 2047XMLHelper can be used without an XSD. In the TypeHelper Customer example, a Customer Type was 2048defined dynamically without an XSD, and without calling TypeHelper.defineOpenContentProperty to 2049define a global element with type Customer. Assuming customer1 is an instance of type Customer, we 2050can save customer1 to XML as follows: 2051 2052 xmlHelper.save( 2053 customer1, "http://www.example.com/customer", "customer", stream); 2054 2055This produces the following XML: 2056 2057 2058 2061 2062The presence of “xsi:type” in the generated XML is required, since no global element exists through which 2063the type of the root object can be derived. 20644.11.7 XMLHelper Methods 2065load(String inputString) creates and returns an XMLDocument from the input string. This method does not 2066perform XSD validation by default. 2067save(XMLDocument xmlDocument) serializes an XMLDocument as an XML document into a string. If the 2068DataObject's Type was defined by an XSD, the serialization will follows the XSD. Otherwise, the 2069serialization will follows the format as if an XSD were generated as defined by the SDO specification. 2070save(DataObject dataObject, String rootElementURI, String rootElementName) returns the DataObject 2071saved as an XML document with the specified root element. 2072createDocument(DataObject dataObject, String rootElementURI, String rootElementName) creates an 2073XMLDocument with the specified XML rootElement for the DataObject. 20744.11.8 Orphan Serialization 2075If a data graph includes noncontainment references to DataObjects which are not also reachable via 2076some containment reference (i.e., if the graph is not closed) Serializing serializing an SDO data graph 2077using the XMLHelper.save() method may resultMAY throw an exception in an error in the event that the 2078graph includes noncontainment references to DataObjects which are not also reachable via some 2079containment reference (i.e., the graph is not closed). For some applications, however, it is burdensome 2080and unnatural to impose a containment structure on the data. To allow such applications to serialize to 2081XML while avoiding such serialization errors, it is possible to annotate one or more elements in the XML 2082schema may be annotated with the sdox:orphanHolder attribute. OrphanHolder elements are used to 2083serialize orphan objects, instead of generating an error”closing” the XML representation of the graph 2084without imposing a containment structure. 169SDO Core Specification Version 3.0 16 December 2008 170Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 57 of 141 2085The serialization of an object having an OrphanHolder property includes the transitive closure of all 2086DataObjects reachable from the object, whether or not the referenced DataObject are contained, directly 2087or indirectly, by the DataObject. DataObjects that are referenced by the DataObject with the orphanHolder 2088property, or any DataObject contained, directly or indirectly by this DataObject but not contained 2089areMUST BE serialized in theas contents of the orphan holder (subject to any restrictions on the types of 2090orphans in the orphanHolder, see below). [COR04110801] Each “orphan” element MUST serialized as 2091part of the containment tree in which it is located, that is, only DataObjects with getContainer()==null can 2092be rendered as top-level orphans. [COR04110802] An SDO implementation MUST treat any DataObject 2093that is referenced from an orphaned DataObject (or from any node in the orphaned object’s containment 2094graph) but that is not otherwise included in the XML serialization as an orphan, and assign it to some 2095orphanHolder property within the XML document, if any appropriate orphanHolder is exists. 2096[COR04110803] Each “orphan” element is serialized as part of the containment tree in which it is located, 2097and any DataObjects referenced but not contained in this tree must also be included as orphans, so that 2098the transitive closure is obtained. References to orphaned DataObjects follow the normal rules of XML 2099serialization 2100For example: 2101 2102 2108 2109When serializing an instance of “MyRootType”, allny orphan objects encountered during the save() 2110operation will arebe serialized under the “myOrphans” element. 2111The type of an orphan holder element is typically (but not always) xsd:anyType, allowing it to contain allny 2112orphans encountered during the save() operation. If multiple orphan holders appear in a type, or among 2113several types encountered in the data graph being serialized (for example, one orphan holder could be 2114defined per potential orphan Type), the algorithm for chosing which is used for a particular orphan object 2115is implementation dependent. For example, an implementation might MAY pick the best match for each 2116orphan or it mayMAY just use the first compatible one. 2117Note that the predefined SDO type {http://docs.oasis-open.org/ns/opencsa/sdo/200812}DataGraphType 2118includes an orphan holder property allowing users of DataGraphs to avoid graph not closed errors without 2119needing to explicitly define their own orphan holders. 21204.11.9 XMLHelper Interface 2121 21224.12 XMLDocument 2123An XMLDocument represents an XML Document containing a graph of DataObjects. 2124XMLHelper creates and serializes XMLDocument objects. An XMLDocument enables a program to 2125access parts of an XML Document. 2126XMLDocuments do not change the state of any input DataObjects and ignore any containers. 172SDO Core Specification Version 3.0 16 December 2008 173Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 58 of 141 21274.12.1 Example XMLDocument 2128Using this XML Schema fragment: 2129 2130 2134 2135and the following example XMLDocument fragment: 2136 2137 2138 2140 2141After loading this XMLDocument: 2142 DataObject is an instance of Type PurchaseOrderType. 2143 RootElementURI is “http://www.example.com/IPO”. 2144 RootElementName is purchaseOrder. 2145 The XML encoding default of "UTF-8" is applied to the creation of new documents. After a load() 2146 it will have an encoding value from the document, or null, if no encoding value was found in the 2147 document. 2148 XMLDeclaration is true because the document contained an XML declaration. 2149 XMLVersion is 1.0. 2150 SchemaLocation and noNamespaceSchemaLocation are null because they are not specified in 2151 the document. 21524.12.2 XMLDocument Methods 2153getRootObject() returns the root DataObject for the XMLDocument. 2154getRootElementURI() returns the targetNamespace URI for the root element. If there is no 2155targetNamespace URI, returns null. 2156getRootElementName() returns the name of the root element. 2157getEncoding() returns the encoding of the document, or null if not specified. Support of values other than 2158“UTF-8” is implementation-dependent. 2159setEncoding(String encoding) sets the XML encoding of the document, or null if the encoding is not 2160specified. 2161isXMLDeclaration() returns true if the document contains an XML declaration. The default value is true to 2162enable new documents to contain the declaration. 2163setXMLDeclaration(boolean xmlDeclaration) sets the XML declaration version of the document. 2164getXMLVersion() returns the XML version of the document, or null if not specified. The default value is 2165"1.0". Specification of other values is implementation-dependent. 2166setXMLVersion(String xmlVersion) sets the XML version of the document, or null if not specified. 2167getSchemaLocation() returns the value of the schemaLocation declaration for the 2168http://www.w3.org/2001/XMLSchema-instance namespace in the root element, or null if not present. 2169setSchemaLocation(String schemaLocation) sets the value of the schemaLocation declaration. 175SDO Core Specification Version 3.0 16 December 2008 176Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 59 of 141 2170getNoNamespaceSchemaLocation() returns the value of the noNamespaceSchemaLocation declaration 2171for the http://www.w3.org/2001/XMLSchema-instance namespace in the root element, or null if not 2172present. 2173setNoNamespaceSchemaLocation(String schemaLocation) sets the value of the 2174noNamespaceSchemaLocation declaration. 2175 2176The root element is a global element of the XML Schema that has a type compatible with the DataObject. 21774.12.3 XMLDocument Interface 2178 21794.13 XSDHelper 2180An XSDHelper provides additional information when a Type or Property is defined by an XML Schema 2181(XSD). Also, an XSDHelper can define Types from XSDs. 2182If SDO Types and Properties were not originally defined by an XSD, or if the original XSD declaration 2183information is not available, the helper methods will return information corresponding to what would be 2184generated in an XSD generated from the Types and Properties. IsXSD() can be used to tell if the 2185information that XSDHelper has, originally comes from a Schema or not. 2186The original name and namespace from an XML Schema can be found using the getLocalName() and 2187getNamespaceURI() methods. The original name returned by getLocalName() is the XML name before 2188sdo:name is applied. 2189It is possible to tell if a Property is serialized as an XML element or attribute with the isElement() and 2190isAttribute() methods. 2191XML Schema global elements and attributes can be found using the getGlobalProperty() method. This is 2192the most common way to build XML documents with open content, by finding a global property with the 2193XSDHelper and then setting the property on an open content DataObject. 2194The getAppinfo() methods return the XSD Appinfo may be returned for a DataObject through the 2195getAppinfo() methods. Appinfo is commonly used to specify information specific to a service in an XSD 2196that may be valuable for configuring that service. The getAppinfo() methods return the XML, starting from 2197the specified source element. 2198When defining SDO medatada from a particular Schema, it can happen that some of the components 2199defined by that Schema (directly or via XSD imports or includes) map to SDO Types and Properties with 2200the same name and namespace URI as existing Types and/or Properties. If an implementation can 2201determine that the XSD components that the existing Types/Properties have been mapped from and the 2202new components have the same identity, then the existing SDO Types/Properties are used instead of 2203defining new ones. 22044.13.1 Default XSDHelper 2205The default XSDHelper is available from getXSDHelper() of the default HelperContext (see 4.6: 2206HelperContext). 178SDO Core Specification Version 3.0 16 December 2008 179Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 60 of 141 22074.13.2 Generating XSDs 2208The XSDHelper can generate a new XSD for Types that do not already have an XSD definition. This is 2209useful when the source of the Types come from services in another domain, such as relational databases, 2210programming languages and UML. The generated XSD format is described later in 8: Generation of XSD 2211from SDO Type and Property. 2212If an XML Schema was originally used to define the Types, that original XSD should be used instead of 2213generating a new XSD. If a new XML Schema is generated when one already exists, the generated 2214schema and the original schema will not be compatible and will validate different documents. The 2215XMLHelper will follow the original XSD if one exists, otherwise it will follow a generated XSD. 22164.13.3 XSDHelper Methods 2217The XSDHelper has methods to: 2218 Return the original XML local name for Types and Properties 2219 Return the namespace uri for Types and Properties 2220 Identify if a Property is represented as an XML element or attribute 2221 Identify if a Type allows XML mixed content 2222 Determine if a Type is defined from an XSD 2223 Access Properties of a Type based on XML representation characteristics 2224 Access instance Properties of a DataObject based on XML representation characteristics 2225 Return Properties for global elements and attributes 2226 Return the appinfo for Types and Properties 2227 Define new Types and Properties from XML Schemas 2228 Generate XML Schemas from Types and Properties 22294.13.4 XSDHelper Interface 2230 22314.14 DataHelper 2232The DataHelper provides helper methods for working with DataObjects, and values used with 2233DataObjects. 181SDO Core Specification Version 3.0 16 December 2008 182Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 61 of 141 2234Methods are available for converting values between data types. 22354.14.1 Default DataHelper 2236The default DataHelper is available from getDataHelper() of the default HelperContext (see 4.6: 2237HelperContext). 22384.14.2 DataHelper Interface 2239The conversion methods provided by DataHelper are language specific. Coversions between language 2240specific time and data formats and SDO time and date related types are typically provided. 2241 2242 22434.14.3 The Project method 2244The DataHelper.project() method is used to move data between contexts. The behavior of this method is 2245as follows. 2246Consider object O1, where O1.getType() is T1 and where T1.getHelperContext() is C1. Consider a 2247context C2 that defines a Type, T2, that is compatible with T1 according to the definition in section 4.4.4: 2248Compatibility Between Types, and P1 and P2 be corresponding properties defined in T1 and T2, 2249respectively. . The method 2250 DataObject O2 = C2.getDataHelper().project(O1); 2251MUST returns a DataObject O2 such that [COR04140301] 2252 1. O2.getType() is T2 2253 2. If P1.getType().isDataType() is true then O1.get(P1)==O2.get(P2) 2254 3. If P1.getType().isDataType() is false, then if O1.get(P1) is null, O2.get(P2) is null, otherwise 2255 O2.get(P2)==C2.project(O1.get(P1)) 2256If O1 and O2 are both sequenced, then the order of the elements in the sequences MUSTwill match. 2257[COR04140302] 2258If C2 does not define a type that is compatible to T1 according to the definition in section 4.4.4: 2259Compatibility Between Types, the project operation MUST MAY throw an exception. 2260The project operation leaves the DataObject O1, and all objects in the transitive closure reachable from 2261O1 in an undefined state. O1 may be returned to a defined state by rReversing the project operation, 2262i.e., 2263 C1.getDataHelper().project(O2); 2264returns O1 to a defined state. 184SDO Core Specification Version 3.0 16 December 2008 185Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 62 of 141 2265Notice that each DataObject has a single representation in each context. That is, 2266 DataObject O2 = C2.getDataHelper().project(O1); 2267 DataObject O3 = C2.getDataHelper().project(O1); 2268 assertSame(O2, O3); 2269 DataObject O4 = C1.getDataHelper().project(O2); 2270 assertSame(O1, O4); 2271It is possible that a valid data graph cannot be projected into another context, because it violates the 2272restrictions implied by the target context’s metamodel.The project method must assure that the object 2273returned from a projection is valid according to the rules defined in the context where the object’s type is 2274defined. SuchThis includes restrictions include those implieds derived from by the type’s containment 2275structure, e.g., there can be no objects in the containment graph reachable from the projected object that 2276have more than one container. For instance, consider an object OP1, with Type T1, in context C1. 2277Assume that it has 2 properties, “a” and “b”, neither of which are marked as being a containment 2278property. Then it could be legal to set the value of these properties to the same object, N1. Now 2279consider a second type, T2, in context C2, that is compatible with T1 but in which the properties “a” and 2280“b” are both marked as being containment properties. Then the DataObject OP1 cannot be projected into 2281the context C2, because the object N1 would project to an object that has conflicting containment 2282properties. Implementations MAY throw exceptions if such a projection is attempted. 2283Similarly, an implementation must check than any bi-directional properties have consistent values. Of 2284course, this is automatic if the properties are bi-directional in both HelperContexts. In the case where the 2285original object does not have a bi-directional property, an implementation must check the consistency of 2286both sides of the property. 2287If the project operation would result in a data graph that violates the restrictions imposed by the type 2288definitions in that context, the project method MUST throw an exception. 22894.14.4 Keys and Projection 2290A type and its keyType are compatible with each other. In other words, a type defined in one context as 2291having a property whose type has a key type is compatible with a type in another context in which the 2292corresponding property’s type is the key type. Since the types are compatible, it is possible to project 2293objects from one context to another, thus the value of a property can in one context be a DataObject but 2294in another could be a simple value. For example, the metamodel 2295 HelperContext #1 2296 2297 Type Employee 2298 * property - id (Integer) - KEY 2299 * property - name (String) 2300 * property - direct-report (List of Employee) 2301is compatible with the metamodel 2302 HelperContext #2 2303 2304 Type Employee 2305 * property - id (Integer) - KEY 2306 * property - name (String) 2307 * property - direct-report (List of Integer) 187SDO Core Specification Version 3.0 16 December 2008 188Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 63 of 141 2309Here the type of the direct-report property has been replaced in the second HelperContext with the 2310corresponding key type. 2311Conceptually, keys represent references to entities that lie outside the data graph (and whose types are 2312potentially not even defined in the context through which the data graph was created). Changing the 2313value of a key changes the target of the reference, and impacts neither the referenced DataObject itself 2314nor any other references to that object. This is compatible with behavior when primitives or immutable 2315data values (such as Integers or Strings) are used as key types. Achieving consistent behavior when the 2316key type extends DataObject (as required whenever compound keys are used) requires that, when 2317projecting from a context with entities to a context with complex keys, a new DataObject must MUST be 2318created for every reference. [COR04140401] The DataObjects representing the keys are never shared, 2319no matter how often any single DataObject is referenced in the original model. When projecting from an 2320DataObject to a key, a new instance of the key is always created. By contrast, when projecting between 2321contexts that do not map entities to keys, the resulting data graph has the same number of objects in the 2322target HelperContext as in the source HelperContext. 2323Conversely, when projecting from a key to a DataObject, then all usages of a the same key value must 2324MUST resolve to the same DataObject.[COR04140402] It will be necessary for tThe projection operation 2325toMUST create a single DataObject for each key value.[COR04140403] The created DataObject must 2326MUST have all default values, except for its key properties, which MUSTmust be set to match the key. 2327[COR04140404] 2328Projection between DataObjects and keys is useful when the relationships through which the entities tie 2329into the graph are non-containment. The following example shows how a complex model that lacks 2330containment relationships can be projected onto a context that requires a specific XML serialization. The 2331project operation implicitly prunes the orignal graph to the requirements of a specific client. 2332 HelperContext #1 2333 2334 Type School 2335 * property - name (String) - KEY 2336 * property - students (Student) - many=true 2337 * property - courses (Course) - many=true 2338 Type Student 2339 * property - name (String) - KEY 2340 * property - courses (Course) - many=true, containment=false, 2341 opposite=students 2342 * property - school (School) - containment=false, opposite=students 2343 Type Course 2344 * property - name (String) - KEY 2345 * property - students (Students) - many=true, containment=false, 2346 opposite=courses 2347 * property - school (School) - containment=false, opposite=courses 2348Notice the m:n relationship between Student and Course. It is possible that this data model should 2349provide data to variety of clients, each organizing the data slightly differently, some wishing to obtain the 2350list of students participating in a particular course, others wishing to obtain the list of courses in which a 2351particular student is enrolled. The application cannot determine based on the structure of the data which 2352of the two possible containment structures is "correct". Notice also that returning the transitive closure 2353would return all the data associated with the entire school. 2354In this example the client wants the data structured according to the following XSD 190SDO Core Specification Version 3.0 16 December 2008 191Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 64 of 141 2355 2356 2375Notice that projection imposes a containment structure on the original context, as well as pruning it by 2376replacing the “course” DataObjects by the corresponding key. The following code illustrates the behavior 2377of the project method. 2378 DataObject cal = _helperContext.getDataFactory().create(School.class); 2379 // Create the SDO graph 2380 cal.set("name","Berkeley"); 2381 DataObject billy = cal.createDataObject("students"); 2382 billy.set("name", "Billy Bear"); 2383 DataObject bob = cal.createDataObject("students"); 2384 bob.set("name", "Bobbie Bear"); 2385 DataObject basketWeaving = cal.createDataObject("courses"); 2386 basketWeaving.set("name", "Basket Weaving"); 2387 DataObject algol = cal.createDataObject("courses"); 2388 algol.set("name", "Algol"); 2389 DataObject revolution = cal.createDataObject("courses"); 2390 revolution.set("name", "Revolution"); 2391 // hook things up 2392 billy.getList("courses").add(basketWeaving); 2393 billy.getList("courses").add(algol); 2394 bob.getList("courses").add(basketWeaving); 2395 bob.getList("courses").add(revolution); 2396 // Create a second context defined by an XSD 2397 2398 HelperContext hc2 = SDO.getHelperContextFactory().createHelperContext(); 2399 hc2.getXSDHelper().define(getClass().getClassLoader().getResourceAsStream( 193SDO Core Specification Version 3.0 16 December 2008 194Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 65 of 141 2400 "projection.xsd"), null); 2401 // Project from the java context to the XSD context 2402 DataObject projection = hc2.getDataFactory().project(cal); 2403 // Produce XML based on the XSD 2404 String xml = hc2.getXMLHelper().save(projection, "http://projection", "school"); 2405 // I'm imagining here that sending the XML out over the wire (eg, using it as 2406 a response to a 2407 // WebService request. On the client side, we go from the XML back to SDO. We 2408 use the context 2409 // based on the XSD. 2410 DataObject projection2 = hc2.getXMLHelper().load(xml).getRootObject(); 2411 // We can make some changes. We can add a new course... 2412 projection2.getList("students.0/courses").add("Fortran and You"); 2413 // So, now the trip back to the server… 2414 //I'm skipping the XML step, and simply projecting the modified (XML oriented) 2415 data back into 2416 // my java context 2417 DataObject cal2 = _helperContext.getDataFactory().project(projection2); 2418 2419 // Test that there is one entity per key value 2420 DataObject billy2 = (DataObject)cal2.getList("students").get(0); 2421 DataObject basketWeavingBill = (DataObject)billy2.getList("courses") 2422 .get(0); 2423 DataObject bob2 = (DataObject)cal2.getList("students").get(1); 2424 DataObject basketWeavingBob = (DataObject)bob2.getList("courses").get(0); 2425 assertSame(basketWeaving2, basketWeavingBob); 24264.14.5 ChangeSummary and Projection 2427Projection provides for the transmission of data between distinct but compatible (see section 4.4.4) 2428HelperContexts. In the case that a service providing the persistence mechanism has a different but 2429compatible type system from the client performing the changes, the contents of ChangeSummaries may 2430also be projected. This functionality is subject to the constraint that the list returned from 2431ChangeSummary.getChangedObjects() contains only DataObjects that are within the scope of the 2432ChangeSummary into which they are being projected. Behavior is undefined if a changed DataObject is 2433not in scope of the ChangeSummary according to the containment structure and OrphanHolder properties 2434of the target HelperContext. The restriction that the contents of the ChangeSummary matches the scope 2435as defined by the containment structure and OrphanHolders of the target HelperContext assures that all 2436SDO functionality (e.g., XML serialization, deep copies using CopyHelper) continue to work as expected 2437in the target projection. 2438The logging state of an active, non-empty ChangeSummary is changed during the project operation. 2439When a DataObject having a ChangeSummary property is projected into another context, and 2440ChangeSummary.beginLogging() has been called on the ChangeSummary object without a 2441corresponding call to ChangeSummary.endLogging(), an SDO implementation MUST perform an implicit 2442call to ChangeSummary.endLogging() before executing the projection. [COR04140501] If the 2443ChangeSummary is empty (that is, no changes have yet been logged), then the implementation MUST 2444make an implicit call to ChangeSummary.beginLogging() in the target context. This supports the case 2445where the persistence service initializes change tracking before passing the projected result to its client. 2446If the ChangeSummary is not empty (that is, ChangeSummary.getChangedObjects() returns a non-empty 2447list), then ChangeSummary.isLogging() on the projected ChangeSummary object MUST return false. 2448[COR04140502] 2449The ChangeSummary, and its properties, follow the normal rules associated with the projection of 2450DataObjects and property values. The list returned by ChangeSummary.getChangedObjects() MUST 2451contain the same underlying business objects, regardless of whether the ChangeSummary is being 2452inspected in the projection in which beginLogging was called or in the target projection. [COR04140503] 2453The elements in the list MUST be consistent with (i.e., projected into) the context of the DataObject from 2454which the ChangeSummary was retrieved. [COR04140504] The behavior of 2455ChangeSummary.getOldContainer() is currently undefined and will be resolved in a later draft of SDO 3. 196SDO Core Specification Version 3.0 16 December 2008 197Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 66 of 141 2456It is illegal to call ChangeSummary.undoChanges() after projecting the ChangeSummary. The behavior 2457will be implementation dependent. 2458The following example, based on the metadata from the previous section’s example, illustrates this 2459behavior. 2460 2461 // Create an envelope DataObject containing a change summary. 2462 DataObject dataGraph = 2463 _helperContext.getDataFactory().create(SDO_URI,"DataGraphType"); 2464 2465 // Create the SDO graph root node 2466 DataObject cal = _helperContext.getDataFactory().create(School.class); 2467 2468 // Add it to the graph 2469 dataGraph.add("school",cal); 2470 2471 // Fill the data graph 2472 cal.set("name","Berkeley"); 2473 DataObject billy = cal.createDataObject("students"); 2474 billy.set("name", "Billy Bear"); 2475 DataObject bob = cal.createDataObject("students"); 2476 bob.set("name", "Bobbie Bear"); 2477 DataObject basketWeaving = cal.createDataObject("courses"); 2478 basketWeaving.set("name", "Basket Weaving"); 2479 DataObject algol = cal.createDataObject("courses"); 2480 algol.set("name", "Algol"); 2481 DataObject revolution = cal.createDataObject("courses"); 2482 revolution.set("name", "Revolution"); 2483 2484 // hook things up 2485 billy.getList("courses").add(basketWeaving); 2486 billy.getList("courses").add(algol); 2487 bob.getList("courses").add(basketWeaving); 2488 bob.getList("courses").add(revolution); 2489 2490 // Create a second context defined by an XSD 2491 HelperContext hc2 = SDO.getHelperContextFactory().createHelperContext(); 2492 hc2.getXSDHelper().define(getClass().getClassLoader().getResourceAsStream("samp 2493 le/projection.xsd"), null); 2494 199SDO Core Specification Version 3.0 16 December 2008 200Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 67 of 141 2495 // Project from the java context to the XSD context 2496 DataObject projection = hc2.getDataHelper().project( dataGraph ); 2497 2498 // Turn on change logging in the projected DataObject 2499 projection.getChangeSummary().beginLogging(); 2500 DataObject projectedSchool = projection.getDataObject("school"); 2501 2502 // Make a few changes in the logging context 2503 projectedSchool.set("name","Stanford"); 2504 DataObject billy2 = (DataObject)projectedSchool .getList("students").get(0); 2505 billy2.set("name","Chauncy Cardinal"); 2506 2507 // Make the original context active by projecting back to it 2508 cal = _helperContext.getDataHelper().project(projection); 2509 2510 // Inspect the change summary 2511 ChangeSummary changeSummary = cal.getChangeSummary(); 2512 2513 // projection is an implicit call to endLogging() 2514 assertFalse(changeSummary.isLogging()); 2515 assert.equals(2, changeSummary.getChangedObjects().size()); 2516 assert.true(changeSummary.getChangedObjects().contains(cal)); 2517 assert.true(changeSummary.getChangedObjects().contains(billy)); 25184.15 SDO 2519The SDO class provides access to HelperContext and HelperContextFactory objects. 25204.15.1 Default HelperContext 2521The SDO class is the means by which the default HelperContext is found: 202SDO Core Specification Version 3.0 16 December 2008 203Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 68 of 141 25224.15.2 HelperContext by Identifier 2523HelperContext objects are created with a unique identifier. The SDO class can be used to retrieve the 2524HelperContext based on the identifier. A null or empty string (“”) identifier corresponds to the default 2525HelperContext. Null is returned if a HelperContext cannot be found for the specified identifier. 2526 2527 HelperContext hrHelperContext = SDO.getHelperContext(“org.example.hr”); 25284.15.3 Default HelperContextFactory 2529To create instances of HelperContext other than the default one, a HelperContextFactory is used. The 2530HelperContextFactory can be accessed from the SDO class. 2531 2532 HelperContextFactory hcf = SDO.getHelperContextFactory(); 2533 HelperContext hc = hcf.createHelperContext(“org.example.hr”, null); 2534 25354.15.4 Implementation Specific HelperContextFactory 2536In order to ensure that a HelperContext factory from a particular vendor is used, a fully qualified class 2537namean implementation language dependent identifier can be specified. 2538 2539 HelperContextFactory hcf = 2540 SDO.getHelperContextFactory(“org.example.vendor.HCFImpl”); 25414.15.5 SDO Class 2542 25434.16 HelperContextFactory 2544HelperContextFactory is used to create instances of HelperContext. 25454.16.1 Creating a HelperContext 2546It is possible to supply a unique identifier when creating a When HelperContext objects a unique identifier 2547may be supplied. 2548 2549 HelperContextFactory hcf = SDO.getHelperContextFactory(); 2550 HelperContext hc = hcf.createHelperContext(“org.example.hr”, null); 2551 2552If a unique identifier was supplied when the HelperContext was created, it can is possible to use the 2553identifier to be looked up the associated HelperContext, using the SDO class: 2554 205SDO Core Specification Version 3.0 16 December 2008 206Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 69 of 141 2555 HelperContext hc = SDO.getHelperContext(“org.example.hr”); 2556 2557It is an error condition if an attempt is made to create a HelperContext with an existing identifier. 25584.16.2 HelperContextFactory Interface 2559 208SDO Core Specification Version 3.0 16 December 2008 209Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 70 of 141 25605 SDO Model for Types and Properties 2561SDO defines a simple metamodel for describing types. DataObjects make their metamodel available through the 2562Type interface, that is, through DataObject.getType(). Figure 3 shows this metamodel as a UML diagram. This SDO 2563model describes SDO Types and Properties. 2564 2565It contains the same information as is in the SDO commonj.sdo.Type and commonj.sdo.Property 2566interfaces shown in a model form, as a UML class diagram and as an XML Schema sdo-3.0.xsd. 2567 2568 2569Figure 2 2570SDO’s metamodel is extensible. This means that Each of the Properties in the SDO model correspond to 2571accessors on the Type and Property interfaces, as shown below in the tables. The model of Types and 2572Properties is defined by the file sdoModel.xml. 2573Type and Property can have open content so that additional new properties can be added to the 2574metamodel. One usecase for this is to represent metadata that is specific to a particular data 2575source.used even if they are not declared on the Type and Property interface. For example, Ssome 2576predefined global properties (specific to XML serialization) are defined inin http://docs.oasis- 2577open.org/ns/opencsa/sdo/xml/200812 can be set using the open content on Type and Property, as shown 211SDO Core Specification Version 3.0 16 December 2008 212Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 71 of 141 2578in the “applies to” column in the tables belowsection 8.2: Tuning the Default Mapping using Open Content 2579Properties. 2580SDO allows application programs to define types. In this case, the objects in the metamodel are created 2581DataObjects and then passed to the TypeHelper.define API. The DataObjects in such a metamodel are 2582themselves normal DataObjects, which means that they themselves have Types, and these Types have 2583properties, etc. . 25845.1 API for DataObjects Representing Type and Properties 2585The objects passed to the TypeHelper.define API are restricted to DataObjects with type 2586{http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812}Type. Type has Properties: name, uri, dataType, 2587open, sequenced, abstract, baseType, property, keyType, and aliasName. Every TypeHelper MUST 2588define {http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812}Type and {http://docs.oasis- 2589open.org/ns/opencsa/sdo/xml/200812}Property according to [COR05010001] 214SDO Core Specification Version 3.0 16 December 2008 215Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 72 of 141 SDO Model Types Type name="Type" open=true uri="http://docs.oasis-open.org/ns/opencsa/sdo/200812" Property name="baseType" many=true type="Type" Property name="property" containment=true many=true type=”Property” Property name="aliasName" many=true type="String" Property name="name" type="String" Property name="uri" type="String" Property name="dataType" type="Boolean" Property name="open" type="Boolean" Property name="sequenced" type="Boolean" Property name="abstract" type="Boolean" Property name="keyType" type="Type" Property name="Property" open=true uri="http://docs.oasis-open.org/ns/opencsa/sdo/200812" Property name="aliasName" many=true type="String" Property name="name" type="String" Property name="many" type="Boolean" Property name="containment" type="Boolean" Property name="type" type="Type" Property name="default" type="Object" Property name="readOnly" type="Boolean" Property name="opposite" type="Property" Property name="nullable" type="Boolean" Property name=”openContent” type=”Boolean” Property name=”key” type=”Boolean” 2590Note that the order of the properties is significant, and implies the index of each property. For instance, 2591the value of the “baseType” property can be retrieved using DataObject.get(0) and the value of the 2592keyType property can be retrieved using DataObject.get(9). 2593As described in 4.8.2: “Defining SDO Types Dynamically”, wherever Types are expected, e.g., as the 2594value of Property.type or of Type.baseType, either a DataObject of type {http://docs.oasis- 2595open.org/ns/opencsa/sdo/xml/200812}Type or a Type object retrieved from the TypeHelper can be used. 2596Once the type has been defined, an SDO implementation MUST make the values used in the defining 2597DataObject available through the the accessor methods in the Type API. [COR05010002] The mapping 2598between the properties and accessor methods is 217SDO Core Specification Version 3.0 16 December 2008 218Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 73 of 141 2599 2600 Property in {http://docs.oasis- commonj.sdo.Type open.org/ns/opencsa/sdo/xml/200812}TypeType model accessor name getName() uri getURI() dataType isDataType() open isOpen() sequenced isSequenced() abstract isAbstract() baseType getBaseTypes() property getDeclaredProperties() keyType getKeyType() aliasName getAliasNames() 2601 Property in {http://docs.oasis- Commonj.sdo.Property open.org/ns/opencsa/sdo/xml/200812}Property accessor name getName() many isMany() containment isContainment() default getDefault() readOnly isReadOnly() type getType() opposite getOpposite() nullable isNullable() openContent isOpenContent() key isKey() aliasName getAliasNames() 2602 2603Additionally, an SDO implementation MUST expose any open content properties set on the DataObject 2604used to define a Type or Propertiy through the getInstanceProperties() and get() methods on the 2605corresponding commonj.sdo.Type and commonj.sdo.Property objects. [COR05010003] 220SDO Core Specification Version 3.0 16 December 2008 221Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 74 of 141 26065.2 SDO Type and Property constraints 2607Compliance is based on an implementation’s ability to create types based on reasonable and consistent 2608type definitions. The definition of objects in the metamodel needs to be consistent with type and property 2609semantics, otherwise the behavior of the SDO implementation is undefined. 2610 Property.containment=true implies type.dataType=false. 2611 Property.default values have to be consistent with property.type, and can only be given if 2612 property.type.dataType=true and property.many=false 2613 Type.dataType=true implies type.properties is empty, type.open=false and type.sequenced=false. 2614 Type.dataType and sequenced have the same value as their base Types' dataType and 2615 sequenced. 2616 Type.open=false implies the type.baseType.open=false. 2617 Properties that are bidirectional have type.dataType=false 2618 Properties that are bidirectional have no more than one end that is containment=true 2619 Properties that are bidirectional have the same value at both ends for readOnly 2620 Properties that are bidirectional where one side has containment=true implies that the other side 2621 has many=false. 2622 Names and aliasNames are unique within Type.getProperties() 26235.3 XML Representation of SDO Type and Property 26245.4 The file SdoModel.xsd defines an XML document structure 2625 corresponding to SDO’s type and property metamodel.Property 2626 Properties 2627Property has Properties: name, many, containment, default, readOnly, type, opposite, nullable, 2628openContent, key and aliasName. 2629 223SDO Core Specification Version 3.0 16 December 2008 224Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 75 of 141 26306 Standard SDO Types 2631These are the predefined SDO Types described in this chapter that are alwaysMUST be available from 2632TypeHelper.getType(TypeHelper.SDO_URI, String typeName). [COR06000001] 26336.1 SDO Data Types 2634The term SDO data type refers to an SDO Type where isDataType() = true. None of the types have any 2635Properties unless noted. All values are false unless noted. 2636DataObject methods of the form get 226SDO Core Specification Version 3.0 16 December 2008 227Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 76 of 141 SDO Type Precision String Representation URI = http://docs.oasis- open.org/ns/opencsa /sdo/200812 Boolean 1 bit 'true' | 'false' | ‘1’ | ‘0’ Byte 8 bits ('+'|'-')? [0-9]+ signed Bytes [0-9A-F]+ Character any character Date '-'?yyyy'-'mm'-'dd'T'hh':'mm':'ss('.'s+)? 'Z'? DateTime '-'?yyyy'-'mm'-'dd'T'hh':'mm':'ss('.'s+)? zz? Day '---'dd zz? Decimal ('+'|'-')? ([0-9]+ ('.'[0-9]+)?) | ('.'[0-9]+) (('E'|'e') ('+'|'-')? [0-9]+)? Duration '-'?'P'(yyyy'Y')? (mm'M')? (dd'D')? ('T'(hh'H')? (mm'M')? (ss('.'s+)?'S')? )? Double IEEE-754 Decimal | 'NaN' | '-NaN' | 'Infinity' | '-Infinity' 64 bits Float IEEE-754 Decimal | 'NaN' | '-NaN' | 'Infinity' | '-Infinity' 32 bits Int 32 bits ('+'|'-')? [0-9]+ signed Integer ('+'|'-')? [0-9]+ Long 64 bits ('+'|'-')? [0-9]+ signed Month '--'mm zz? MonthDay '--'mm'-'dd zz? Short 16 bits ('+'|'-')? [0-9]+ signed String any characters Strings any characters separated by whitespace Time hh':'mm':'ss('.'s+)? zz? URI any characters Year '-'?yyyy zz? YearMonth '-'?yyyy'-'mm zz? 229SDO Core Specification Version 3.0 16 December 2008 230Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 77 of 141 SDO Type Precision String Representation URI = http://docs.oasis- open.org/ns/opencsa /sdo/200812 YearMonthDay '-'?yyyy'-'mm'-'dd zz? 2653 2654where 2655 [0-9] any digit, [0-9A-F] any hexadecimal digit. 2656 '-' single quotes around a literal character, () for higher precedence, | for choice. 2657 ? occurs zero or one time, * occurs zero or more times, + occurs one or more times. 2658 Decimal lexical representation is valid for Double and Float. 2659 yyyy year, mm month, dd day, hh hour, mm minute, ss second, s fractional second 2660 zz time zone (('+'|'-')hh':'mm)|'Z' where hh time zone hour, mm time zone minute. 2661 Date will accepts the same lexical format as DateTime but will normalizes to the Z time zone. 2662If a value is null and a conversion to (byte, char, double, float, int, long, short) is requested by a 2663DataObject.get 26666.1.1 Conversion from SDO type Bytes to SDO type String 2667An SDO implementation MUST convert Bytes are converted to String by converting each byte into the 2668hexadecimal two-digit equivalent using the characters [0-9A-F]. [COR06010101]The 0 index of the byte 2669array becomes the 0th and 1st index of the String, with subsequent values in order to the right. Null Bytes 2670become null Strings. This representation is compatible with XML Schema hexBinary dataType canonical 2671lexical representation. An example conversion of byte[] = { 10, 100 } becomes the String "0A64". 26726.1.2 Conversion from SDO type String to SDO type Bytes 2673An SDO implementation MUST convert Strings are converted to Bytes by converting each pair of 2674characters from the hexadecimal two-digit equivalent using the characters [0-9A-Fa-f]. [COR06010201] 2675The 0th and 1st index of the String becomes the 0 index of the byte array, with subsequent values in 2676order to the right. Null Strings become null Bytes. This representation is compatible with XML Schema 2677hexBinary dataType lexical representation. An example conversion of the String "0A64" becomes byte[] = 2678{ 10, 100 }. 26796.1.3 Conversion between Character and String 2680An SDO implementation MUST convert The conversion from Character to String happens when calling 2681getString() on a property of type Character or setCharacter() on a property of type String; the conversion 2682from String to Character happens when calling getCharacter() on a property of type String or setString() 2683on a property of type Character. Aby mapping the Character value maps to a String of length 1, whose 2684first (and only) character is that Character value. [COR06010301] The character with the Unicode 2685codepoint '0' MUST maps to the empty String. [COR06010302] Strings with length > 1 can't be converted 2686to Character. Null String can't be converted to Character. 26876.2 SDO Abstract Types 2688It is not possible to instaniate tThe following types may not be instantiated. They describe metadata for 2689DataObjects, Types, and Properties. Attempts to instantiate any of these Types that may not be 2690instantiated MUST throw IllegalArgumentException from all create() methods.[COR06020001] 2691 232SDO Core Specification Version 3.0 16 December 2008 233Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 78 of 141 SDO Abstract Type XSD Type URI = http://docs.oasis- open.org/ns/opencsa/sdo/200812 ChangeSummaryType ChangeSummaryType abstract=true in the SDO namespace. dataType=true ChangeSummaries are instances. DataObject Not applicable abstract=true DataObjects are instances. DataTypeWrapper anyType, to represent values that are simpleTypes 26926.3 SDO Model Types 2693Type and Property describe themselves. The definition is: 235SDO Core Specification Version 3.0 16 December 2008 236Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 79 of 141 SDO Model Types Type name="Type" open=true uri="http://docs.oasis-open.org/ns/opencsa/sdo/200812" Property name="baseType" many=true type="Type" Property name="property" containment=true many=true type=”Property” Property name="aliasName" many=true type="String" Property name="name" type="String" Property name="uri" type="String" Property name="dataType" type="Boolean" Property name="open" type="Boolean" Property name="sequenced" type="Boolean" Property name="abstract" type="Boolean" Property name="keyType" type="Type" Property name="Property" open=true uri="http://docs.oasis-open.org/ns/opencsa/sdo/200812" Property name="aliasName" many=true type="String" Property name="name" type="String" Property name="many" type="Boolean" Property name="containment" type="Boolean" Property name="type" type="Type" Property name="default" type="Object" Property name="readOnly" type="Boolean" Property name="opposite" type="Property" Property name="nullable" type="Boolean" Property name=”openContent” type=”Boolean” Property name=”key” type=”Boolean” 26946.4 SDO Type and Property constraints 2695There are several restrictions on SDO Types and Properties. These restrictions ensure Types and 2696Properties for DataObjects are consistent with their API behavior. Behavior of ChangeSummaryType 2697Properties is defined. 2698 2699 Instances of Types with dataType=false must implement the DataObject interface. 238SDO Core Specification Version 3.0 16 December 2008 239Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 80 of 141 2700 Values of bidirectional Properties with type.dataType=false and many=true must be unique 2701 objects within the same list. 2702 Values of Properties with type.dataType=false and many=true cannot contain null. 2703 Property.containment has no effect unless type.dataType=false. 2704 Property.default!=null requires type.dataType=true and many=false 2705 Types with dataType=true cannot contain properties, and must have open=false and 2706 sequenced=false. 2707 Type.dataType and sequenced must have the same value as their base Types' dataType and 2708 sequenced. 2709 Type.open may only be false when the base Types' open are also false. 2710 An implementation is not required to modify pre-existing types when derived types are defined. 2711 Properties that are bidirectional require type.dataType=false 2712 Properties that are bidirectional require that no more than one end has containment=true 2713 Properties that are bidirectional require that both ends have the same value for readOnly 2714 Properties that are bidirectional with containment require that the non-containment Property has 2715 many=false. 2716 Names and aliasNames must all be unique within Type.getProperties() 241SDO Core Specification Version 3.0 16 December 2008 242Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 81 of 141 27177 XML Schema to SDO Mapping 2718XML Schema declarations (XSD) are mapped to SDO Types and Properties following the principles 2719outlined below. [Schema1] [Schema2] (The abbreviation XSD is used for both the XML Schema infoset 2720and the XML Schema declarations used to build the infoset.) 2721This simple yet flexible mapping allows SDO DataObjects to represent XML documents following an XSD. 2722The vast majority of XSD capabilities are mapped and several corner cases are included. XML 2723documents without XSDs are also handled. 2724Sequenced DataObjects preserve detailed information about the order of XML elements. 2725This document describes the Mapping Principles, Mapping of XSD Types, Sequenced DataObject, 2726Mapping of XSD elements and Attributes, Mapping of data types and XML document mapping. It also 2727provides Examples. 27287.1 Mapping Principles 2729Creating SDO Types and Properties from XML Schema is increasingly important as a great deal of 2730structured information is described by XSDs. The following table describe provides an overview the 2731mapping. 2732 XML Schema Concept SDO Concept Target namespace URI for Types Simple Type Type, dataType=true SDO data types Complex Type Type, dataType=false SDO DataObjects Attribute of Complex Type Property within enclosing Type Global Attribute Open content property Element of Complex Type Property within enclosing Type Global Element Open content property 2733 2734The general principles are that: 27351. A Schema target namespace describes the URI for a set of Types. 27362. SimpleType declarations describe data types, Types where isDataType() is true. 27373. ComplexType declarations describe DataObjects, Types where isDataType() is false. 27384. Within each ComplexType, the elements and attributes describe Properties in the corresponding 2739 enclosing Type. 27405. Model groups (all, choice, sequence, group reference) are expanded in place and do not describe 2741 Types or Properties. There is no SDO construct corresponding to groups. 27426. Open content maps to Type.open. Open element content also maps to Type.sequenced. 27437. Mixed content maps to Type.sequenced and uses text entries in the sequence for mixed text. 27448. Order of element content maps to Type.sequenced. 244SDO Core Specification Version 3.0 16 December 2008 245Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 82 of 141 27459. XSD any and anyAttribute (wildcard) declarations are not required to map to Types or Properties. 274610. We do not allow design changes that complicate the simple cases to solve more advanced cases. 274711. The mapping input is an annotated XSD using the SDO annotations. The mapping output is SDO 2748 Types and Properties. 274912. Normally, SDO names are the same as the XSD names. To change the SDO name user can 2750 annotate an XSD with sdox:name annotations. In some cases, for example in the case of duplicate 2751 component names or anonymous XSD types, the original XSD names cannot be used in SDO. In 2752 such cases, an SDO-aware code generator tool will generate new names and virtually add 2753 sdox:name annotations to the original XSD. Then, the tool will use the Annotated Schema to generate 2754 SDO. Such tool would must be able to serialize the Annotated Schema at user request. Note: an 2755 SDO implemention will MUST never NOT generated names for anonymous types that hide a globally 2756 defined type with the same name. [COR07010001] 275713. This mapping specifies a minimum. An SDO Iimplementations may MAY expand this mapping to 2758 perform additional functions as long as the mapping stated here works for all client code. 27597.2 Generating static SDOs from an XSD 2760These principles apply when generating static SDOs from an XSD: 2761 27621. SDO does not specify any name mangling but enables and sometimes requires name overrides 2763 through annotations. 27642. If the normal generation of source code from an XSD would result in conflicting names, the XSD 2765 declaration would need to contain annotations to override the default name. 27663. XSD allows for anonymous types to be defined within an enclosing definition. When generating a 2767 static SDO in an implementation language that supports a concept of locally scoped types (such as 2768 Java's inner classes or C++'s nested classes), then the anonymous type is scoped to the smallest 2769 available enclosing structure. For instance, in Java, the anonymous type is by default an inner class 2770 within the class that represents the containing type (see the [SDOJava] for details). To achieve global 2771 visibility or cross language consistency when generating static SDOs from an anonymous type, 2772 annotations must be usedare required to specify the name of the static SDO. 27734. Implementations may MAY provide behavior (in a product-specific fashion) equivalent to annotations 2774 to automatically solve such problems as duplicate names. This is logically equivalent to the 2775 implementation creating an Annotated Schema (AS) and then creating SDO metadata from the 2776 Annotated Schema. An implementation that provides this behavior should also provide a means to 2777 generate the AS. The generated AS should be annotated so that another implementation can define 2778 SDO Types and Properties from the generated schema without further name mangling. Having such 2779 an annotated schema ensures portability of Types and Properties (and generated code) across all 2780 implementations. 27817.3 Mapping fromof XSD to SDO Types and Properties 2782 The tables in this section and in section 7.4: Mapping of XSD Attributes and Elements to SDO 2783 Properties, define the default mapping of XSD to SDO constructs, which MUST be implemented by all 2784 SDO implementations. [COR07030001] There are a number of customizations that can be used to 2785 improve modify the constructed mapping to SDO metamodel. 2786 These customizations are expressed as attributes in the SDO namespace for XML, "http://docs.oasis- 2787 open.org/ns/opencsa/sdo/xml/200812". The following XSD attributes in the SDO XML namespace are 2788 used to modify the constructed SDO model: 27891. name - sets the SDO name to the name specified here. Applies to Type and Property. Used in 2790 ComplexType, SimpleType, element, and attribute declarations. The XSD type of the annotation is 2791 string. 247SDO Core Specification Version 3.0 16 December 2008 248Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 83 of 141 27922. propertyType - sets the Property's Type as specified by the QName value. Applies to Property. 2793 Used in element and attribute declarations where Property.type.dataType ismust be false. The XSD 2794 type be IDREF, IDREFS, anyURI or the keyType associated with the property. The XSD type controls 2795 how the non-containment relationship is rendered in XML, e.g., during XMLHelper.save(): when the 2796 specified property type has a key type, then the key is rendered, otherwise, the XPath is rendered 2797 (see the ChangeSummary XML format described in 10: ChangeSummary XML format. The XSD 2798 type of the annotation is QName. 27993. oppositeProperty - sets the Property opposite to be the property with the given name within the 2800 Type specified by propertyType. Applies to Property, making the property bidirectional. Used in 2801 element and attribute declarations where . Property.type.dataType must beis false. Requires 2802 sdox:propertyType on the property. Automatically creates the opposite property if one or both ends 2803 are specified in the XSD, with opposites bidirectional. The XSD type of the annotation is string. 28044. sequence – overrides the value of Type.sequenced. Applies to Type. Used in ComplexType 2805 declarations. A Sequenced Type has a Sequence for all XML Elements. The default is false. If 2806 schema extension is used and the value is “true”, the base complexType is required tomust also be 2807 marked sequence="true". The XSD type of the annotation is boolean. 28085. string="true" - sets the SDO Type to String for XSD SimpleTypes as a means to override the 2809 instance class when it is desired to preserve the exact values must be preserved.. Applies to 2810 Property. Used in element and attribute declarations. Same as sdox:dataType="sdo:String". The XSD 2811 type of the annotation is boolean. 28126. dataType - sets the Property's type as specified by the QName value as a means to override the 2813 declared type. Applies to XML attributes and elements with simple content. Used in element and 2814 attribute declarations. The XSD type of the annotation is QName. 28157. aliasName - add alias names to the SDO Type or Property. The format is a list of names separated 2816 by whitespace, each becoming an aliasName. Applies to Type and Property. The XSD type of the 2817 annotation is string. 28188. readOnly - indicate the value of Property.readOnly. The format is boolean with default false. Applies 2819 to Property. Used in element and attribute declarations. The XSD type of the annotation is boolean. 28209. many - sets the value of Property.isMany to the specified boolean value. Typically used on element 2821 declarations that appear inside a repeating model group declaration ( 250SDO Core Specification Version 3.0 16 December 2008 251Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 84 of 141 284414. 2845In all tables, SDO Type and Property values that are not shown default to false or null, as appropriate. 2846[URI] is the targetNamespace. Use sdo:name to override the names as desired. 28477.3.1 XML Schemas XML Schemas SDO Package Schema with targetNamespace [URI] is (non-null) type.uri for the types defined by this Schema. Schema without targetNamespace [URI] is null. Null is type.uri for the types defined by this Schema. 28487.3.2 XML Simple Types 2849XML simple types map directly to SDO types. 2850The mapping of XML Schema built-in simple types is defined in another section 7.5below. When deriving 2851Simple Types by restriction, the base Type for the SDO Type MUST BEfollows the SDO Type thap maps 2852to the XSD SimpleType restriction base. [COR07030201] 2853When the XSD type is integer, positiveInteger, negativeInteger, nonPositiveInteger, nonNegativeInteger, 2854long, or unsignedLong, and there are facets (minInclusive, maxInclusive, minExclusive, maxExclusive, 2855totalDigits or enumeration) constraining the range to be within the range of int, then implementation type 2856MUST beis int. [COR07030202].. 2857 XML Simple Types SDO Type Simple Type with name Type name=[NAME] base=[BASE] 253SDO Core Specification Version 3.0 16 December 2008 254Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 85 of 141 XML Simple Types SDO Type Simple Type with sdox:name Type name=[SDO_NAME] base=[BASE] 28587.3.3 XML Complex Types XML Complex Types SDO Type Complex Type with empty content Type name=[NAME] uri=[URI] [NAME]=given by an automated annotation utility (7.1:Mapping Principles, point 12) 256SDO Core Specification Version 3.0 16 December 2008 257Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 86 of 141 XML Complex Types SDO Type Complex Type with sdox:name Type name=[SDO_NAME] uri=[URI] or 259SDO Core Specification Version 3.0 16 December 2008 260Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 87 of 141 XML Complex Types SDO Type Complex Type with complex content Type name=[NAME] restricting a Complex Type Properties+=[BASE].properties base=[BASE] 262SDO Core Specification Version 3.0 16 December 2008 263Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 88 of 141 XML Complex Types SDO Type Complex Type extending a Type name=[NAME] SimpleType uri=[URI] Property: 28597.4 Mapping of XSD Attributes and Elements to SDO Properties 2860Each XSD element or attribute maps to an SDO property. 2861The Property.containingType is the SDO Type for the enclosing ComplexType declaration. 2862The order of Properties in Type.getDeclaredProperties() is the order of declarations as they appear in the 2863XML Schema ComplexType. When extension is used, the Properties of the base type occur first in the 2864Properties list. 2865If the local names of the elements and attributes of a complex type, including within a complexType, and 2866its base types, have the same local name are not unique, then unique names must beit is avisable to 2867assign the SDO name of the generated property usinged by sdox:name. This ensures that all property 2868names in Type.getProperties() are unique. See Chapter 9: SDO Path Expression for DataObjects for 2869using SDO path syntax to distinguish attributes and elements in cases where sdox:name cannot be 2870applied. Multiple elements with the same name and URI are combined into a single Property and the 2871Type is sequenced, as described in 7.4.2: Mapping of XSD Elements. 2872When creating a Property where the default or fixed value is defined by the XSD, the Property's default is 2873assigned based on the XSD default. If there is no default in the XSD, then the Property’s default is null. 2874Note that XSD anyType is a ComplexType and XSD anySimpleType is a SimpleType. They follow the 2875normal mapping rules. 265SDO Core Specification Version 3.0 16 December 2008 266Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 89 of 141 28767.4.1 Mapping of XSD Attributes XML Attribute SDO Property Attribute Property name=[NAME] type=[TYPE] 268SDO Core Specification Version 3.0 16 December 2008 269Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 90 of 141 XML Attribute SDO Property Attribute with sdox:string Property name=[NAME] type=String where [TYPE] = IDREF, IDREFS, the KeyType associated with P_TYPE, anyURI or restrictions of these types. Attribute with bidirectional property to a Property name=[NAME] DataObject with sdox:oppositeProperty and type=[P_TYPE] sdox:propertyType opposite=[PROPERTY] many=true (for IDREFS only) 2877 XML Global Elements and Attributes SDO Property 271SDO Core Specification Version 3.0 16 December 2008 272Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 91 of 141 Global Element Same as local element declaration except the containing Type is not specified by SDO other than the Type's URI is the XSD target namespace and that many=”true”. 28787.4.2 Mapping of XSD Elements 2879If a ComplexType has content with two elements that have the same local name and the same 2880targetNamespace, whether through declaration, extension, substitution, groups, or other means, the 2881duplication MUST BEis handled as follows [COR07040201]: 2882 The ComplexType becomes a sequenced type, as if sdox:sequence="true" was declared. 2883 A single property is used for all the elements with the same local name and the same 2884 targetNamespace. If the content model allows more than 1 instance of the element, then 2885 isMany=true. If, however, the elements are mutually exclusive (for example, they are single 2886 valued and on two sides of a xsd:choice group), then isMany=false.. 2887 If schema extension is used, the base type may need toMAY be modified with 2888 sdox:sequence="true". and Eelements with name conflicts introduced in extensions require that 2889 the property in the extended base type must MUST BEbe made many=true. [COR07040202] 2890 XML Elements SDO Property Element Property name=[NAME] 274SDO Core Specification Version 3.0 16 December 2008 275Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 92 of 141 XML Elements SDO Property Element with maxOccurs > 1 Property name=[NAME] many=true where [MAX] > 1 Element in all, choice, or sequence Property name=[NAME] type=[TYPE] <[GROUP] maxOccurs=[G_MAX]> many=true 277SDO Core Specification Version 3.0 16 December 2008 278Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 93 of 141 XML Elements SDO Property Element with substitution group Property name=[BASE_NAME] type=[BASE_TYPE] When marshalling a DataObject to XML, an SDOthe implementation MUSTshould use the [CONCRETE_NAME] that provides the best match to the DataObject’s type. [COR07040204] In the case where more than one “best” match is found, the selection of which name is used will be implementation dependent. Specifically, there is no requirement that the [CONCRETE_NAME] from the input document used to generate the DataObject round trip when the object is again marshaled to XML. 2891 2892Elements of Complex Type follow this table, in addition. XML Elements with Complex Type SDO Property where [TYPE] = the (compound) KeyType associated with P_TYPE. 2893 2894Elements of Simple Type follow this table, in addition. 280SDO Core Specification Version 3.0 16 December 2008 281Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 94 of 141 XML Elements with Simple Type SDO Property Element of SimpleType Property name=[NAME] type=[TYPE] where [TYPE] = IDREF, IDREFS, anyURI the KeyType associated with P_TYPE or restrictions of these types 283SDO Core Specification Version 3.0 16 December 2008 284Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 95 of 141 XML Elements with Simple Type SDO Property Element with bidirectional Property name=[NAME] reference to a DataObject with opposite=[PROPERTY] sdox:propertyType and sdox:oppositeProperty type=[P_TYPE] many=true (for IDREFS only) Element of SimpleType with sdox:dataType Property name=[NAME] type=[SDO_TYPE] 2895 XML Schema Element SDO Property special types Element with type SDO Property name=[NAME] ChangeSummaryType type=ChangeSummaryType readOnly=true 28967.5 Mapping of XSD Built in Data Types 2897SDO specifies mappings from XSD to SDO Types. 2898The URI of the SDO Types is http://docs.oasis-open.org/ns/opencsa/sdo/200812. An SDO 2899implementation MUST read simple values whose If the XSD type of the instance valuetype cannot be 2900determined the value is read as a String. [COR07050001]. Note that in cases where the schema does 2901not provide the necessary information, AnySimpleType will read document values in as String unless 2902xsi:type canis be specified in the document. 2903 XSD Simple Type SDO Type anySimpleType Object anyType DataObject anyURI URI (override with sdox:propertyType) 286SDO Core Specification Version 3.0 16 December 2008 287Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 96 of 141 XSD Simple Type SDO Type base64Binary Bytes boolean Boolean byte Byte date YearMonthDay dateTime DateTime decimal Decimal double Double duration Duration ENTITIES Strings ENTITY String float Float gDay Day gMonth Month gMonthDay MonthDay gYear Year gYearMonth YearMonth hexBinary Bytes ID String (signifies the field is a sdo:key field) IDREF String (override with sdox: propertyType) IDREFS Strings (override with sdox: propertyType) int Int integer Integer language String long Long Name String NCName String negativeInteger Integer NMTOKEN String NMTOKENS Strings nonNegativeInteger Integer nonPositiveInteger Integer 289SDO Core Specification Version 3.0 16 December 2008 290Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 97 of 141 XSD Simple Type SDO Type normalizedString String NOTATION String positiveInteger Integer QName URI short Short string String time Time token String unsignedByte UnsignedByte unsignedInt UnsignedInt unsignedLong UnsignedLong unsignedShort UnsignedShort 29047.5.1 Conversion between XSD QName and SDO URI 2905When an XML document is loaded, a value of type xsd:QName, an SDO implementation MUST is 2906convert ited into an SDO URI with a value of: 2907 The namespace name + # + local part 2908where + indicates string concatenation. [COR07050101] 2909When an XML document is saved, a value of type SDO can be converted back to an xsd:QName, if that 2910is the expected XML type: 2911The URI value is parsed into two parts: 2912 – The namespace name is the URI up to but not including the last # character in the URI value. 2913 – The local part is the URI after the last # character in the URI value. 2914An XML namespace declaration for a namespace prefix is made in the XML document. The declaration 2915may MAY be made at any enclosing point in the document in an implementation-dependent manner or an 2916existing declaration may MAY be reused. 2917The declaration is of the form xmlns:prefix="namespace name". 2918The prefix is implementation-dependent. 2919The QName value is of the form prefix:local part. 2920 2921Example: 2922Message is a property of XSD type QName and SDO type URI 2923Load: 2924inputDataObject.getString(message) returns http://www.example.com#inputRequest 2925inputDataObject.setString(message, "http://test.org#testMessage") 2926Save: 292SDO Core Specification Version 3.0 16 December 2008 293Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 98 of 141 29277.5.2 Dates 2928Considering the importance of Date information, it is unfortunate that there are few good software 2929standards for handling this information. 2930SDO chose strings as the default implementation type for Date types because they are the simplest 2931implementation to sufficient to enable technology-independent scenarios. The string representations are 2932from XML Schema and easy to convert to other representations. 2933Operating on Date values, such as applying calendar, time zone, order, duration, and locale settings, is 2934best left to helper and utility libraries. In the case where a string representation is insufficient, 2935sdo:dataType can be used to override the datatype to a custom type 29367.6 Examples of XSD to SDO Mapping XSD SDO Schema declaration uri="http://www.example.com/IPO" 295SDO Core Specification Version 3.0 16 December 2008 296Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 99 of 141 XSD SDO Local Element with Complex Type Property name="shipTo" type="Address" containment=true containingType="PurchaseOrderType" Property name="billTo" type="Address" Local Element with Simple Type Property name="comment" type="String" containingType="PurchaseOrderType" Local Attribute Property name="orderDate" type="YearMonthDay" containingType="PurchaseOrderType" Local Attribute fixed value declaration Property name="country" type="String" default="US" containingType="USAddress" 298SDO Core Specification Version 3.0 16 December 2008 299Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 100 of 141 XSD SDO Multi-valued local element declaration Property name="item" type="ItemType" containment=true many=true containingType="Items" Attribute reference declarations Property name="customer" type="Customer" opposite="Type[name='Customer']/ property[name='purchaseOrder']" 301SDO Core Specification Version 3.0 16 December 2008 302Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 101 of 141 XSD SDO SimpleType unions Type SDO Object is used as the Type for every Property resulting from elements and attributes with SimpleType zipUnion. 2937 Notes: 29381. Examples are from, or based on, IPO.xsd in http://www.w3.org/TR/xmlschema-0/ 29392. Type[name='Customer']/property[name='purchaseOrder'] refers to the declaration of the 2940 purchaseOrder Property in the Type Customer in the same document. 29417.6.1 Example of SDO Annotations 2942This example shows the use of sdox:string and sdox:dataType. 2943 2944 304SDO Core Specification Version 3.0 16 December 2008 305Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 102 of 141 2983 2984 2985 2986 2987 29987.7 XML use of Sequenced Data Objects 2999Sequenced Data Objects are DataObjects with a sequence capturing the additional XML order 3000information, defining an order of values across all DataObject’s instance properties that is specific to XML 3001documents. 3002Sequenced DataObjects have Type.sequenced=true. The XSD to SDO mapping in sections 7.3 and 7.4 3003define when defines an XML DataObjecta complex type in schema is mapped to a sequenced type in 3004SDO. The default value may be overridden using to be used whenthe sdox:sequence="true" is declared 3005attribute in the XSD type. 3006The XML use of Sequenced DataObject defines have a Sequence returned that can be accessedfrom 3007using the DataObject interface: 3008.getSequence() method. This method returns - Aa Sequence of all the elements and mixed text in the 3009content of an XML element. Each entry in the Sequence represents either one XML element designated 3010by the entry's Property, or XML mixed text, designated by a null Property. The name of the property is the 3011same as the name of the XML element unless sdox:name was used to replace the name. 3012The values of the entries are are available through both the Sequence API and the DataObject API for the 3013Properties. 3014DataObject.getInstanceProperties() includes all the Properties in the Sequence. For open content, where 3015XML any declarations were used, the Properties of some entries might not be declared in the 3016DataObject's Type. The order of the entries in the Sequence is MUST BE the same as the order of XML 3017elements. [COR07070001] 30187.8 XSD Mapping Details 3019An implementation of SDO MUST follow theseThe following guidelines apply when mapping XSD to SDO: 30201. The order of the Properties declared within a Type is the order of their declaration in an XSD. All 3021 Properties of the Type extended precede local declarations within the Type. 30222. The XSD names are preserved in the Type and Property. Use the sdox:name override to modify 3023 names as an option to remove duplicate names, blank names, or names with special characters. 30243. All declarations not covered in this Mapping may MAY be ignored by a compliant implementation. 30254. All 307SDO Core Specification Version 3.0 16 December 2008 308Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 103 of 141 30327. Redefinitions are expanded to the equivalent XSD as if these declarations were not present. 30338. Model Groups (sequence, all, choice, group) do not contribute to the mapping except for 3034 maxOccurs>1 results in Properties with many=true. 30359. Global group and attribute group declarations that include type declarations follow the normal 3036 mapping rules for those type declarations. The same types are used in all places the groups are 3037 referenced. 303810. When an element of anyType is used with xsi:type specifying simple content, a wrapper DataObject 3039 (see Data Type Wrappers) is created with a property named "value" and type of SDO Object that is 3040 set to the wrapped type. For example, 30447.9 Compliance 3045The mappings here are the base mappings. Vendors may MAY extend the mappings provided that client 3046programs developed against these mappings continue to run. [COR07090001] An SDO program using 3047this mapping, and the DataObject, should be portable across vendor-added mappings and 3048implementations. 30497.10 Corner cases 3050This specification does not standardize the mapping for corner cases. We follow the principle that 3051complexity is never added to the simple cases to handle these more advanced cases. It is possible that 3052Ffuture versions of SDO maywill define mappings for these corner cases. 30531. List of lists without unions. 30542. Multi-valued nillable Properties with DataObject Types. 30553. key and keyref. 30564. When an element of anyType is used with xsi:type specifying simple content, a wrapper DataObject 3057 (see Data Type Wrappers) must be used with a property named "value" and type of SDO Object that 3058 is set to the wrapped type. For example, 30717.11 XML without Schema to SDO Type and Property 3072When no meta information is available during the parsing of a document, that is, the document does not 3073have a schema and the properties and types in the document are not otherwise known to the SDO 3074application, the following algorithm defines how the document contents willare be converted to SDO 3075DataObjects using the following algorithm:. 30761. To represent tThe rootObject of the document, an SDO implementation MUST BEwill be an open, 3077 sequenced, mixed data object. [COR07110001] 310SDO Core Specification Version 3.0 16 December 2008 311Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 104 of 141 30782. If an attribute or element contains a URI, the implementation must MUST attempt to locate the 3079 property definition as if by calling XSDHelper.getGlobalProperty() using the specified URI and 3080 property name. [COR07110002] 30813. 30824. Attributes for which no meta-information is available are MUST BE interpreted as open content String 3083 properties, where the name of the property is the local name of the attribute. [COR07110003] 30845. Elements for which no meta-information is available are MUST BE interpreted as open content 3085 properties, where the name of the property is the local name of the element. The property will MUST 3086 always have containment=true. [COR07110004] 30876. If multiple instance of the same element occur within a containing element instance, the open content 3088 property corresponding to the element will MUST have isMany=true. Otherwise an implementation 3089 may MAY create the property with isMany=false. [COR07110005] 30907. The type of the created property will not necessarily be identical to the type of the value read from an 3091 element, since, in the case of multi-valued properties it is possible that the types of the elements 3092 maydo not agree. However, Iif an element contains an xsi:type attribute, the value MUST BEit is used 3093 to determine the type of the value. If no xsi:type attribute is present and the content is simple, then 3094 the value's type will be implementation dependent. If the content is complex, the value must beMUST 3095 BE interpreted as an open, sequenced, mixed type (similar to the type of the document's root 3096 element); an implementation will MUST provide a single Type to handle all such cases. 3097 Implementations MAYmay use wrapper objects (see 7.10: Corner Cases, point 4) to contain simple 3098 values. [COR07110006] 30998. An implementation must MUST define the property type such that all the values of the property 3100 conform, and the type information is available. If the property is single valued, or if the type of all 3101 elements in a multi-valued property agree, an implementation may MAY create the property of the 3102 value type itself. However, implementations mayMAY, instead, choose to create the property with a 3103 more general type, such as {http://docs.oasis-open.org/ns/opencsa/sdo/200812}Object or 3104 {http://docs.oasis-open.org/ns/opencsa/sdo/200812}DataObject. Applications are expected 3105 toSHOULD use meta-data introspection to determine the contents and structure of the received data 3106 objects. [COR07110007] 31079. Any properties created in the previous steps are local to their containing DataObject, i.e. they are 3108 MUST NOT not available via the TypeHelper.getOpenContentProperty() API. [COR07110008] 313SDO Core Specification Version 3.0 16 December 2008 314Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 105 of 141 31098 Generation of XSD from SDO Type and Property 3110When SDO Types and Properties did not originate from an XSD definition, it is often useful to define the 3111equivalent XML schema declarations. 3112When an XSD is generated from Type and Property it contains all the information defined in the SDO 3113Model. An SDO implementation MUST generate an XSD generated from a Type such that the XSD type 3114and Property will round trips back to an SDO Type that is identical to the original Type and Property. 3115[COR08000001] However, if the XSD was not generated and is used to create the Type and Property, 3116regenerating the XSD will not necessarily round trip to produce the original. This is because there is more 3117information in an XSD than in Type and Property, primarily focused on defining the XML document 3118syntax. 3119The mapping principles are summarized in this table. A URI defines a schema and a target namespace. 3120An SDO Type defines an XSD complex type and a global element declaration. An SDO property defines 3121either a local element or an attribute in a complex type. 3122 SDO XSD URI 3123 3124Each XSD contains Types with the same URI. When referring to other ComplexTypes, the 3125implementation is responsible for generating the appropriate import and include XSD declarations. 3126An XSD can only be generated when: 31271. Multiple inheritance is not used. 3128 – That is, all Types have no more than 1 base in Types.getBaseTypes(). 31292. The names of the Types and Properties are valid XSD identifiers. 3130The following defines the minimal XML schema declarations. When opening XML elements are shown the 3131appropriate ending XML element is produced by the implementation. An SDO implementation may MAY 3132include additional declarations as long as documents that validate with the generated schema also 3133validate with the customized schema. [COR08000004] In addition, an implementation is expected to 3134generate all required namespace declarations, includes, and imports necessary to produce a valid XML 3135schema. 3136If a namespace declaration shown in the generation templates is not used by the XSD, it may can be 3137suppressed. Namespace declarations may can have prefix names chosen by the implementation (instead 3138of xsd, sdo, sdoj, and tns). The specific elements containing the namespace declarations are determined 3139by the implementation. 3140It is permissible to generate the xmi:version attribute from the XMI specification to enable XMI conformant 3141software to read the XSDs and valid XML documents. 316SDO Core Specification Version 3.0 16 December 2008 317Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 106 of 141 3142An SDO implementation MUST generate tThe Schema element itself is generated with a target 3143namespace determined by the URI of the Types that will be defined in the schema. [COR08000002]. 3144[URI] is defined by type.uri. If [URI] is null then the XSD is generated without a targetNamespace. 3145 SDO XSD Schema 3146 3147For each Type that is a dataType, type.dataType==true, an SDO implementation MUST generate an XSD 3148SimpleType is generated. The SimpleType is basedas on the followsing: 3149 [NAME] is type.name 3150 [ABSTRACT] is type.abstract. 3151 [ALIAS_NAME] is space separated values from type.aliasNames and is produced if there are alias 3152 names. 3153 [BASE.NAME] is the name of the base type, type.getBaseTypes().get(0).getName() if not null. When 3154 not null, the simple type extends the base type. tns: is the prefix for the URI of the base type, 3155 type.getBaseTypes().get(0).getURI(). If the base type is in another namespace the appropriate 3156 namespace and import declarations are produced by the implementation. If there are no base 3157 types, then the xsd type used is from the table "Mapping of SDO DataTypes to XSD Built in Data 3158 Types". 3159 . based on the instance class. 3160[COR08000005] 3161 3162 SDO Type XSD SimpleType [ABSTRACT] abstract="true" [ALIAS_NAME] sdox:aliasName=[ALIAS_NAME] [BASE.NAME] 3163 3164For each Type that is not a dataType, type.dataType==false, an SDO implementation MUST generate an 3165XSD ComplexType and a global element is generated. The ComplexType is based on the following: 3166 [NAME] is type.name. If an implementation can determine that a particular SDO type has been 3167 created based on an anonymous Schema type declaration and both the type and its containing 3168 Schema component are to be generated, then the implementation can use an anonymous type 3169 declaration in the generated XSD. 3170 [ABSTRACT] is type.abstract. 3171 [ALIAS_NAME] is space separated values from type.aliasNames and is produced if there are alias 3172 names. 319SDO Core Specification Version 3.0 16 December 2008 320Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 107 of 141 3173 [BASE.NAME] is the name of the base type, type.getBaseTypes().get(0).getName() and is produced 3174 if not null. When produced, the complex type extends the base type. tns: is the prefix for the URI 3175 of the base type, type.getBaseTypes().get(0).getURI(). If the base type is in another namespace 3176 the appropriate namespace and import declarations are produced by the implementation. 3177 [SEQUENCED] indicates if the type is sequenced, type.sequenced. If true, the complex type 3178 declaration is mixed and the content of the element is placed in a [ABSTRACT] abstract="true" [ALIAS_NAME] sdox:aliasName=[ALIAS_NAME] [BASE.NAME] 3188 3189For each property in type.getDeclaredProperties(), either an element or an attribute will beis generated, 3190declared withinas the content of the complexType corresponding to the SDO typeproperty's containing 3191type property.getContainingType(). An element is generated iIf property.many, property.containment, or 3192property.nullable is true, or if property.get(xmlElement) is present and set to true, where xmlElement is an 3193open content property in http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812 an SDO implementation 3194MUST generate an element; i. If the property is bidirectional and the opposite property has 3195containment=true, an SDO implementation MUST generate neither an element nor an attribute; onothing 3196is generated. Otherwise, an SDO implementation MUST generate an attribute is generated. 3197[COR08000007] Round-trip between SDO models and their generated XSDs will preserve the order of 3198the properties when all elements are generated. When an SDO implementation generates an element it 3199MUST base the element on: 3200 [NAME] is property.name 3201 [ALIAS_NAME] is space separated values from property.aliasNames and is produced if there are 3202 alias names. 3203 [READ_ONLY] is the value of property.readOnly and is produced if true. 3204 [MANY] indicates if property.many is true and maxOccurs is unbounded if true. 322SDO Core Specification Version 3.0 16 December 2008 323Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 108 of 141 3205 [CONTAINMENT] indicates if property.containment is true. 3206 When containment is true, then DataObjects of that Type will appear as nested elements in 3207 an XML document. 3208 When containment is false and the property's type is not a data type, then by default the 3209 generated element or attribute will have the XSD type AnyURI and an sdox:propertyType 3210 declaration records the target type. Values in XML documents will be of the form "#xpath" 3211 where the xpath is an XPath expression, like the ones used in the ChangeSummary XML 3212 format described in ChangeSummary XML format. 3213 When containment is false and the property's type is a type for which key properties have 3214 been specified, it is also possible to the key type to represent the non-containment reference. 3215 See the 8.3: Generating XSD from Types using Keys. 3216 [OPPOSITE.NAME] is the opposite property if the property is bidirectional and indicated when 3217 property.opposite is not null. 3218 [NULLABLE] is the value of property.nullable and is produced if true. 3219[COR08000008] 3220 SDO Property XSD Element [ALIAS_NAME] sdox:aliasName=[ALIAS_NAME] [READ_ONLY] sdox:readOnly=[READ_ONLY] [MANY] maxOccurs="unbounded" [CONTAINMENT] type="tns:[TYPE.NAME]" ![CONTAINMENT] type="xsd:anyURI" sdox:propertyType="tns:[TYPE.NAME]", it is also possible to use keys may also be used to represent non-containment relationships. Users may set If xsdType is set to the XSD type matching the target type’s keyType to express this, then an SDO implementation MUST render the reference using the value of the key. [COR08000003] [OPPOSITE.NAME] sdox:oppositeProperty=[OPPOSITE.NAME] [NULLABLE] nillable="true" 3221 3222 3223When an SDO implementation generates an attribute it MUST base the attribute on: 3224 [NAME] is property.name 3225 [ALIAS_NAME] is space separated values from property.aliasNames and is produced if there are 3226 alias names. 3227 [READ_ONLY] is the value of property.readOnly and is produced if true. 3228 [DEFAULT] is property.default and is produced if the default is not null and the default differs from the 3229 XSD default for that data type . 3230 [TYPE.DATATYPE] indicates if property.type.dataType is true. 3231 When isDataType is true, [TYPE.NAME] is the name of the XSD built in SimpleType 3232 corresponding to property.type, where the prefix is for the xsd namespace. 325SDO Core Specification Version 3.0 16 December 2008 326Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 109 of 141 3233 When isDataType is false, [TYPE.NAME] is property.type.name where the tns: prefix is 3234 determined by the namespace declaration for the Type's URI. A URI reference to the element 3235 containing the DataObject is used and an sdox:propertyType declaration records the target 3236 type. Values in XML documents will be of the form "#xpath" where the xpath is an XPath 3237 expression, like the ones used in the ChangeSummary XML format described in Chapter 10: 3238 ChangeSummary XML format. here. It is typical to customize the declaration to IDREF if the 3239 target element has an attribute with type customized to ID. 3240 [OPPOSITE.NAME] is the opposite property if the property is bidirectional and indicated when 3241 property.opposite is not null. 3242 3243[COR08000009] SDO Property XSD Attribute [ALIAS_NAME] sdox:aliasName=[ALIAS_NAME] [READ_ONLY] sdox:readOnly=[READ_ONLY] [DEFAULT] default=[DEFAULT] [TYPE.DATATYPE] type="tns:[TYPE.NAME]" ![TYPE.DATATYPE] type="xsd:anyURI" sdox:propertyType=tns:[TYPE.NAME] [OPPOSITE.NAME] sdox:oppositeProperty=[OPPOSITE.NAME] 32448.1 Mapping of SDO DataTypes to XSD Built in Data Types 3245For SDO Date and for SDO Character, an sdox:dataType annotation is generated on the XML attribute or 3246element referring to the SDO Type. 3247 328SDO Core Specification Version 3.0 16 December 2008 329Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 110 of 141 SDO Type XSD Type Boolean boolean Byte byte Bytes hexBinary Character string DataObject anyType Date dateTime DateTime dateTime Day gDay Decimal decimal Double double Duration duration Float float Int int Integer integer Long long Month gMonth MonthDay gMonthDay Object anySimpleType Short short String string Strings string Time time Year gYear YearMonth gYearMonth YearMonthDay date URI anyURI 32488.2 Tuning the Default Mapping using Open Content Properties 3249Open content properties in http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812 are used to modify the 3250default mapping for of SDO types and properties. It is also possible to read Tthese values may also be 3251read, for instance, to determine the characteristics of the schema docment used to generate the SDO 3252metadata. 3253The following properties are defined 3254 331SDO Core Specification Version 3.0 16 December 2008 332Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 111 of 141 http://docs.oasis-open.org/ns/opencsa/sdo/xml/200812 Type applies to property xmlElement boolean Property xmlType URI Property, data string Type 3255 3256Setting the xmlElement property is set to true forces Properties represented as XML elements. Setting 3257the value to false does not guarantee that the annotated property will map to an XML attribute. S, since 3258this ismay not be always possible. For example, a containment property, nullable property, or demand 3259created open content property must beare always serialized as an XML elements. 3260Setting the xmlType property to overrides the default mapping of a property or data type. The value 3261should be the standard SDO string representation of the URI of the desired schema type. An important 3262use of this annotation is to force the use of keys as the representation of non-containment references. 32638.3 Generating XSD from Types using Keys 3264Non-containment references are by default represented by default as XPath expressions. In cases where 3265it is known that the key values are set before XML serialization is requested, the xsdType property may 3266be setcan be used to indicate that the key values be used to expressXML representation the non- 3267containment reference should be the key value rather than the XPath expression. TThe xsdType has to 3268must match the keyType of the referenced object. If the key type is a DataType and the reference is 3269single-valued, the reference is an SDO implementation MUST, by default, rendered it as an attribute. 3270[COR08030001]. An SDO implementation MUST render complexIf the keys type is complex and , or the 3271reference is multivalued, the references is rendered as an elements. [COR08030002] In either 3272caseWhenever a non-containment reference is redenderd in schema, whether XPath or keys are used, 3273and regardless of whether the reference is rendered as a attribute or element, an SDOthe implementation 3274must MUST also annotate the attribute or element with “sdox:propertyType”. [COR08030003] 3275To illustrate, we start with the example from 4.5.3: Key Properties: 3276OrderType 3277 - id (type=String, key=true) 3278 - customer (type=CustomerType) 3279 - lineItems (type=LineItemType, many=true, opposite=order, xsdType=LineItemKeyType) 3280 3281LineItemType (keyType=LineItemKeyType) 3282 - order (type=OrderType key=true opposite=lineItems, xsdType=String) 3283 - lineNumber (type=Int, key=true) 3284 - productID, etc. 3286LineItemKeyType 3287 - order (type=String) 3288 - lineNumber (type=Int) 3289 3290Generating XSD from these types results in: 3291 3292 334SDO Core Specification Version 3.0 16 December 2008 335Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 112 of 141 3295 3316 3317As shown, the sdox:key and sdox:keyType annoations are generated to indicate the key metadata for 3318OrderType and LineItemType. Notice also that the OrderType.lineItems and LineItemType.order 3319references are generated to use the key-based referencing pattern described above. 33208.4 Example Generated XSD 3321If the Types and Properties for the PurchaseOrder schema had not come originally from XSD, then these 3322rules would produce the following XML Schema. 3323 3324 337SDO Core Specification Version 3.0 16 December 2008 338Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 113 of 141 3352 3353 3354 3355 3374 3375The following is the serialization of the example purchase order that matches this schema. 3376 3377 3378 33938.5 Customizing Generated XSDs 3394Because an XSD contains more information than Type and Property, there are many XSD capabilities 3395unused by the default generation, for example the preference between serializing with XML elements or 3396attributes. The recommended procedure is to generate the XSD from Types and Properties, customize 3397the XSD using tools or with XSLT, and use the customized XSD as the original from which to define the 3398SDO Types and Properties. 340SDO Core Specification Version 3.0 16 December 2008 341Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 114 of 141 33999 SDO Path Expression for DataObjects 3400Many of the accessor methods for DataObjects make use of a String parameter that provides the path 3401that identifies the property to which the method applies. 3402 3403An SDO Path is a subset of XPath 1.0 [XPath]. The syntax for specifying these paths, is shown here: 3404 3405 path ::= (scheme ':')? '/'? (step '/')* step 3406 scheme ::= [^:]+ 3407 step ::= property 3408 | property '[' index_from_1 ']' 3409 | property '[' namespace-uri() '=' uri ']' 3410 | reference '[' attribute '=' value ']' 3411 | ".." 3412 property ::= NCName ;; may be simple or complex type 3413 attribute ::= NCName ;; must be simple type 3414 reference :: NCName ;; must be DataObject type 3415 index_from_1 ::= NotZero (Digits)? 3416 value ::= Literal 3417 | Number 3418 | Boolean 3419 Literal ::= '"' [^"]* '"' 3420 | "'" [^']* "'" 3421 Number ::= Digits ('.' Digits?)? 3422 | '.' Digits 3423 Boolean ::= true 3424 | false 3425 NotZero ::= [1-9] 3426 Digits ::= [0-9]+ 3427 3428 ;; leading '/' begins at the root 3429 ;; ".." is the containing DataObject, using containment properties 3430 ;; Only the last step have an attribute as the property 3431 3432NOTE: Previous versions of the SDO specification allowed for a zero-based dot syntax to specify the 3433index (e.g., "departments.0"), and an @ sign (without meaning) to precede a property in the syntax (e.g., 3434“departments[1]/@number”). Both of these have been deprecated in SDO 3.0, but SDO implementations 3435may MAYchoose to allow them for backwards compatibility. [COR09000002] 3436 3437The scheme is an extension mechanism for supporting additional path expressions in the future. No 3438schema and a scheme of "sdo:" are equivalent, representing this syntax. The "xml:" scheme provides a 3439proper syntactic and semantic subset of standard XPath [XPath]. If a scheme of "xml:" is used, an SDO 3440implementation MUST do name matching based on the XML representation (i.e., the XML element or 3441attribute names), including distinguishing between attributes and elements based on whether or not the 3442local name was preceeded by a “@” sign. [COR09000001]. A scheme of "xml:" also represents this same 3443syntax, only with matching based on the XML representation (i.e., the XML element or attribute names). 3444The "xml:" scheme provides a proper syntactic and semantic subset of standard XPath [XPath]. As with 3445standard XPath, in this case attribute names must be preceeded by the @ character. For example, unlike 3446get(”sdo:number”), get(”xml:number”) would returns null if “number” is not an XML element, while; 3447get((”xml:@number”) must be used in this casereturns the property’s value.. 3448 343SDO Core Specification Version 3.0 16 December 2008 344Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 115 of 141 3449Consider the Company model described in Complete Data Graph for Company Example. One way to 3450construct an SDO Path that can be used to access a DataObject contained in another DataObject is to 3451specify the index of the contained DataObject within the appropriate property. For example, given an 3452instance of a Company DataObject called “company” one way to access the first Department in the 3453“departments” list is: 3454 3455 department = company.getDataObject("departments[1]"); 3456 3457Another way to access a contained DataObject is to identify that object by specifying the value of one of 3458the attributes of that object. So, for example, given a Department DataObject called “department”, one 3459way to access the Employee where the value of the “SN” attribute is “E0002” is: 3460 3461 employee = department.getDataObject("employees[SN='E0002']"); 3462 3463If there are more than one Employee DataObjects that have their “SN” property/attribute values equal to 3464“E0002”, the first Employee DataObject in the list is returned. If no Employee DataObject matches the 3465[SN=’E0002’] criteria, null is returned. 3466 3467It is also possible to write a path expression that traverses one or more references in order to find the 3468target object. The two accesses shown above can be combined into a single call that gets the Employee 3469using a path expression that starts from the company DataObject, for example 3470 3471 employee = company.getDataObject("departments[1]/employees[SN='E0002']"); 3472 3473SDO Path expressions can also be used to set/unset values of properties, including multi-valued 3474properties. In these cases, set(String path, …) changes values in the list without changing the size of the 3475list and unset(String path) removes values from the list. For example, if “myList” is a multi-valued property 3476on the “myDataObject” DataObject, then: 3477 3478 List list = myDataObject.get("myList"); 3479 // Let’s assume that at this point the list is empty 3480 3481 list.add("one"); 3482 list.add("two"); 3483 3484 // Changes the second element to "three" so the list will be 3485 // "one", "three" 3486 myDataObject.set("myList[2]", "three"); 3487 3488 // An unspecified runtime exception will be thrown because the index 3489 // exceeds the list size 3490 myDataObject.set("myList[3]", "three"); 3491 3492 // Variable b1 will be true because the specified index is smaller 3493 // than the size of the list 3494 boolean b1 = myDataObject.isSet("myList[1]"); 3495 3496 // Variable b2 will also be true 3497 boolean b2 = myDataObject.isSet("myList[2]"); 3498 3499 // Variable b3 will be false because the index is greater than 346SDO Core Specification Version 3.0 16 December 2008 347Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 116 of 141 3500 // the size of the list 3501 boolean b3 = myDataObject.isSet("myList[3]"); 3502 3503 // An unset() call will remove elements from the list 3504 myDataObject.unset("myList[1]"); 3505 // The list now contains one element: "three" 3506 3507 // An unset() call can throw an unspecified runtime exception 3508 myDataObject.unset("myList[99]"); 3509 3510If more than one property shares the same name, only the first is matched by the path expression, using 3511property.name for name matching. The second, or subsequent, property can be accessed by qualifying 3512the name using the namespace-uri() function: 3513 3514 // Access the first "foo" property 3515 Object foo1 = dataObject.get("foo"); 3516 3517 // Aceess a duplicate open-content "foo" property in namespace 3518 // "http://the-tns2-namespace" 3519 Object foo2 = 3520 dataObject.get("foo[namespace-uri()='http://the-tns2-namespace']"); 3521 3522If there are alias names assigned, those are also used to match. Also, names including any of the special 3523characters of the syntax (/[]=’”) are not accessible. Each step of the path before the last must has to 3524return a single DataObject. When the property is a Sequence, the values returned are those of the 3525getValue() accessor. 349SDO Core Specification Version 3.0 16 December 2008 350Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 117 of 141 352610 ChangeSummary XML format 3527ChangeSummary elements are located in XML documents according to the normal rules accociated with 3528properties of a type. For instance, a property named “changeSummary” having ChangeSummaryType is 3529serialized as an element with local name “changeSummary” within the XML structure corresponding to 3530the containing (envelope) object. 3531An SDO implementation MUST render the ChangeSummary element if either of the conditions apply: 3532 Changes have been logged (getChangedDataObjects().size() > 0). 3533 No changes have been logged but isLogging() is true at the time of serialization. 3534[COR10000001] 3535When deserializing an empty ChangeSummary element, an SDO implemention MUST create a 3536changeSummary object having logging==true. [COR10000002] Otherwise, the logging state is given by 3537the corresponding attribute. 3538The serialization of the ChangeSummary includes enough information to reconstruct the original 3539information state of the DataObjects in its scope at the point when logging was turned on. The goal of 3540this format is to provide a simple XML representation that can express the difference between the graph 3541when logging began and ended. The serialization of the state when logging is ended is the complete 3542XML as serialized from XMLHelper and is referred to as the final XML in this section to contrast with the 3543changeSummary XML. 354410.1 ChangeSummary Creation and Deletion Attributes 3545When serializing a ChangeSummary, an SDO implementation MUST fill the @create attribute with 3546references to every DataObject which in the ChangeSummary’s getChangedObjects() list for which 3547isCreated returns trueare currently in the data graph, but were not present when logging was started 3548MUST be indicated in the change summary with a create attribute. [COR10010001] For example, if the 3549employee “Al Smith” with ID “E0004” was added: 3550 3551 352SDO Core Specification Version 3.0 16 December 2008 353Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 118 of 141 3567Similarly, DataObjects deleted during logging are flagged with the “delete” attribute. In this case the 3568change summary also contains a deep copy of the object which was deleted, as it no longer appears in 3569the data graph. (Contained children of the deleted object are not included in the “delete” attribute.) Also, 3570the position in the tree must be recorded, so the departments property is reproduced, where there is an 3571employees element for each employee object. The sdo:ref attribute is used to indicate the corresponding 3572object that is represented in both the changeSummary and the final document. 3573For example, 360110.2 Serialization Format for References 3602When serializingThe references to DataObjects as a value of an sdo:ref attribute, or included in 3603ChangeSummary’s create or delete attributes, an SDO implementation MUSTabove are use IDREFs 3604when IDs are available, and XPath expressions otherwise. [COR10020001], to locate the data object. 3605XPath expressions are distinguishable from ID references in that they start with a ‘#’ character. Key 3606properties, other than those identified using the schema ID type, are not used as values of sdo:ref or as 3607elements of the created or deleted lists. 3608XPath expressions differ from SDO object paths as described in SDO Path Expression for DataObjects, in 3609particular, XPath expressions can navigate into the ChangeSummary. This is necessary so that 3610references to deleted objects can be expressed. An XPath expression contains namespace information 3611and element names from the serialized DataObject. All elements inside the ChangeSummary are 3612indexed. 3613If there were no IDs available in the previous example (that is, either IDs were not defined, or simply not 3614set), XPath expressions would be used exclusively for the references: 3615 3616 355SDO Core Specification Version 3.0 16 December 2008 356Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 119 of 141 3620 employeeOfTheMonth= 3621 "#/changeSummary/departments[1]/employees[2]"/> 3622 3630 3631Note that in this case XPath expressions are used for normal cross references (employeeOfTheMonth) as 3632well, not just for the SDO attributes (create, delete, and ref). 363310.3 Serialization Format for Sequenced DataObjects 3634If the Type is sequenced, then the serialized change summary will MUST contain the complete sequence 3635of elements and intermixed text as it existed at the point that logging was started, with elements that are 3636still represented in the final document containing only an sdo:ref attribute pointing to that respective 3637element in the serialized graph. [COR10030001] 3638Note: For serialization of ChangeSummary information in case of many-valued properties or sequenced 3639objects, implementations are allowed to follow a different format than the one described in this document, 3640if interoperability is not required. 364110.4 Serialization Format for DataObject Modifications 3642The content of a ChangeSummary element representing a deleted object is a deep copy of the object at 3643the point it was deleted, where the deleted property value was a data object type. 3644Where changes made were only to data type properties of a data object, an SDO implementation MUST 3645include a copy of data object in, the ChangeSummary element, but the contains a copy MUST of the data 3646object from the data graph, but containing only the properties which that have changed, and showing their 3647old values. [COR10040001] For example, changing the company name places just the changed 3648information in the change summary:. 3649 3650 3662 3663If a multivalued property was modifed, an SDO implementation MUST reproduce the entire list. 3664[COR10040002] If the property’s type is not a dataType, an SDO implementation MUST render 3665unaltered elements using the sdo:ref attribute to indicate the corresponding object in the final document. 3666[COR10040003] 3667If an old value is not present in the ChangeSummary, it is assumed not to have changed. If the old value 3668a property was not set when logging began, an SDO implementation MUST represent the old state in the 3669ChangeSummary using an “unset” attribute. [COR10040004], it is represented in the ChangeSummary 358SDO Core Specification Version 3.0 16 December 2008 359Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 120 of 141 3670using an “unset” attribute. For example, if comment is an optional property of product and is set for the 3671first time. 3672 3673 3688 3689The value of the “unset” attribute is a space-separated list of previously unset changed properties of the 3690corresponding referenced object. Multi-valued datatype properties and mutli-valued non-containment 3691properties have their entire old and new values in the changeSummary and final XML respectively. For 3692example, if availableColors is a multi-valued property for a product, and the availableColors change: 3693 3694 3711 3712When an object that was formerly contained is deleted, there is always a corresponding change to the 3713object that contained the deleted object, namely, the property through which the deleted object was 3714formerly contained has been modified. If the deleted object was formerly contained, an SDO 3715implementation MUST serialize a deep copy of the object in-place, as part of the modification to the 3716parent object. [COR10040005] 3717For example, 361SDO Core Specification Version 3.0 16 December 2008 362Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 121 of 141 3724 3725 375110.5 Example Use of ChangeSummary on a DataObject 3752A common use of defining DataObject Types with a ChangeSummary is when wrapping specific existing 3753types such as PurchaseOrders along with a ChangeSummary tracking their changes. A message header 3754defined by the following XSD is an example. 3755 3756 3763 3764The following is an example message document: 3765 3766 364SDO Core Specification Version 3.0 16 December 2008 365Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 122 of 141 3778 367SDO Core Specification Version 3.0 16 December 2008 368Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 123 of 141 377911 DataType Conversions 3780In the tables in this section, x indicates that cConversions with an x areis supported through DataObject 3781or DataHelper and. X indicates an are identity where the input and output are the same. Individual 3782languages MAY might support converstions involving types specific to the language. Other conversions 3783are not supported, including combinations not in these tables. Conversions of Lists to String are done by 3784converting each element of the list to a string and adding a space character between each converted 3785element. 3786 3787 l t t t r r s n e e g g e r l a t t a n e e e a I n To-> n t o i y b t a o g l m c r e o h y i l u t B e D a F L t c S o o B r S n e o a I D D From B h C | V Boolean X x Byte X x x x x x x x x Character X x Double x X x x x x x x x Float x x X x x x x x x Int x x x X x x x x x Long x x x x X x x x x x Short x x x x x X x x x String x x x x x x x x X x x x x Bytes x X x Decimal x x x x x x x X x Integer x x x x x x x x x X Date x x X 3788 370SDO Core Specification Version 3.0 16 December 2008 371Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 124 of 141 r y y s y g e e n h e h t t t a a a g a To-> n o i i a m n m n e i n i t r D D D i t o o D Y r a T T h h t r S t t e M M t u S r n n a a o o D From e D M M Y r | a e V Y String X x x x x x x x x x x x Day x X x Date x x X x x x x x x x x DateTime x x X Duration x x X Month x x X MonthDay x x X Strings x X Time x x X Year x x X YearMonth x x X YearMonthDay x x X 378912Conformance 3790This specification identifies an SDO implementation as its only conformance target. 379112.1 SDO Implemenation 3792An implementation that claims to conform to the requirements of this specification MUST meet the 3793conditions: 3794 1. The implementation MUST comply with all mandatory statements listed in Conformance Items. 379512.1.1 Optional Items 3796In addition to mandatory items Conformance Items lists a number of non-mandatory items that can be 3797implemented by a compliant implementation. 373SDO Core Specification Version 3.0 16 December 2008 374Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 125 of 141 3798A. Complete Data Graph Examples 3799 A.1 Complete Data Graph Serialization 3800 A.2 Complete Data Graph for Company Example 3801The following XML represents the complete serialization of the data graph. 3802 3803 376SDO Core Specification Version 3.0 16 December 2008 377Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 126 of 141 3852 3853 3854 3855 A.3 Complete Data Graph for Letter Example 3856In this data graph, no summary information is sent. 3857 3858 3871 3872The XSD used is the following: 3873 3874 3887 A.4 Complete WSDL for Web services Example 3888The full WSDL from the Using Web services with data graph Example: 3889 379SDO Core Specification Version 3.0 16 December 2008 380Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 127 of 141 3904 type="company:CompanyDataGraphType"/> 3905 382SDO Core Specification Version 3.0 16 December 2008 383Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 128 of 141 3945B. Conformance Items COR03000001 An SDO implementation MAY provide additional functionality so that valid results would be returned where this specification would produce an error, provided that the functionality is a strict superset and all valid uses of the SDO specification operate correctly. COR04010301 An SDO implementation MUST convert between the data type of the property and the requested data type for all conversions defined in Chapter 11: DataType Conversions. COR04010302 An SDO implementation MUST convert between DataType values and wrapper DataObjects (i.e., Data Type Wrappers). COR04010303 An SDO implementation MUST support all conversions specified in DataType ConversionsDataType Conversions when converting from DataWrappers to DataTypes. COR04010401 An SDO implementation MUST return an empty list, rather than a null value, for all property accessors that have a return type of List, whether in the DataObject interface or in a static API, even if the property has no value. COR04010402 An SDO implementation MUST make all modifications to a returned List visible in the DataObject, so that all operations, reflect the updated list contents. COR04010403 An SDO implementation MUST make updates to the DataObject visible though a returned List object. COR04010501 For many-valued properties, isSet(property) MUST return: True, if the List is not empty. False, if the List is empty. COR04010502 For single-valued properties, isSet(property) MUST return: True, if the Property has been set(), and not unset(). False, if the Property has not been set(), or has been unset(). COR04010504 After unset() has been called on a single-valued property, get(property) and get 385SDO Core Specification Version 3.0 16 December 2008 386Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 129 of 141 COR04010701 If the DataObject's Type is a sequenced type then the SDO implementation MUST place the created DataObject at the end of the Sequence. COR04010702 If the Property is single-valued, an SDO implementation MUST set the value of the Property, to the object created by DataObject.create(). COR04010703 If the Property is multi-valued, an SDO implementation MUST add the object created by DataObject.create() as the last object in the value list. COR04010704 The delete() method MUST unset all the DataObject’s non-readonly properties. COR04010705 If the containment Property is not read-only, the delete() method MUST also remove the DataObject from its containing DataObject. COR04010706 When delete is called, all DataObjects directly or indirectly contained by containment properties MUST also be deleted. COR04010707 If other DataObjects have one-way, non-containment properties that refer to deleted DataObjects, then these references MUST NOT be modified. COR04010801 If a DataObject's Type is not sequenced then getSequence() MUST return null. COR04010901 The isSet() method invoked on an open content property in the list of instance properties MUST return true. COR04010902 If the specified property name does not already exist in a DataObject an SDO Implementaion MUST dynamically define the open content property and add it as an instance property of the DataObject. COR04010903 A demand-created property created by an SDO Implemention MUST be equivalent to an open content property explicitly created by calling TypeHelper.defineOpenContentProperty(null, property) according to the specified rules. COR04010907 When deriving a property type from a value that is an instance of DataObject, an SDO implementation MUST create a property with the same type as the DataObject (returned by DataObject.getType()). COR04010904 If the value is not a DataObject, an SDO implementation MUST create a property with a DataType whose Type is compatible with the value. COR04010906 If getList() is called on an undefined property, an SDO implemenation MAY return a value of null or an empty list. COR04010905 An SDO implementation MUST automatically serialize sufficient metadata along with the instance so that an equivalent instance property is reconstituted on de-serialization.[ COR04011301 The get(String path) method MUST return null instead raising an error for error conditions, for example if “path” refers to a non-existing property. COR04011302 The get 388SDO Core Specification Version 3.0 16 December 2008 389Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 130 of 141 COR04011401 If the value set on a Property does not meet a facet or constraint, such as an XSD range restriction, an SDO implementation MAY raise an implementation specific error or MAY delay raising an error to a later time when validation is more appropriate. COR04020201 DataObject.getChangeSummary() invoked on the ChangeSummary root, or on any DataObject contained, directly or indirectly, by the ChangeSummary root, MUST return the same ChangeSummary object. COR04020202 DataObject.get(“changeSummaryProperty”) where “changeSummaryProperty” is the name of a property whose Type is ChangeSummaryType MUST return the same ChangeSummary object as DataObject.getChangeSummary(). COR04020203 When an SDO implementation creates a DataObject containing a ChangeSummary, the logging state MUST be off. COR04020204 An SDO implementation MUST raise an error if a Type is defined that contains more than one property with type ChangeSummaryType. [COR04020204] COR04020205 An SDO implementation MUST raise an error if a Type is defined with a property with type ChangeSummaryType that has many=true and readOnly=false. COR04020206 The scope of ChangeSummaries never overlap. An SDO implementation MUST raise an error if a DataObject has a property of type ChangeSummary is directly or indirectly contained or otherwised referenced by any other DataObject that has a property of type ChangeSummary. COR04020301 An SDO implementation MUST include in the ChangeSummary.changedObjects list all DataObjects that were in the ChangeSummary scope when logging was activated but are not in the scope when logging was deactivated and which are not themselves contained by a deleted DataObject; the implementation MUST return true when such an object is passed to ChangeSummary.isDeleted. COR04020302 An SDO implementation MUST include in the ChangeSummary.changedObjects list all DataObjects that were not in the ChangeSummary scope when logging was activated, but are in scope when logging was deactivated (or when ChangeSummary.getChangedObjects() was called, if logging is still active) and which are not themselves contained by a created DataObject; the implementation MUST return true when such an object is passed to ChangeSummary.isCreated. COR04020303 An SDO implementation MUST include in the ChangeSummary.changedObjects list all DataObjects that remained in the ChangeSummary scope and whose property values changed during the time that logging was activated; the implementation MUST return true when such an object is passed to ChangeSummary.isModified. COR04020304 The changeObject MUST NOT contain any objects other than those meeting the defined criteria. COR04020401 If the only change a DataObject is to the contents of its orphanHolder properties, the object itself MUST NOT be contained in the ChangeSummary as a modified. COR04020402 An SDO implementation MUST NOT include OrphanHolder properties in the getOldValues or getOldSequence lists. COR04020403 If an orphan DataObject is referenced from within the scope of a ChangeSummary, and if an object with a matching orphanHolder property is contained, either directly or indirectly, then the object is in scope of the ChangeSummary then when the change summary root is serialized using XMLHelper.save, an SDO implementation MUST serialze the orphan DataObject as being “contained” by the orphanHolder property. 391SDO Core Specification Version 3.0 16 December 2008 392Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 131 of 141 COR04020404 An SDO implemenation MAY ignore orphanHolder properties defined on DataObjects that themselves are orphans, or that are contained by orphans. COR04020405 An SDO implemenation MAY ignore ChangeSummary defined on DataObjects that themselves are orphans, or that are contained by orphans. COR04020501 For a deleted DataObject, the old values List MUST contain all the properties of the DataObject. COR04020502 For a DataObject that has been modified, an SDO implementation MUST include only the modified properties in the the old values List. COR04020503 For a DataObject that has not been deleted or modified, getOldValues() MUST return an empty List. COR04020601 If DataObject.getSequence() returns null then getOldSequence(DataObject dataObject) MUST return null. COR04030301 An SDO implementation MUST provide access to the properties that appear in a Sequence through the DataObject API. COR04030302 If DataObject APIs are used to set a Property that was already set an SDO implemenatation MUST do so “in-place”. COR04030303 If a value is added to a many-valued Property as the item with index “i” (rather than as the last item), then an SDO implemenation MUST insert the new value in the Sequence right before the value corresponding to the item “i+1” of that many-valued Property. COR04030304 When the Sequence APIs are used to reorder a many-valued property, getList() invoked on that property MUST have a relative order of values that reflects these changes. COR04030306 If DataObject APIs are used to modify properties of a sequenced DataObject, then setting a Property previously unset or adding a value as the last item of a many-valued Property an SDO implementation MAY add the value at the end of the Sequence or, if possible,in a more suitable position in the Sequence (according to the XSD definition of the sequenced DataObject's Type). COR04040401 An SDO implementations MUST not have a more restrictive set of conditions for compatibility than defined by this specification, it MAY loosen these conditions. COR04040601 The actual type of a wrapper DataObject is implementation dependent, but MUST extend the SDO type {http://docs.oasis- open.org/ns/opencsa/sdo/200812}DataTypeWrapper COR04040801 An SDO implemenation MUST support access to open content using the getInstanceProperties() and get(Property) methods on the objects COR04040802 If provided by an implementation, such facets SHOULD appear in the list returned by COR04050301 getInstanceProperties(). COR04050100 An SDO implemenation MUST raise an error if defining a Property would result in a 1 duplicate name or the name would duplicate an alias of an existing Property. COR04045020 An SDO implemenation MUST raise an error if defining a Property would result in a 02 duplicate alias or an alias would duplicate the name of an existing Property. COR04050301 If the key type is not explicitly set, and SDO implemenation MUST derive its default COR04050301C value according to the algorithm: OR04050301C If there is exactly one key property, and its type is a DataType, then the key OR04050301C 394SDO Core Specification Version 3.0 16 December 2008 395Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 132 of 141 type is the type of the key property. If there is exactly one key property and its type is not a DataType, then the key type is the key type of the key property’s type. COR04050302 An SDO implementation MUST check that the specified key type matches the defined key properties, and raise an error if the key type and the key properties do not match. COR04060001 An SDO implementation MUST ensure that every DataObject in a data graph, that is, in the transitive closure reachable from some root node, is associated with the same HelperContext. COR04070101 An SDO implementation MUST create DataFactory instances that use the TypeHelper associated with the same HelperContext as the DatFactory instance. COR04070201 The created object's getType() MUST return the Type used in the call to DataFactory.create(), and the Type.isInstance() MUST return true for the created object. COR04070202 When instantiating a Type that has an InstanceClass then the object returned from the create MUST instantiate it. COR04070203 An SDO implementation MUST create the DataObject associated with a new ChangeSummary instance with change logging turned off. COR04080201 An SDO implementations MUST allow the “sdotype” argument in the property.set(“type”, sdotype) method, and in all setters that take Types as arguments, to be either an instance of commonj.sdo.Type or a DataObject of type {http://docs.oasis- open.org/ns/opencsa/sdo/200812}Type. COR04080202 An SDO implementation MUST define all directly or indirectly referenced Types, and their properties when the referencing Type is defined (e.g., through a call to TypeHelper.define()). COR04080401 Open content properties MUST be available by calling XSDHelper.getGlobalProperty(uri, propertyName, true), just as XSD global properties created by XSDHelper.define() MUST be available by calling TypeHelper.getOpenContentProperty(). COR04080501 If a type with the same name and URI already exists, this operation MUST NOT modify the existing type. COR04080502 If some of the types in the list passed to TypeHelper.define have the same name/URI COR04080401 combination as types that already exist, the SDO implementation MUST NOT redefine the existing types and the corresponding entries in the List returned MUST have references to the already existing types. COR04090201 The copyShallow() method MUST create a DataObject with the same values as the source dataObject for each Property of the source DataObject where property.type.dataType is true, including read-only properties, and for each Property of the Data Object were property.type.dataType is false, that property MUST be unset in the new DataObject. COR04090204 If a ChangeSummary is part of the source DataObject then copyShallow() MUST create a new, empty ChangeSummary that is associated with the new DataObject and the logging state of the new ChangeSummary MUST BE the same as the source ChangeSummary. COR04090301 The copy() method MUST create a DataObject with the same values as in the shallow copy for each Property of the source DataObject where property.getType().isDataType() is true. 397SDO Core Specification Version 3.0 16 December 2008 398Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 133 of 141 COR04090302 The copy() method MUST make a deep copy of the value for each containment Property of the source DatObject where the value is a DataObject. COR04090303 The copy() method MUST NOT copy a value that is a reference to a DataObject outside the copy tree for any bidirectional property of the source DataObject. COR04090304 If a unidirectional property’s value is a reference to a DataObject outside the copy, then the the copy() method MUST set the value in the new DataObject to reference the same DataObject as the source DataObject. COR04090305 If a ChangeSummary is part of the copy tree, the copy() method MUST create a new ChangeSummary with contents that correspond to the values in the source ChangeSummary, with the copied ChangeSummary referring to objects in the copied DataObject tree and logging state the same as the source Change Summary. COR04110301 An SDO Implementaion MUST generate an xsi:type annotation in the serialization of DataObjects whenever the Type of the DataObject is not the same as the type of the element, e.g., when polymorphism occurs in the object model, but there are no corresponding substitution group defined in the XSD. COR04110302 When marshalling an element having an xsi:type declaration into a DataObject, the SDO implementation MUST create an DataObject with the indicated type COR04110303 XSD cannot support multiple inheritance, but an SDO implementation MUST be able to marshal and unmarshal between SDO objects that use multiple inheritance and well- formed XML documents. COR04110401 When processing COR04140402 When projecting from a key to a DataObject, then all usages of the same key value 400SDO Core Specification Version 3.0 16 December 2008 401Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 134 of 141 MUST resolve to the same DataObject. COR04140403 The projection operation MUST create a single DataObject for each key value. COR04140404 The created DataObject MUST have all default values, except for its key properties, which MUST be set to match the key. COR05010001 Every TypeHelper MUST define {http://docs.oasis- open.org/ns/opencsa/sdo/xml/200812}Type according to the table in section 5.1 COR05010002 Once the type has been defined, an SDO implementation MUST make the values used in the defining DataObject available through the the accessor methods in the Type API. COR05010003 An SDO implementation MUST expose any open content properties set on the DataObject used to define a Type or Propertiy through the getInstanceProperties() and get() methods on the corresponding commonj.sdo.Type and commonj.sdo.Property objects. COR06000001 The predefined SDO Types described in this chapter MUST be available from TypeHelper.getType(TypeHelper.SDO_URI, String typeName). COR06010001 An SDO Implementation MUST convert between each of the defined DataTypes and its string representation according to the patterns described in the table. COR06010101 An SDO implementation MUST convert Bytes to String by converting each byte into the hexadecimal two-digit equivalent using the characters [0-9A-F]. COR06010201 An SDO implementation MUST convert Strings to Bytes by converting each pair of characters from the hexadecimal two-digit equivalent using the characters [0-9A-Fa-f]. COR06010301 An SDO implementation MUST convert Character to String by mapping the Character value to a String of length 1, whose first (and only) character is that Character value. COR06010302 The character with the Unicode codepoint '0' MUST map to the empty String. COR06020001 Attempts to instantiate abstract Types MUST throw IllegalArgumentException from all create() methods. COR07010001 An SDO implemention MUST NOT generate names for anonymous types that hide a globally defined type with the same name. COR07030001 The tables sections 7.3 and 7.4 MUST be implemented by all SDO implementations. COR07030002 XSD generation MUST include the “many” attribute on any element serialized inside a repeating model group, where the corresponding property has Property.isMany = false. COR07030003 Orphan holder properties MUST NOT BE not visible in Type.getProperties() or DataObject.getInstanceProperties(). COR07030201 When deriving Simple Types by restriction, the base Type for the SDO Type MUST BE the SDO Type thap maps to the XSD SimpleType restriction base. COR07030202 When the XSD type is integer, positiveInteger, negativeInteger, nonPositiveInteger, nonNegativeInteger, long, or unsignedLong, and there are facets (minInclusive, maxInclusive, minExclusive, maxExclusive, totalDigits or enumeration) constraining the range to be within the range of int, then implementation type MUST be int. COR07040201 If a ComplexType has content with two elements that have the same local name and the same targetNamespace, whether through declaration, extension, substitution, groups, or 403SDO Core Specification Version 3.0 16 December 2008 404Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 135 of 141 other means, the duplication MUST BE handled as described. COR07040202 If schema extension is used, the base type MAY be modified with sdox:sequence="true". Elements with name conflicts introduced in extensions require that the property in the extended base type MUST BE made many=true. COR07040203 Implementations MUST interpret instance documents containing a [CONCRETE_NAME] tag as part of a type [TYPE] element as setting (or adding, in the case of multi-valued properties) the value of property [BASE_NAME]. COR07040204 When marshalling a DataObject to XML, an SDO implementation MUST use the [CONCRETE_NAME] that provides the best match to the DataObject’s type. COR07050001 An SDO implementation MUST read simple values whose type cannot be determined the value is read as a String. COR07050101 When an XML document is loaded, a value of type xsd:QName, an SDO implementation MUST convert it into an SDO URI with a value of: namespace name + # + local part where + indicates string concatenation. COR07070001 The order of the entries in the Sequence MUST BE the same as the order of XML elements. COR07080001 An implementation of SDO MUST follow the guidelines when mapping XSD to SDO: COR07090001 The mappings here are the base mappings. Vendors MAY extend the mappings provided that client programs developed against these mappings continue to run. COR07110001 To represent the rootObject of the document, an SDO implementation MUST BE an open, sequenced, mixed data object. COR07110002 If an attribute or element contains a URI, the implementation MUST attempt to locate the property definition as if by calling XSDHelper.getGlobalProperty() using the specified URI and property name. COR07110003 Attributes for which no meta-information is available MUST BE interpreted as open content String properties, where the name of the property is the local name of the attribute. COR07110004 Elements for which no meta-information is available MUST BE interpreted as open content properties, where the name of the property is the local name of the element. The property MUST always have containment=true. COR07110005 If multiple instance of the same element occur within a containing element instance, the open content property corresponding to the element MUST have isMany=true. Otherwise an implementation MAY create the property with isMany=false. COR07110006 If an element contains an xsi:type attribute, the value MUST BE used to determine the type of the value. If no xsi:type attribute is present and the content is simple, then the value's type will be implementation dependent. If the content is complex, the value MUST BE interpreted as an open, sequenced, mixed type (similar to the type of the document's root element); an implementation MUST provide a single Type to handle all such cases. Implementations MAY use wrapper objects (see 7.10: Corner Cases, point 4) to contain simple values. COR07110007 An implementation MUST define the property type such that all the values of the property conform, and the type information is available. If the property is single valued, or if the type of all elements in a multi-valued property agree, an implementation MAY 406SDO Core Specification Version 3.0 16 December 2008 407Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 136 of 141 create the property of the value type itself. However, implementations MAY, instead, choose to create the property with a more general type, such as {http://docs.oasis- open.org/ns/opencsa/sdo/200812}Object or {http://docs.oasis- open.org/ns/opencsa/sdo/200812}DataObject. Applications SHOULD use meta-data introspection to determine the contents and structure of the received data objects. COR07110008 Any properties created in the previous steps are local to their containing DataObject, i.e. they MUST NOT not available via the TypeHelper.getOpenContentProperty() API. COR08000001 An SDO implementation MUST generate an XSD from a Type such that the XSD type round trips back to an SDO Type that is identical to the original Type. COR08000004 An SDO implementation MAY include additional declarations as long as documents that validate with the generated schema also validate with the customized schema. COR08000002 An SDO implementation MUST generate the Schema element with a target namespace determined by the URI of the Types that will be defined in the schema COR08000003 If xsdType is set to the XSD type matching the target type’s keyType, then an SDO implementation MUST render the reference using the value of the key. COR08000005 For each Type that is a dataType, type.dataType==true, an SDO implementation MUST generate an XSD SimpleType as specified. COR08000006 For each Type that is not a dataType, an SDO implementation MUST generate an XSD ComplexType and a global element. The ComplexType is based on the specified pattern. COR08000007 If the property is bidirectional and the opposite property has containment=true, an SDO implementation MUST generate neither an element nor an attribute; otherwise, an SDO implementation MUST generate an attribute. COR08000008 When an SDO implementation generates an element it MUST base the element on the specified pattern. COR08000009 When an SDO implementation generates an attribute it MUST base the attribute on the specified pattern. COR08030001 If the key type is a DataType and the reference is single-valued, the reference an SDO implementation MUST, by default, render it as an attribute. COR08030002 An SDO implementation MUST render complex keys and multivalued references as elements. COR08030003 Whenever a non-containment reference is redenderd in schema, whether XPath or keys are used, and regardless of whether the reference is rendered as a attribute or element, an SDO implementation MUST also annotate the attribute or element with “sdox:propertyType”. COR09000001 An SDO implementation MUST do name matching based on the XML representation (i.e., the XML element or attribute names), including distinguishing between attributes and elements based on whether or not the local name was preceeded by a “@” sign. COR09000002 The zero-based dot syntax to specify the index (e.g., "departments.0"), and @ sign (without meaning) to precede a property in the syntax have been deprecated in SDO 3.0, but SDO implementations MAY allow them for backwards compatibility. COR10000001 An SDO implementation MUST render the ChangeSummary element if either of the conditions apply: 409SDO Core Specification Version 3.0 16 December 2008 410Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 137 of 141 Changes have been logged (getChangedDataObjects().size() > 0). No changes have been logged but isLogging() is true at the time of serialization. COR10000002 When deserializing an empty ChangeSummary element, an SDO implemention MUST create a changeSummary object having logging==true. COR10010001 When serializing a ChangeSummary, an SDO implementation MUST fill the @create attribute with references to every DataObject in the ChangeSummary’s getChangedObjects() list for which isCreated returns true. COR10010002 Similarly, when serializing a ChangeSummary, an SDO implementation MUST fill the @delete attribute with references to every DataObject in the ChangeSummary’s getChangedObjects() list for which isDeleted returns true. COR10010003 Deleted orphans MUST be serialized as top level elements in the changeSummary. COR10020001 When serializing references to DataObjects as a value of an sdo:ref attribute, or included in ChangeSummary’s create or delete attributes, an SDO implementation MUST use IDREFs when IDs are available, and XPath expressions otherwise. COR10030001 If the Type is sequenced, then the serialized change summary MUST contain the complete sequence of elements and intermixed text as it existed at the point that logging was started, with elements that are still represented in the final document containing only an sdo:ref attribute pointing to that respective element in the serialized graph. COR10040001 Where changes made were only to data type properties of a data object, an SDO implementation MUST include a copy of data object in the ChangeSummary element, but the copy MUST contain only the properties that have changed, showing their old values. COR10040002 If a multivalued property was modifed, an SDO implementation MUST reproduce the entire list. COR10040003 [If the property’s type is not a dataType, an SDO implementation MUST render unaltered elements using the sdo:ref attribute to indicate the corresponding object in the final document. COR10040004 If an old value is not present in the ChangeSummary, it is assumed not to have changed. If a property was not set when logging began, an SDO implementation MUST represent the old state in the ChangeSummary using an “unset” attribute. COR10040005 If the deleted object was formerly contained, an SDO implementation MUST serialize a deep copy of the object in-place, as part of the modification to the parent object. 3946 412SDO Core Specification Version 3.0 16 December 2008 413Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 138 of 141 3947C. Acknowledgements 3948The following individuals have participated in the creation of this specification and are gratefully 3949acknowledged: 3950Participants: 3951We would like to thank Matthew Adams , Joshua Auerbach (IBM), David Bau, John Beatty, David Booz 3952(IBM), Adam Bosworth, Graham Barber (IBM), Kevin Bauer (IBM), Jerome Beau (DataDirect 3953Technologies), Michael Beisiegel (IBM), Henning Blohm (SAP), Michael Carey, Graham Charters (IBM), 3954Gang Chen (IBM), Shane Claussen (IBM), Ed Cobb, Brent Daniel (IBM), George DeCandio (IBM), Jean- 3955Sebastien Delfino (IBM), Scott Dietzen, Jean-Jacques Dubray (SAP), Mike Edwards (IBM), Emma 3956Eldergill (IBM), Raymond Ellersick (IBM), Don Ferguson (IBM), Christopher Ferris (IBM), Paul Fremantle, 3957Kelvin Goodson (IBM), John Green (IBM), Andy Grove (RogueWave Software), Omar Halaseh (Oracle), 3958Larry Harris (Oracle), Laurent Hasson (IBM), Eric Herness (IBM), Rob High (IBM), Michael Ho (Sybase), 3959Steve Holbrook (IBM), Sridhar Iyengar (IBM), Anish Karmarkar (Oracle), Jagan Karuturi (IBM), Dan 3960Kearns, Stephen J Kinder (IBM), Regis Le Brettevillois (DataDirect Technologies), Elena Litani (IBM), 3961Matthew Lovett (IBM), Angel Luis Diaz (IBM), Fuhwei Lwo (IBM), Ed Merks (IBM), Denny McKinney 3962(Oracle), Adam Messinger, Martin Nally (IBM), Simon Nash (IBM), Peter Niblett (IBM), Karla Norsworthy 3963(IBM), Howard Operowsky (IBM), Rahul Patel (Oracle), Bertrand Portier (IBM), Barbara Price (IBM), Jim 3964Rhyne (IBM), Fabio Riccardi, Mike Rowley, Timo Salo (IBM), Edward Slattery (IBM), Denise Smith 3965(Oracle), Shaun Smith (Oracle), Dave Steinberg (IBM), Andrew Spyker (IBM), James Taylor, Sachin 3966Thatte (Oracle), Arnaud Thiefaine, Colin Thorne (IBM), Greg Truty (IBM), Celia Tung (IBM), Lionel Villard 3967(IBM), Seth White (BEA), Kevin Williams (IBM), Geoffrey Winn (IBM), Helena Yan (Oracle), Wing Yew 3968Poon (Oracle), and George Zagelow (IBM). 3969 415SDO Core Specification Version 3.0 16 December 2008 416Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 139 of 141 3970D. Non-Normative Text 418SDO Core Specification Version 3.0 16 December 2008 419Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 140 of 141 3971E. Revision History 3972[optional; should not be included in OASIS Standards] 3973 Revision Date Editor Changes Made CD1-Rev2 29.9.2009 Ron Barack Resolved Issues: 44, 122, 164 CD1–Rev15 20.7.2009 Ron Barack First set of resolutions for CD 2 Resolved Issues: 22, 56, 139, 141, 150, 154, 158, 160, 161, 162 4 16.12.2008 Frank Budinsky Committee Draft 1 3 12.12.2008 Frank Budinsky Resolved issues: 1,2,5,66,67,71,82,83,118, 119,124,125,129,133,135,145 2 26.11.2008 Frank Budinsky Merge 2.1.1 changes 1 2.7.2008 Bryan Aupperle Refactor 3974 3975 421SDO Core Specification Version 3.0 16 December 2008 422Copyright © OASIS® 2003, 2008. All Rights Reserved. Page 141 of 141