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/Development/SDO-JPA"

(Limitations)
 
(3 intermediate revisions by the same user not shown)
Line 34: Line 34:
 
# The SDO Data Object model is now implicitly define through the use of the generated XSD. If the service developer wishes to use a static DataObject model they can optionally use the SDO compiler to generate this model based on the XSD.  
 
# The SDO Data Object model is now implicitly define through the use of the generated XSD. If the service developer wishes to use a static DataObject model they can optionally use the SDO compiler to generate this model based on the XSD.  
  
==== 1.1. SDO Bootstrapping ====
+
Support for this use case has been added to EclipseLink 1.1. See the following links for more information:
 +
* [[EclipseLink/Examples/SDO/JAXB | Wrapping JAXB Objects in SDO DataObjects]]
 +
* [[EclipseLink/Examples/SDO/JPA | Wrapping JPA Entities in SDO DataObjects]]
  
When the application needs to interact with the JPA backed SDO model the service being developed must bootstrap the SDO context. In general SDO usage the context is initialized using something like:
+
==== Feature Development ====
 
+
<source lang="java">
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
</source>
+
 
+
When using JPA entities behind the SDO model the service developer will need to express the XML schema represenation through JAXB mappings (including MOXy extensions) on the JPA entities.
+
 
+
==== Querying ====
+
 
+
When developing a service that will return SDO DataObject instances from the relational database the developer will issue queries against the database using JPA (PK Find, JP QL or Native ORM queries in JPA 1.0). The resulting entities will then be wrapped by DataObject using a provided helper class.
+
 
+
<source lang="java">
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample");     
+
EntityManager em = emf.createEntityManager();
+
List<MyEntity> entities = em.createQuery("SELECT e FROM MyEntity e WHERE ...").getResultList();
+
 
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
 
+
List<DataObject> dataObjects = hc.wrap(entities);
+
</source>
+
 
+
==== Creating (JPA persist) ====
+
 
+
Creating new entities in the database can be done by explicitly requesting the new data to be persisted. If the DataObject being persisted combines new objects with updates to existing objects then the Updating scenario below will be used.
+
 
+
<source lang="java">
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample");     
+
EntityManager em = emf.createEntityManager();
+
 
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
 
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
 
+
DataObject customerDO = hc.getDataFactory().create("urn:customer", "customer");
+
customerDO.setString("firstName", "Jane");
+
customerDO.setString("lastName", "Doe");
+
DataObject addressDO customerDO.create("address");
+
addressDO.setString("street", "123 Any Street");
+
addressDO.setString("city", "Any Town");
+
 
+
em.getTransaction().begin();
+
em.persist(jpaHelperContext.unwrap(customerDO));
+
em.getTransaction().commit();
+
 
+
</source>
+
''Note: The cascade persist configuration on the underlying entity's relationship mappings will define the scope of which new instances in the graph will be persisted.''
+
 
+
==== Updating (JPA merge) ====
+
 
+
In the case of updates to existing entities as well as addition of new entities through relationships the merge call on the helper will be used.
+
 
+
<source lang="java">
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample");     
+
EntityManager em = emf.createEntityManager();
+
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
 
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
 
+
em.getTransaction().begin();
+
em.merge(hc.unwrap(dataObject));
+
// ... Other operations within the same TX
+
em.getTransaction().commit();
+
</source>
+
 
+
''Note: The creation of new objects and the removal of existing objects in the graph result in database operations based on the cascade and private-owned configurations in the JPA model's relationship mappings.''
+
 
+
==== Deleting (JPA remove) ====
+
 
+
Entities can be removed from the database using the helper's remove call:
+
 
+
<source lang="java">
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("CustomerExample");     
+
EntityManager em = emf.createEntityManager();
+
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
 
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
+
em.getTransaction().begin();
+
em.remove(hc.unwrap(dataObject));
+
em.getTransaction().commit();
+
</source>
+
 
+
==== Unmarshalling from XML (SDO load) ====
+
 
+
SDO can be used to unmarshal the JPA entities from XML.
+
 
+
<source lang="java">
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
 
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
 
+
FileInputStream xml = new FileInputStream("customer.xml");
+
XMLDocument xmlDocument = gc.getXMLHelper().load(xml);
+
DataObject customerDO = xmlDocument.getRootObject();
+
Customer customer = (Customer) hc.unwrap(customerDO);
+
</source>
+
 
+
==== Marshalling to XML (SDO save) ====
+
 
+
SDO can be used to marshal the JPA entities to XML.
+
 
+
<source lang="java">
+
JAXBContext jaxbContext = JAXBContext.newInstance("com.example.customer");
+
 
+
HelperContext hc = new JAXBHelperConext(jaxbContext);
+
hc.getXSDHelper().define(customerXSD);
+
 
+
DataObject customerDO = hc.wrap(customer);
+
XMLDocument xmlDocument = hc.getXMLHelper().createDocment(customerDO, "urn:customer", "root");
+
hc.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:
+
## 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
+
 
+
== Feature Development ==
+
  
 
In order to implement the above defined functionality the following development tasks and associated design work is required.
 
In order to implement the above defined functionality the following development tasks and associated design work is required.
# JPA ValueStore
+
# Merge using ChangeSummary
# Helper: SdoJpaContext
+
 
# Examples
 
# Examples
  
=== JPA Value Store ===
+
===== Merge using ChangeSummary =====
  
Within the EclipseLink SDO implementation there is inherent support for wrapping different implementations of a ValueStore (). This interface and supporting mechanics of accessing the values from the new EntityValueStore will be the core of the incubation effort.
+
When a developer wishes to persist a DataObject graph and a ChangeSummary is available this solution should leverage the ChangeSummary to avoid calculating the necessary changes based on reading in the objects and doing comparisons.
  
[[Image:sdo-uml.jpg]]
+
=== 2. JPA Mapping of SDO DataObjects ===
  
=== SDO-JPA Helper/Context ===
+
In this use case the static SDO impl classes are the JPA entities.
 
+
An approach to bootstrapping and accessing the integrated functionality will be required.
+
 
+
=== Merge using ChangeSummary ===
+
 
+
When a developer wishes to persist a DataObject graph and a ChangeSummary is available this solution should leverage the ChangeSummary to avoid calculating the necessary changes based on reading in the objects and doing comparisons.
+

Latest revision as of 14:36, 30 January 2009

EclipseLink Incubator: SDO Data Access Service with JPA

The work is being developed within the EclipseLink/Development/Incubator and is being tracked by bug 258057.

This incubator is intended to illustrate how SDO can be used with JPA to provide relational database access to data exposed as SDO DataObjects. This functionality bridges SDO, JPA, and MOXy components and may also result in the generation of some additional utilities to simplify development tasks and tooling support.

Incubator Exit Criteria

This incubator feature is intended to facilitate rapid development and interaction with consumers. Once each usage scenario is validated with the consumers and the necessary testing is in place the functionality will be migrated back into the main components (SDO, MOXy, JPA, & Core) as well as the necessary test cases being migrated into the corresponding projects.

This incubator feature will continue to evolve functionality until all of the consumer required use cases surrounding SDO usage with JPA have been addressed.

Use Cases

There are several options for using SDO with JPA:

  1. SDO DataObjects wrapping JPA entities. The XSD and DataObject model defined by JAXB mappings on the JPA entities
  2. JPA Mapping of SDO DataObjects

1. SDO DataObjects wrapping JPA entities

In this use case a developer wishes to expose their JPA model as an SDO DataObject model (static or dynamic). The JPA entities are mapped to a XSD through JAXB mappings.

  1. In this use case the developer defines the mapping from the JPA domain model (POJOs) to an XML schema (XSD) using JAXB mappings (annotations or EclipseLink native OXM).
  2. The XSD is then generated using the JAXB Java-XML Compiler (JXC), or in the meet-in-the-middle case the schema from the previous step.
  3. The SDO Data Object model is now implicitly define through the use of the generated XSD. If the service developer wishes to use a static DataObject model they can optionally use the SDO compiler to generate this model based on the XSD.

Support for this use case has been added to EclipseLink 1.1. See the following links for more information:

Feature Development

In order to implement the above defined functionality the following development tasks and associated design work is required.

  1. Merge using ChangeSummary
  2. Examples
Merge using ChangeSummary

When a developer wishes to persist a DataObject graph and a ChangeSummary is available this solution should leverage the ChangeSummary to avoid calculating the necessary changes based on reading in the objects and doing comparisons.

2. JPA Mapping of SDO DataObjects

In this use case the static SDO impl classes are the JPA entities.

Back to the top