Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/SDO/JAXB"

(→‎Define the SDO Metadata)
(→‎Overview)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
==Overview==
 
==Overview==
  
−
The JAXBHelperContext is a bridge between POJOs and SDO DataObjects.  The bridge is based on their corresponding XML representations.  For the POJOs the XML representation is specified using JAXB annotations or object-to-XML mappings.
+
The JAXBHelperContext is a bridge between POJOs and SDO DataObjects.  This bridge allows POJO data to be exposed as SDO DataObjects, this is useful when using POJO data with SDO aware applications.  The bridge is based on their corresponding XML representations.
  
−
==Create the JAXBHelperContext==
+
==Create the POJO/SDO Bridge==
−
The JAXBHelperContext is instantiated using a JAXBContext.  This JAXBContext represents the object-to-XML mapping for the POJOs.  If static DataObjects are being used, a second constructor is offered that takes a ClassLoader as a parameter.
+
JAXBHelperContext is the bridge between POJOs and DataObjects.  This bridge allows POJOs to be converted to/from SDO DataObjects.  It also provides a mechanism to determine the SDO type corresponding to a POJO class. 
−
<pre>
+
 
 +
===Define an XML Representation for the POJOs===
 +
This XML representation can be defined either by applying JAXB annotations to the POJOs, or by using an existing XML schema and mapping to it using EclipseLink MOXy.  Programmatically this XML binding is represented as a javax.xml.bind.JAXBContext.
 +
<source lang="java">
 
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
 
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
−
JAXBHelperContext jaxbHelperContext = new JAXBHelperContext(jaxbContext);
+
</source>
−
</pre>
+
 
For help on creating a JAXBContext see:
 
For help on creating a JAXBContext see:
 
* [[EclipseLink/Examples/MOXy/JAXB#Creating_a_JAXBContext_using_jaxb.properties | Creating a JAXBContext using jaxb.properties]]
 
* [[EclipseLink/Examples/MOXy/JAXB#Creating_a_JAXBContext_using_jaxb.properties | Creating a JAXBContext using jaxb.properties]]
 
* [[EclipseLink/Examples/MOXy/NativeOxmJaxbContext | Creating a Native OXM aware JAXBContext]]
 
* [[EclipseLink/Examples/MOXy/NativeOxmJaxbContext | Creating a Native OXM aware JAXBContext]]
  
−
==Define the SDO Metadata==
+
===Instantiate the JAXBHelperContext===
 +
The JAXBHelperContext is instantiated using a JAXBContext.  This JAXBContext represents the object-to-XML mapping for the POJOs.  If static DataObjects are being used, a second constructor is offered that takes a ClassLoader as a parameter.
 +
<source lang="java">
 +
JAXBHelperContext jaxbHelperContext = new JAXBHelperContext(jaxbContext);
 +
</source>
 +
 
 +
===Define the SDO Side of the Metadata===
 
An XML schema can be used to create the SDO metadata.  This is the same schema that the POJOs are mapped to.  This step has been separated so that SDO annotations could be added to the XML schema.
 
An XML schema can be used to create the SDO metadata.  This is the same schema that the POJOs are mapped to.  This step has been separated so that SDO annotations could be added to the XML schema.
−
<pre>
+
<source lang="java">
 
jaxbHelperContext.getXSDHelper().define(xmlSchema);
 
jaxbHelperContext.getXSDHelper().define(xmlSchema);
−
</pre>
+
</source>
 +
For help on creating an XML Schema from POJOs using JAXB see:
 +
* [[EclipseLink/Examples/MOXy/JAXB#Using_JAXBContext_to_Generate_an_XML_Schema | Generating an XSD using a JAXBContext]]
  
 
==Get the SDO Type for a POJO==
 
==Get the SDO Type for a POJO==
 +
From the JAXBHelperContext you can determine the SDO type from a POJO class.  This provides quick access to the necessary SDO metadata, to work with the data as SDO DataObjects.
 +
<source lang="java">
 +
Type customerType = jaxbHelperContext.getType(Customer.class);
 +
DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType);
 +
</source>
  
 
==Convert a POJO to a SDO DataObject==
 
==Convert a POJO to a SDO DataObject==
 +
POJOs corresponding to the types in the JAXBContext, can be converted to SDO DataObjects using the "wrap" operation on JAXBHelperContext.  This operation should be called on the root POJO.
 +
<source lang="java">
 +
Customer customer = new Customer();
 +
Address address new Address();
 +
address.setStreet("123 Any Street");
 +
customer.set(address);
 +
 +
DataObject customerDO = jaxbHelperContext.wrap(customer);
 +
customerDO.getString("address/street");  // returns "123 Any Street"
 +
</source>
 +
Multiple calls to wrap for the same instance POJO return the same instance of DataObject, in other words the following is always true:
 +
<source lang="java">
 +
jaxbHelperContext.wrap(customer123) == jaxbHelperContext.wrap(customer123)
 +
jaxbHelperContext.wrap(customer123) != jaxbHelperContext.wrap(customer456)
 +
</source>
 +
 +
The wrap operation may also be called on a collection POJOS.
 +
<source lang="java">
 +
List<DataObject> dataObjects = jaxbHelperContext.wrap(pojoCollection);
 +
</source>
  
 
==Convert a SDO DataObject to a POJO==
 
==Convert a SDO DataObject to a POJO==
 +
SDO DataObjects corresponding to POJOs with types in the JAXBContext, can be converted to POJOs using the "unwrap" operation on JAXBHelperContext.
 +
<source lang="java">
 +
Type customerType = jaxbHelperContext.getType(Customer.class);
 +
DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType);
 +
DataObject addressDO = customerDO.create("address");
 +
addressDO.set("street", "123 Any Street");
 +
 +
Customer customer = (Customer) jaxbHelperContext.unwrap(customerDO);
 +
customer.getAddress().getStreet();  // returns "123 Any Street"
 +
</source>
 +
Multiple calls to unwrap for the same DataObject must return the same instance of Object, in other words the following is always true:
 +
<source lang="java">
 +
jaxbHelperContext.unwrap(customerDO123) == jaxbHelperContext.unwrap(customerDO123)
 +
jaxbHelperContext.unwrap(customerDO123) != jaxbHelperContext.unwrap(customerDO456)
 +
customer123 == jaxbHelperContext.unwrap(jaxbHelperContext.wrap(customer123))
 +
</source>
 +
The unwrap operation may also be called on a collection of SDO DataObjects.
 +
<source lang="java">
 +
List<Object> objects = jaxbHelperContext.unwrap(dataObjectCollection);
 +
</source>
 +
 +
==Unmarshalling from XML (SDO load)==
 +
JAXBHelperContext can be used to unmarshal the POJOs from XML.
 +
 +
<source lang="java">
 +
FileInputStream xml = new FileInputStream("customer.xml");
 +
XMLDocument xmlDocument = jaxbHelperContext.getXMLHelper().load(xml);
 +
DataObject customerDO = xmlDocument.getRootObject();
 +
Customer customer = (Customer) jaxbHelperContext.unwrap(customerDO);
 +
</source>
 +
 +
==Marshalling to XML (SDO save)==
 +
 +
JAXBHelperContext can be used to marshal the POJOs to XML.
 +
 +
<source lang="java">
 +
DataObject customerDO = jaxbHelperContext.wrap(customer);
 +
XMLDocument xmlDocument =jaxbHelperContext.getXMLHelper().createDocment(customerDO, "urn:customer", "root");
 +
jaxbHelperContext.getXMLHelper().save(xmlDocument, System.out, null);
 +
</source>
 +
 +
''Note: With the exception of the ChangeSummary property (if any), the output of the SDO save operation will be identical to the output produced by JAXB marshalling the entities directly.''
 +
 +
 +
== Limitations ==
 +
 +
The  following are known limitations of the current implementation.
 +
# All entities must be mapped to global XML elements or global complex types.
 +
# The schema context for a OXM descriptor can only be set to a global element if that element has an anonymous complex type.  Otherrwise the schema context must be set to be the corresponding global complex type instead.
 +
# Path and position based MOXy mappings are currently not supported with the SDO integration.  The following are compatible "address" and "name/text()", and the following are not currently compatible "contact-info/address" and "phone-number[2]".
 +
# Only the following MOXy mappings are supported (either through native mapping or JAXB equivalents):
 +
## XML Direct Mapping
 +
## XML Direct Collection Mapping
 +
## XML Composite Object Mapping
 +
## XML Compoiste Collection Mapping
 +
## XML Object Reference Mapping
 +
## XML Collection Reference Mapping
 +
# The current implementation does not support ChangeSummary
 +
# The current implementation does not support open content properties
 +
# The current implementation does not support inheritance

Latest revision as of 15:14, 6 February 2009

Overview

The JAXBHelperContext is a bridge between POJOs and SDO DataObjects. This bridge allows POJO data to be exposed as SDO DataObjects, this is useful when using POJO data with SDO aware applications. The bridge is based on their corresponding XML representations.

Create the POJO/SDO Bridge

JAXBHelperContext is the bridge between POJOs and DataObjects. This bridge allows POJOs to be converted to/from SDO DataObjects. It also provides a mechanism to determine the SDO type corresponding to a POJO class.

Define an XML Representation for the POJOs

This XML representation can be defined either by applying JAXB annotations to the POJOs, or by using an existing XML schema and mapping to it using EclipseLink MOXy. Programmatically this XML binding is represented as a javax.xml.bind.JAXBContext. 

JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");

For help on creating a JAXBContext see:

Instantiate the JAXBHelperContext

The JAXBHelperContext is instantiated using a JAXBContext. This JAXBContext represents the object-to-XML mapping for the POJOs. If static DataObjects are being used, a second constructor is offered that takes a ClassLoader as a parameter. 

JAXBHelperContext jaxbHelperContext = new JAXBHelperContext(jaxbContext);

Define the SDO Side of the Metadata

An XML schema can be used to create the SDO metadata. This is the same schema that the POJOs are mapped to. This step has been separated so that SDO annotations could be added to the XML schema. 

jaxbHelperContext.getXSDHelper().define(xmlSchema);

For help on creating an XML Schema from POJOs using JAXB see:

Get the SDO Type for a POJO

From the JAXBHelperContext you can determine the SDO type from a POJO class. This provides quick access to the necessary SDO metadata, to work with the data as SDO DataObjects. 

Type customerType = jaxbHelperContext.getType(Customer.class);
DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType);

Convert a POJO to a SDO DataObject

POJOs corresponding to the types in the JAXBContext, can be converted to SDO DataObjects using the "wrap" operation on JAXBHelperContext. This operation should be called on the root POJO. 

Customer customer = new Customer();
Address address new Address();
address.setStreet("123 Any Street");
customer.set(address);
 
DataObject customerDO = jaxbHelperContext.wrap(customer);
customerDO.getString("address/street");  // returns "123 Any Street"

Multiple calls to wrap for the same instance POJO return the same instance of DataObject, in other words the following is always true: 

jaxbHelperContext.wrap(customer123) == jaxbHelperContext.wrap(customer123)
jaxbHelperContext.wrap(customer123) != jaxbHelperContext.wrap(customer456)

The wrap operation may also be called on a collection POJOS. 

List<DataObject> dataObjects = jaxbHelperContext.wrap(pojoCollection);

Convert a SDO DataObject to a POJO

SDO DataObjects corresponding to POJOs with types in the JAXBContext, can be converted to POJOs using the "unwrap" operation on JAXBHelperContext. 

Type customerType = jaxbHelperContext.getType(Customer.class);
DataObject customerDO = jaxbHelperContext.getDataFactory().create(customerType);
DataObject addressDO = customerDO.create("address");
addressDO.set("street", "123 Any Street");
 
Customer customer = (Customer) jaxbHelperContext.unwrap(customerDO);
customer.getAddress().getStreet();  // returns "123 Any Street"

Multiple calls to unwrap for the same DataObject must return the same instance of Object, in other words the following is always true: 

jaxbHelperContext.unwrap(customerDO123) == jaxbHelperContext.unwrap(customerDO123)
jaxbHelperContext.unwrap(customerDO123) != jaxbHelperContext.unwrap(customerDO456)
customer123 == jaxbHelperContext.unwrap(jaxbHelperContext.wrap(customer123))

The unwrap operation may also be called on a collection of SDO DataObjects. 

List<Object> objects = jaxbHelperContext.unwrap(dataObjectCollection);

Unmarshalling from XML (SDO load)

JAXBHelperContext can be used to unmarshal the POJOs from XML. 

FileInputStream xml = new FileInputStream("customer.xml");
XMLDocument xmlDocument = jaxbHelperContext.getXMLHelper().load(xml);
DataObject customerDO = xmlDocument.getRootObject();
Customer customer = (Customer) jaxbHelperContext.unwrap(customerDO);

Marshalling to XML (SDO save)

JAXBHelperContext can be used to marshal the POJOs to XML. 

DataObject customerDO = jaxbHelperContext.wrap(customer);
XMLDocument xmlDocument =jaxbHelperContext.getXMLHelper().createDocment(customerDO, "urn:customer", "root");
jaxbHelperContext.getXMLHelper().save(xmlDocument, System.out, null);

Note: With the exception of the ChangeSummary property (if any), the output of the SDO save operation will be identical to the output produced by JAXB marshalling the entities directly.


Limitations

The following are known limitations of the current implementation.

  1. All entities must be mapped to global XML elements or global complex types.
  2. The schema context for a OXM descriptor can only be set to a global element if that element has an anonymous complex type. Otherrwise the schema context must be set to be the corresponding global complex type instead.
  3. Path and position based MOXy mappings are currently not supported with the SDO integration. The following are compatible "address" and "name/text()", and the following are not currently compatible "contact-info/address" and "phone-number[2]".
  4. Only the following MOXy mappings are supported (either through native mapping or JAXB equivalents):
    1. XML Direct Mapping
    2. XML Direct Collection Mapping
    3. XML Composite Object Mapping
    4. XML Compoiste Collection Mapping
    5. XML Object Reference Mapping
    6. XML Collection Reference Mapping
  5. The current implementation does not support ChangeSummary
  6. The current implementation does not support open content properties
  7. The current implementation does not support inheritance
Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/Examples/SDO/JAXB&oldid=139425"

This page was last modified 15:14, 6 February 2009 by Blaise Doughan.

Back to the top