====What You May Need to Know About Local and Global HelperContext====

====What You May Need to Know About Local and Global HelperContext====

−

Using the EclipseLink <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOHelperContext.html SDOHelperContext]</tt> <ttmakeDefaultContext<tt> method, you can promote your local context to become the global (default) one.

+

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

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 <tt>[http://www.eclipse.org/eclipselink/api/1.1/org/eclipse/persistence/sdo/helper/SDOHelperContext.html SDOHelperContext]</tt> <tt>makeDefaultContext</tt> method, you can promote your local context to become the global (default) one.

===Using DataFactory===

===Using DataFactory===

−

You use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/DataFactory.html DataFactory]</tt> to create disconnected instances of the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/DataObject.html DataObject]</tt>.

+

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 <tt>DataFactory</tt> from the <tt>HelperContext</tt>, and vice versa.

+

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 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 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 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 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 use the <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/CopyHelper.html CopyHelper]</tt> to create the following types of copies of data objects:

+

* a copy of a <tt>DataObject</tt>'s values with <tt>DataType</tt> properties;

+

* a copy of a tree of <tt>DataObject</tt> instances.

+

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>.

An <tt>[http://www.eclipse.org/eclipselink/api/1.1/commonj/sdo/helper/EqualityHelper.html EqualityHelper]</tt> provides methods to compare data objects and let you determine the following:

+

* whether or not two <tt>DataObject</tt> instances have the same values for their <tt>DataType</tt> properties;

+

* whether or not two trees of data objects are equal.

−

==Generating Static SDO Classes at Design Time==

+

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>.

Many of the accessor methods for data objects make use of a <tt>String</tt> 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:

−

==Executing XPath with XML==

+

path ::= (scheme ':')? '/'? (step '/')* step

−

Information pending

+

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 <tt>DataObject</tt> contained in another <tt>DataObject</tt> is to specify the index of the contained <tt>DataObject</tt> within the appropriate property:

+

+

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

+

+

Another way to access a contained <tt>DataObject</tt> is to identify that object by specifying the

Performing Actions on Data Objects at Run Time

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 HelperProvidergetDefaultContext method.

Integrating SDO with JPA

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:

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:

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.