Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/UserGuide/SDO/Introduction to EclipseLink SDO (ELUG)"
m (→Using DataObject) |
m |
||
Line 13: | Line 13: | ||
A <tt>Type</tt> can have supertypes, which corresponds to the EclipseLink concept of inheritance policy (see [[Introduction_to_Descriptors_%28ELUG%29#Descriptor_API | Inheritance Policy in Descriptor API]]). | A <tt>Type</tt> can have supertypes, which corresponds to the EclipseLink concept of inheritance policy (see [[Introduction_to_Descriptors_%28ELUG%29#Descriptor_API | Inheritance Policy in Descriptor API]]). | ||
− | For more information, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Type.html Type | + | For more information, see <tt>[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Type.html Type]</tt> API. |
====What You May Need to Know About Open Sequenced Type==== | ====What You May Need to Know About Open Sequenced Type==== | ||
− | For information, see <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/dataobjects/OpenSequencedType.html OpenSequencedType]</tt>. | + | For information, see EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/dataobjects/OpenSequencedType.html OpenSequencedType]</tt> API. |
====What You May Need to Know About DataObjectType for Data Types==== | ====What You May Need to Know About DataObjectType for Data Types==== | ||
− | For information, see <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/types/SDODataObjectType.html SDODataObjectType]</tt>. | + | For information, see EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/types/SDODataObjectType.html SDODataObjectType]</tt> API. |
+ | |||
===Using Property=== | ===Using Property=== | ||
SDO <tt>Property</tt> acts similarly to a property in Java and provides much of the same metadata as the Java Reflection API provides for Java fields or methods. | SDO <tt>Property</tt> acts similarly to a property in Java and provides much of the same metadata as the Java Reflection API provides for Java fields or methods. | ||
− | In EclipseLink, a <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOProperty.html SDOProperty]</tt> wraps an [[Introduction_to_XML_Mappings_%28ELUG%29 | object-XML mapping]] in the following | + | In EclipseLink, a <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOProperty.html SDOProperty]</tt> wraps an [[Introduction_to_XML_Mappings_%28ELUG%29 | object-XML mapping]] in the following manner: |
− | * <tt>DataType=true + isMany=false</tt> | + | * <tt>DataType=true + isMany=false</tt> - corresponds to EclipseLink [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Direct_Mapping | OXM direct mappings]] and [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Binary_Data_Mapping | OXM binary mappings]]. |
− | + | * <tt>DataType=true + isMany=true</tt> - corresponds to EclipseLink [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Composite_Direct_Collection_Mapping | OXM direct collection mappings]] and [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Binary_Data_Collection_Mapping | OXM binary collection mappings]]. | |
− | * <tt>DataType=true + isMany=true</tt> | + | * <tt>DataType=false + isMany=false + containment=true</tt> - corresponds to EclipseLink [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Composite_Object_Mapping | OXM composite object mappings]]. |
− | + | * <tt>DataType=false + isMany=true + containment=true</tt> - corresponds to EclipseLink [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Composite_Collection_Mapping | OXM composite collection mappings]]. | |
− | * <tt>DataType=false + isMany=false + containment=true</tt> | + | * <tt>DataType=false + isMany=false + containment=false</tt> - corresponds to EclipseLink [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Object_Reference_Mapping | OXM reference mappings]]. |
− | + | * <tt>DataType=false + isMany=true + containment=false</tt> - corresponds to EclipseLink [[Introduction_to_XML_Mappings_%28ELUG%29#XML_Collection_Reference_Mapping | OXM collection reference mappings]]. | |
− | * <tt>DataType=false + isMany=true + containment=true</tt> | + | |
− | + | For more information, see <tt>[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/Property.html Property]</tt> API. | |
− | * <tt>DataType=false + isMany=false + containment=false</tt> | + | |
− | + | ||
− | * <tt>DataType=false + isMany=true + containment=false</tt> | + | |
− | + | ||
− | |||
===Defining Metadata=== | ===Defining Metadata=== | ||
− | You can use the following | + | You can use the following helper classes to define SDO metadata: |
− | * <tt>[[#How to Define Metadata with | + | * <tt>[[#How to Define Metadata with XSDHelper| XSDHelper]]</tt> |
− | * <tt>[[#How to Define Metadata with | + | * <tt>[[#How to Define Metadata with TypeHelper| TypeHelper]]</tt> |
Information pending: modifying and accessing the underlying EclipseLink metadata | Information pending: modifying and accessing the underlying EclipseLink metadata | ||
− | |||
− | |||
− | |||
− | |||
− | ====How to Define Metadata with | + | ====How to Define Metadata with XSDHelper==== |
− | You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/ | + | You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XSDHelper.html XSDHelper]</tt> to do the following: |
* Define SDO metadata, where SDO metadata is derived from XML schemas. | * Define SDO metadata, where SDO metadata is derived from XML schemas. | ||
* Generate XML schemas from SDO types. | * Generate XML schemas from SDO types. | ||
− | You can customize metadata using the following annotations that you apply to the XML schema: | + | You can customize metadata by using the following annotations that you apply to the XML schema: |
* Standard annotations: | * Standard annotations: | ||
** Information pending | ** Information pending | ||
Line 70: | Line 62: | ||
You can also use various APIs to determine the XML representation about the SDO metadata. | You can also use various APIs to determine the XML representation about the SDO metadata. | ||
+ | |||
+ | For more information, see EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOXSDHelper.html SDOXSDHelper]</tt> API. | ||
− | ====How to Define Metadata with EclipseLink | + | ====How to Define Metadata with EclipseLink TypeHelper==== |
− | You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/ | + | You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/TypeHelper.html TypeHelper]</tt> to do the following: |
* Look up SDO metadata. | * Look up SDO metadata. | ||
− | * Programmatically define SDO metadata (note that this is not the typical usage for the <tt> | + | * Programmatically define SDO metadata (note that this is not the typical usage for the <tt>TypeHelper</tt>). |
+ | |||
+ | For more information, see EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOTypeHelper.html SDOTypeHelper]</tt> API. | ||
+ | |||
+ | |||
+ | |||
==Using Data== | ==Using Data== | ||
− | + | Use the following SDO classes to work with data: | |
* [[#Using DataObject | XSDHelper]] | * [[#Using DataObject | XSDHelper]] | ||
* [[#Using XMLDocument | XMLDocument]] | * [[#Using XMLDocument | XMLDocument]] | ||
Line 95: | Line 94: | ||
Note that you can use the EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/extension/XPathHelper.html XPathHelper]</tt> to query data objects using an XPath expression. | Note that you can use the EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/extension/XPathHelper.html XPathHelper]</tt> to query data objects using an XPath expression. | ||
− | For more information, see EclipseLink [http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDODataObject.html SDODataObject | + | For more information, see EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDODataObject.html SDODataObject]</tt> API. |
Line 104: | Line 103: | ||
Information pending. | Information pending. | ||
+ | |||
+ | |||
===Using XMLDocument=== | ===Using XMLDocument=== | ||
When you marshall (save) a <tt>DataObject</tt> to XML, or unmarshall an XML document into objects, the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLDocument.html XMLDocument]</tt> class contains information about the root of the XML document. | When you marshall (save) a <tt>DataObject</tt> to XML, or unmarshall an XML document into objects, the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLDocument.html XMLDocument]</tt> class contains information about the root of the XML document. | ||
− | For more information, see EclipseLink [http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOXMLDocument.html SDOXMLDocument | + | For more information, see EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOXMLDocument.html SDOXMLDocument]</tt> API. |
Line 118: | Line 119: | ||
Note that the <tt>[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataGraph.html DataGraph]</tt> class has been deprecated. | Note that the <tt>[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.emf.ecore.sdo.doc/references/javadoc/commonj/sdo/DataGraph.html DataGraph]</tt> class has been deprecated. | ||
− | For more information, see the following EclipseLink | + | For more information, see the following EclipseLink APIs: |
* <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOSequence.html SDOSequence]</tt> | * <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOSequence.html SDOSequence]</tt> | ||
* <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOChangeSummary.html SDOChangeSummary]</tt> | * <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/SDOChangeSummary.html SDOChangeSummary]</tt> |
Revision as of 15:04, 28 April 2009
This section introduces EclipseLink implementation of Service Data Objects (SDO) specification, as well as provides information on how you can use it in your application development.
Contents
Using SDO Metadata
SDO metadata is represented as Type and Property objects. You define the metadata at run time either programmatically, or from an XML schema.
Using Type
SDO Type acts similarly to a Class in Java, and provides much of the same metadata as the Java Reflection API provides for Java classes.
In EclipseLink, a SDOType wraps an object-XML mapping (OXM) descriptor.
A Type can have supertypes, which corresponds to the EclipseLink concept of inheritance policy (see Inheritance Policy in Descriptor API).
For more information, see Type API.
What You May Need to Know About Open Sequenced Type
For information, see EclipseLink OpenSequencedType API.
What You May Need to Know About DataObjectType for Data Types
For information, see EclipseLink SDODataObjectType API.
Using Property
SDO Property acts similarly to a property in Java and provides much of the same metadata as the Java Reflection API provides for Java fields or methods.
In EclipseLink, a SDOProperty wraps an object-XML mapping in the following manner:
- DataType=true + isMany=false - corresponds to EclipseLink OXM direct mappings and OXM binary mappings.
- DataType=true + isMany=true - corresponds to EclipseLink OXM direct collection mappings and OXM binary collection mappings.
- DataType=false + isMany=false + containment=true - corresponds to EclipseLink OXM composite object mappings.
- DataType=false + isMany=true + containment=true - corresponds to EclipseLink OXM composite collection mappings.
- DataType=false + isMany=false + containment=false - corresponds to EclipseLink OXM reference mappings.
- DataType=false + isMany=true + containment=false - corresponds to EclipseLink OXM collection reference mappings.
For more information, see Property API.
Defining Metadata
You can use the following helper classes to define SDO metadata:
Information pending: modifying and accessing the underlying EclipseLink metadata
How to Define Metadata with XSDHelper
You use the XSDHelper to do the following:
- Define SDO metadata, where SDO metadata is derived from XML schemas.
- Generate XML schemas from SDO types.
You can customize metadata by using the following annotations that you apply to the XML schema:
- Standard annotations:
- Information pending
- EclipseLink annotations:
- Information pending
You can also use various APIs to determine the XML representation about the SDO metadata.
For more information, see EclipseLink SDOXSDHelper API.
How to Define Metadata with EclipseLink TypeHelper
You use the TypeHelper to do the following:
- Look up SDO metadata.
- Programmatically define SDO metadata (note that this is not the typical usage for the TypeHelper).
For more information, see EclipseLink SDOTypeHelper API.
Using Data
Use the following SDO classes to work with data:
Using DataObject
A DataObject in SDO corresponds to a Java Object (POJO). To define object-XML mappings, you map the DataObject to XML. You can create your data object as either dynamic (see Dynamic DataObject Examples), or static by applying a type-safe interface to it (see Static DataObject Examples). The DataObject provides an XPath-like (see Mappings and XPath) means of data access. For example, the following code is valid in SDO:
customerDO.getDataObject("contact-info/phone-number[2]");
The standard JAXB, however, would require the following:
customer.getContactInfo().getPhoneNumbers().get(1);
Note that you can use the EclipseLink XPathHelper to query data objects using an XPath expression.
For more information, see EclipseLink SDODataObject API.
What You May Need to Know About Serialization in SDO
SDO has its own Java serialization format. The DataObject implements the Serializable interface.
Information pending.
Using XMLDocument
When you marshall (save) a DataObject to XML, or unmarshall an XML document into objects, the XMLDocument class contains information about the root of the XML document.
For more information, see EclipseLink SDOXMLDocument API.
What You May Need to Know About Sequence, ChangeSummary, and DataGraph
The following SDO classes allow you to obtain additional information about data objects:
- Sequence -- provides a list of properties and their corresponding values.
- ChangeSummary -- records changes to data objects.
Note that the DataGraph class has been deprecated.
For more information, see the following EclipseLink APIs: