Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/SDO/Using EclipseLink SDO (ELUG)"

(What You May Need to Know About Local and Global HelperContext)
m (Using SDO as a Web Service Binding Layer)
 
(6 intermediate revisions by one other user not shown)
Line 43: Line 43:
 
You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataFactory.html DataFactory]</tt> to create disconnected instances of a <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/DataObject.html DataObject]</tt>. That is, the newly created <tt>DataObject</tt> instances have no set properties and no container.
 
You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataFactory.html DataFactory]</tt> to create disconnected instances of a <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/DataObject.html DataObject]</tt>. That is, the newly created <tt>DataObject</tt> instances have no set properties and no container.
  
You can obtain the default <tt>DataFactory</tt> from the <tt>INSTANCE</tt> field or from the <tt>getDataFactory</tt> method of the default <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.
+
You can obtain the global <tt>DataFactory</tt> from the <tt>INSTANCE</tt> field or a DataFactory corresponding to a HelperContext using the <tt>getDataFactory</tt> method on <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.  
 
+
You can also define and retrieve the <tt>HelperContext</tt> from your EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataFactory.html SDODataFactory]</tt>.
+
  
 
For more information, see the following:
 
For more information, see the following:
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataFactory.html SDODataFactory]</tt> API
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataFactory.html SDODataFactory]</tt> API
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#DataFactory_-_Create_DataObjects DataFactory]</tt> examples
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#DataFactory_-_Create_DataObjects DataFactory]</tt> examples
 
 
  
 
===Using XMLHelper===
 
===Using XMLHelper===
 
You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLHelper.html XMLHelper]</tt> to convert XML documents into data objects, and vice versa. The two main operations of the <tt>XMLHelper</tt> are <tt>load</tt> and <tt>save</tt>.
 
You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/XMLHelper.html XMLHelper]</tt> to convert XML documents into data objects, and vice versa. The two main operations of the <tt>XMLHelper</tt> are <tt>load</tt> and <tt>save</tt>.
  
You can obtain the default <tt>XMLHelper</tt> from the <tt>INSTANCE</tt> field or from the <tt>getXMLHelper</tt> method of the default <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.
+
You can obtain the global <tt>XMLHelper</tt> from the <tt>INSTANCE</tt> field or a XMLHelper corresponding to a HelperContext using the <tt>getXMLHelper</tt> method on <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.  
 
+
The EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOXMLHelper.html SDOXMLHelper]</tt> <tt>initializeDescriptor</tt> method allows you to define an [[Introduction_to_XML_Descriptors_%28ELUG%29 | XML descriptor]] for your application.
+
  
 
For more information, see the following:
 
For more information, see the following:
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOXMLHelper.html SDOXMLHelper]</tt> API
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOXMLHelper.html SDOXMLHelper]</tt> API
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#XMLHelper_-_Handle_XML_Data_as_DataObjects XMLHelper]</tt> examples
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#XMLHelper_-_Handle_XML_Data_as_DataObjects XMLHelper]</tt> examples
 
 
  
 
===Using DataHelper===
 
===Using DataHelper===
 
The main purpose of the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataHelper.html DataHelper]</tt> is to enable conversion of values used with data objects between data types.
 
The main purpose of the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataHelper.html DataHelper]</tt> is to enable conversion of values used with data objects between data types.
  
You can obtain the default <tt>DataHelper</tt> from the <tt>INSTANCE</tt> field or from the <tt>getDataHelper</tt> method of the default <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.
+
You can obtain the global <tt>DataHelper</tt> from the <tt>INSTANCE</tt> field or a DataHelper corresponding to a HelperContext using the <tt>getDataHelper</tt> method on <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.  
 
+
You can also define and retrieve the <tt>HelperContext</tt> from your EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataHelper.html SDODataHelper]</tt>.
+
  
 
For more information, see the following:
 
For more information, see the following:
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataHelper.html SDODataHelper]</tt> API
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDODataHelper.html SDODataHelper]</tt> API
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#DataHelper_-_Convert_Simple_Values DataHelper]</tt> examples
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#DataHelper_-_Convert_Simple_Values DataHelper]</tt> examples
 
 
  
 
===Using CopyHelper===
 
===Using CopyHelper===
Line 84: Line 72:
 
* a copy of a tree of <tt>DataObject</tt> instances.
 
* a copy of a tree of <tt>DataObject</tt> instances.
  
You can obtain the default <tt>CopyHelper</tt> from the <tt>INSTANCE</tt> field or from the <tt>getCopyHelper</tt> method of the default <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.
+
You can obtain the global <tt>CopyHelper</tt> from the <tt>INSTANCE</tt> field or a CopyHelper corresponding to a HelperContext using the <tt>getCopyHelper</tt> method on <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.  
 
+
You can also define and retrieve the <tt>HelperContext</tt> from your EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOCopyHelper.html SDOCopyHelper]</tt>.
+
  
 
For more information, see the following:
 
For more information, see the following:
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOCopyHelper.html SDOCopyHelper]</tt> API
 
* EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOCopyHelper.html SDOCopyHelper]</tt> API
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#CopyHelper_-_Create_Copies_of_DataObjects CopyHelper]</tt> examples
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#CopyHelper_-_Create_Copies_of_DataObjects CopyHelper]</tt> examples
 
 
  
 
===Using EqualityHelper===
 
===Using EqualityHelper===
Line 99: Line 83:
 
* whether or not two trees of data objects are equal.
 
* whether or not two trees of data objects are equal.
  
You can obtain the default <tt>EqualityHelper</tt> from the <tt>INSTANCE</tt> field or from the <tt>getEqualityHelper</tt> method of the default <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.
+
You can obtain the global <tt>EqualityHelper</tt> from the <tt>INSTANCE</tt> field or an EqualityHelper corresponding to a HelperContext using the <tt>getEqualityHelper</tt> method on <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/HelperContext.html HelperContext]</tt>.  
 
+
You can also define and retrieve the <tt>HelperContext</tt> from your EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOEqualityHelper.html SDOEqualityHelper]</tt>.
+
  
 
For more information, see the following:
 
For more information, see the following:
Line 107: Line 89:
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#EqualityHelper_-_Compare_DataObjects EqualityHelper]</tt> examples
 
* EclipseLink <tt>[http://wiki.eclipse.org/EclipseLink/Examples/SDO/BasicAPI#EqualityHelper_-_Compare_DataObjects EqualityHelper]</tt> examples
  
==Generating Static SDO Classes at Design Time==
 
If you know the metadata, such as, for example, the XML schema definition or the SQL relational schema, at development time, you can use the code-generating interfaces for data objects. SDO enables static
 
data API code generation from a variety of metamodels, including the following:
 
* XML schema languages;
 
* relational database schemas with queries known at the time of code generation;
 
* Web services, when the message is specified by an XML schema;
 
* JCA connectors;
 
* JMS message formats;
 
* UML models.
 
 
Note that when you use static data APIs, the dynamic data APIs are still available to you.
 
  
Information pending.
 
  
 
==Performing Integration==
 
==Performing Integration==
Line 144: Line 114:
 
  DataObject resultPo = resultEnvelope.getDataObject("Body/purchaseOrder");
 
  DataObject resultPo = resultEnvelope.getDataObject("Body/purchaseOrder");
  
You can also build a Web services client around the <tt>XMLHelper</tt>. For example, in a simple web service
+
You can also build a Web services client around the <tt>XMLHelper</tt>. For example, in a simple Web service
 
client, you could post an input <tt>DataObject</tt> representing an XML document using the <tt>XMLHelper</tt>, and then have the returning XML document returned to the caller as a <tt>DataObject</tt>:
 
client, you could post an input <tt>DataObject</tt> representing an XML document using the <tt>XMLHelper</tt>, and then have the returning XML document returned to the caller as a <tt>DataObject</tt>:
  

Latest revision as of 14:14, 21 May 2009

This section explains where and how you use EclipseLink SDO to customize your application to meet requirements.


Performing Actions on Data Objects at Run Time

Use the following classes to perform actions on your data objects:


For more information, see EclipseLink SDO examples.


Using HelperContext

SDO defines a HelperContext interface. You use it to access related SDO helper classes that let you perform common operations such as reading and writing XML documents, defining SDO types from XML Schema, and so on.

To obtain a default context, call the HelperProvider getDefaultContext method.

You can create the local context provided by EclipseLink as follows:

HelperContext helperContext = new SDOHelperContext();

For more information, see the following:


What You May Need to Know About Local and Global HelperContext

All the helpers that you can retrieve from the INSTANCE fields are the same ones as can be accessed from HelperProvider.

XSDHelper.INSTANCE == HelperProvider.getDefaultContext().getXSDHelper()

In terms of Java serialization, both global and local HelperContexts can be used to serialize DataObjects, but the global HelperContext is always used for deserialization.

Using the EclipseLink SDOHelperContext makeDefaultContext method, you can promote your local context to become the global (default) one.

Using DataFactory

You use the DataFactory to create disconnected instances of a DataObject. That is, the newly created DataObject instances have no set properties and no container.

You can obtain the global DataFactory from the INSTANCE field or a DataFactory corresponding to a HelperContext using the getDataFactory method on HelperContext.

For more information, see the following:

Using XMLHelper

You use the XMLHelper to convert XML documents into data objects, and vice versa. The two main operations of the XMLHelper are load and save.

You can obtain the global XMLHelper from the INSTANCE field or a XMLHelper corresponding to a HelperContext using the getXMLHelper method on HelperContext.

For more information, see the following:

Using DataHelper

The main purpose of the DataHelper is to enable conversion of values used with data objects between data types.

You can obtain the global DataHelper from the INSTANCE field or a DataHelper corresponding to a HelperContext using the getDataHelper method on HelperContext.

For more information, see the following:

Using CopyHelper

You use the CopyHelper to create the following types of copies of data objects:

  • a copy of a DataObject's values with DataType properties;
  • a copy of a tree of DataObject instances.

You can obtain the global CopyHelper from the INSTANCE field or a CopyHelper corresponding to a HelperContext using the getCopyHelper method on HelperContext.

For more information, see the following:

Using EqualityHelper

An EqualityHelper provides methods to compare data objects and let you determine the following:

  • whether or not two DataObject instances have the same values for their DataType properties;
  • whether or not two trees of data objects are equal.

You can obtain the global EqualityHelper from the INSTANCE field or an EqualityHelper corresponding to a HelperContext using the getEqualityHelper method on HelperContext.

For more information, see the following:


Performing Integration

You can integrate your SDO application with the following technologies:

The first step in this integration proccess is to create POJO/SDO bridge.


Integrating SDO with JAXB

For information and examples, see SDO-JAXB Integration with EclipseLink.

Integrating SDO with JPA

For information and examples, see SDO-JPA Integration with EclipseLink.

Using SDO as a Web Service Binding Layer

You can easily invoke a Web service and obtain results in the form of data objects, as the following example shows:

DataObject resultEnvelope = WebService.invoke(po, "http://werbservices.org/purchaseOrder", 
                                              soap, "Envelope");

// Get the purchase order from the result envelope
DataObject resultPo = resultEnvelope.getDataObject("Body/purchaseOrder");

You can also build a Web services client around the XMLHelper. For example, in a simple Web service client, you could post an input DataObject representing an XML document using the XMLHelper, and then have the returning XML document returned to the caller as a DataObject:

public static DataObject invoke(DataObject input, String serviceUri,
                                String rootElementURI, String rootElementName) 
                                throws IOException {
URL address = new URL(serviceUri);
HttpURLConnection connection =
(HttpURLConnection) address.openConnection();
if (input != null) {
   connection.setRequestMethod("POST");
   connection.setDoOutput(true);
   connection.addRequestProperty("Content-Type", "text/xml; charset=utf-8");
   OutputStream os = connection.getOutputStream();
   // Add the XML document to the request
   XMLHelper.INSTANCE.save(input, rootElementURI, rootElementName, os);
   os.flush();
}
// invoke the service
connection.connect();
int code = connection.getResponseCode();
if (code != HttpURLConnection.HTTP_OK) {
   throw new IOException("HTTP "+code+" "+connection.getResponseMessage());
}
InputStream is = connection.getInputStream();
// Return the root DataObject from the web service response
DataObject output = XMLHelper.INSTANCE.load(is).getRootObject();
return output;
}


How to Use Web Service Attachments

Information pending

Executing XPath with XML

Many of the accessor methods for data objects make use of a String parameter that provides the path that identifies the property to which the method applies.

The XPath expression is an augmented subset of XPath with the additional ability to access data using 0 as a base index. You specify the path using the following syntax:

path ::= (scheme ':')? '/'? (step '/')* step
scheme ::= [^:]+
step ::= '@'? property
    | property '[' index_from_1 ']'
    | property '.' index_from_0
    | reference '[' attribute '=' value ']'
    | ".."
property ::= NCName ;; may be simple or complex type
attribute ::= NCName ;; must be simple type
reference :: NCName ;; must be DataObject type
index_from_0 ::= Digits
index_from_1 ::= NotZero (Digits)?
value ::= Literal
    | Number
    | Boolean
Literal ::= '"' [^"]* '"'
    | "'" [^']* "'"
Number ::= Digits ('.' Digits?)?
    | '.' Digits
Boolean ::= true
    | false
NotZero ::= [1-9]
Digits ::= [0-9]+
;; leading '/' begins at the root
;; ".." is the containing DataObject, using containment properties
;; Only the last step have an attribute as the property

Note that properties are always matched by name independent of their XML representation.

The following example shows how to construct an XPath that you can use to access a DataObject contained in another DataObject is to specify the index of the contained DataObject within the appropriate property:

DataObject department = company.getDataObject("departments.0");

Another way to access a contained DataObject is to identify that object by specifying the value of one of the attributes of that object. For example:

DataObject employee = department.getDataObject("employees[SN='E0002']");

You can also use XPath expressions to set or unset values of properties, including multivalued properties. Note that each step of the path before the last must return a single DataObject. When the property is a Sequence, the values returned are those of the getValue method.



Copyright Statement