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/Development/DBWS/MetadataSupport"
(→org.eclipse.persistence.tools.dbws.XmlBindingsGenerator) |
|||
Line 1: | Line 1: | ||
== Design document for adding JPA/JAXB metadata support to DBWS == | == Design document for adding JPA/JAXB metadata support to DBWS == | ||
− | |||
− | + | The purpose of this document is to outline what changes are to be made to the DBWS codebase to allow support for reading/writing JPA/JAXB metadata in place of EclipseLink deployment XML. This feature is required to resolve EclipseLink [https://bugs.eclipse.org/bugs/show_bug.cgi?id=332227 Bug 332227]. | |
− | The | + | |
− | === Requirements === | + | === Overview === |
− | *Support generation and marshal of JPA and JAXB metadata files in the DBWS builder | + | |
− | *Support unmarshal of JPA and JAXB metadata files in the DBWS runtime | + | The DBWS builder constructs OR/OX projects, which are marshalled to a given output stream by the builder and placed in a generated .war archive for use by the DBWS runtime. The builder currently utilizes the legacy EclipseLink deployment XML format for this purpose, but is required to move to the modern JPA/JAXB metadata format. |
+ | |||
+ | === Requirements === | ||
+ | |||
+ | *Support generation and marshal of JPA and JAXB metadata files in the DBWS builder | ||
+ | *Support unmarshal of JPA and JAXB metadata files in the DBWS runtime | ||
*Support unmarshal of legacy OR/OX deployment XML for backward compatibility | *Support unmarshal of legacy OR/OX deployment XML for backward compatibility | ||
− | === JAXB Metadata support === | + | === JAXB Metadata support === |
− | The existing DBWS builder code utilizes the <code>ObjectPersistenceWorkbenchXMLProject</code> class to marshal the OX project at design time and unmarshal it at runtime. | + | |
− | *http://wiki.eclipse.org/EclipseLink/DesignDocs/277920 | + | The existing DBWS builder code utilizes the <code>ObjectPersistenceWorkbenchXMLProject</code> class to marshal the OX project at design time and unmarshal it at runtime. The code will be changed to instead use JAXB metadata for these operations. The following pages contain information pertaining to EclipseLink's support for JAXB annotations via XML metadata: |
− | *http://wiki.eclipse.org/EclipseLink/DesignDocs/293925 | + | |
+ | *http://wiki.eclipse.org/EclipseLink/DesignDocs/277920 | ||
+ | *http://wiki.eclipse.org/EclipseLink/DesignDocs/293925 | ||
*http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions | *http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions | ||
− | The DBWS builder creates an OX project; | + | The DBWS builder creates an OX project; this project's descriptors - and each descriptor's mappings - will be used to generate one or more <code><xml-bindings></code> elements (one per package) that make up the JAXB metadata file. Three classes are needed to accomplish this task: |
− | *<code>XmlBindingsModel</code> - used to create a JAXB context that can be used to marshal/unmarshal the metadata file. | + | |
− | *<code>XmlBindingsGenerator</code> - generates one or more <code> | + | *<code>XmlBindingsModel</code> - used to create a JAXB context that can be used to marshal/unmarshal the metadata file. |
+ | *<code>XmlBindingsGenerator</code> - generates one or more <code><xml-bindings></code> elements (one per package) based on a list of Descriptor instances | ||
*<code>DBWSMetadataSource</code> - implementation of <code>org.eclipse.persistence.jaxb.metadata.MetadataSource</code> to allow passing <code>org.eclipse.persistence.jaxb.xmlmodel.XmlBindings</code> to a <code>org.eclipse.persistence.jaxb.dynamic.DynamicJAXBContextFactory</code> instance | *<code>DBWSMetadataSource</code> - implementation of <code>org.eclipse.persistence.jaxb.metadata.MetadataSource</code> to allow passing <code>org.eclipse.persistence.jaxb.xmlmodel.XmlBindings</code> to a <code>org.eclipse.persistence.jaxb.dynamic.DynamicJAXBContextFactory</code> instance | ||
− | The generated metadata file will have the format: | + | |
− | <source lang="xml"> | + | The generated metadata file will have the format: <source lang="xml"> |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> | <?xml version="1.0" encoding="UTF-8" standalone="yes"?> | ||
<xml-bindings-list xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"> | <xml-bindings-list xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"> | ||
Line 32: | Line 38: | ||
... | ... | ||
</xml-bindings-list> | </xml-bindings-list> | ||
− | </source> | + | </source> |
==== org.eclipse.persistence.internal.xr.XmlBindingsModel ==== | ==== org.eclipse.persistence.internal.xr.XmlBindingsModel ==== | ||
− | The <code>XmlBindingsModel</code> class will be used to create a <code>JAXBContext</code> instance that is able to marshal and unmarshal the generated JAXB metadata file. | + | |
− | <source lang="java"> | + | The <code>XmlBindingsModel</code> class will be used to create a <code>JAXBContext</code> instance that is able to marshal and unmarshal the generated JAXB metadata file. <source lang="java"> |
/** | /** | ||
* This class is responsible for holding a list of XmlBindings. | * This class is responsible for holding a list of XmlBindings. | ||
Line 61: | Line 67: | ||
} | } | ||
} | } | ||
− | </source> | + | </source> |
+ | |||
+ | ==== org.eclipse.persistence.tools.dbws.XmlBindingsGenerator ==== | ||
+ | |||
+ | This class is responsible for generating one or more <code><xml-bindings></code> elements (one per package) based on a given list of Descriptor instances - these elements will make up the JAXB metadata file. The following OX mappings must be supported: | ||
− | + | *<code>XMLBinaryDataMapping</code> | |
− | + | *<code>XMLCompositeCollectionMapping</code> | |
− | *<code>XMLBinaryDataMapping</code> | + | *<code>XMLCompositeDirectCollectionMapping</code> |
− | *<code>XMLCompositeCollectionMapping</code> | + | *<code>XMLCompositeObjectMapping</code> |
− | *<code>XMLCompositeDirectCollectionMapping</code> | + | |
− | *<code>XMLCompositeObjectMapping</code> | + | |
*<code>XMLDirectMapping</code> | *<code>XMLDirectMapping</code> | ||
− | The following API is required: | + | |
− | <source lang="java"> | + | The following API is required: <source lang="java"> |
/** | /** | ||
* Generate one or more XmlBindings based on a given list of | * Generate one or more XmlBindings based on a given list of | ||
Line 78: | Line 86: | ||
*/ | */ | ||
public static List<XmlBindings> generateXmlBindings(List<ClassDescriptor> descriptors) | public static List<XmlBindings> generateXmlBindings(List<ClassDescriptor> descriptors) | ||
− | </source> | + | </source> <source lang="java"> |
− | <source lang="java"> | + | |
/** | /** | ||
* Generate an XmlBindings instance based on a list of XML descriptors. | * Generate an XmlBindings instance based on a list of XML descriptors. | ||
Line 88: | Line 95: | ||
*/ | */ | ||
public static XmlBindings generateXmlBindings(String packageName, List<XMLDescriptor> descriptors) | public static XmlBindings generateXmlBindings(String packageName, List<XMLDescriptor> descriptors) | ||
− | </source> | + | </source> |
+ | |||
+ | ==== org.eclipse.persistence.internal.xr.XRServiceFactory$DBWSMetadataSource ==== | ||
− | + | This inner class holds on to an <code>org.eclipse.persistence.jaxb.xmlmodel.XmlBindings</code> instance, allowing it to be passed to the DynamicJAXBContextFactory. <source lang="java"> | |
− | This inner class holds on to an <code>org.eclipse.persistence.jaxb.xmlmodel.XmlBindings</code> instance, allowing it to be passed to the DynamicJAXBContextFactory. | + | |
− | <source lang="java"> | + | |
/** | /** | ||
* Implementation of MetadataSource to allow passing XmlBindings | * Implementation of MetadataSource to allow passing XmlBindings | ||
Line 110: | Line 117: | ||
} | } | ||
} | } | ||
− | </source> | + | </source> |
+ | |||
+ | ==== Example: <code>XmlBindings</code> list generation and marshal operation ==== | ||
− | + | The following example illustrates how the <code>XmlBindingsGenerator</code> can be used to generate a list of <code>org.eclipse.persistence.jaxb.xmlmodel.XmlBindings</code> instances, and how this list can be marshalled to a given output stream: <source lang="java"> | |
− | The following example illustrates how the <code>XmlBindingsGenerator</code> can be used to generate a list of <code>org.eclipse.persistence.jaxb.xmlmodel.XmlBindings</code> instances, and how this list can be marshalled to a given output stream: | + | |
− | <source lang="java"> | + | |
List<XmlBindings> xmlBindingsList = XmlBindingsGenerator.generateXmlBindings(oxProject.getOrderedDescriptors()); | List<XmlBindings> xmlBindingsList = XmlBindingsGenerator.generateXmlBindings(oxProject.getOrderedDescriptors()); | ||
if (xmlBindingsList.size() > 0) { | if (xmlBindingsList.size() > 0) { | ||
Line 128: | Line 135: | ||
} | } | ||
} | } | ||
− | </source> | + | </source> Note that the existing marshal code in <code>BaseDBWSBuilderHelper.writeOrOxProjects</code> should be removed and the above code (or similar) should be used. |
− | Note that the existing marshal code in <code>BaseDBWSBuilderHelper.writeOrOxProjects</code> should be removed and the above code (or similar) should be used. | + | |
+ | ==== Example: Unmarshal a JAXB metadata file and use DynamicJAXBContext to retrieve the resulting OX Project ==== | ||
− | + | The following example illustrates how DBWS generated JAXB metadata can be unmarshalled to an <code>XmlBindingsModel</code>, and how this can be used with <code>DynamicJAXBContext</code> to retrieve the OX Project. <source lang="java"> | |
− | The following example illustrates how DBWS generated JAXB metadata can be unmarshalled to an <code>XmlBindingsModel</code>, and how this can be used with <code>DynamicJAXBContext</code> to retrieve the OX Project. | + | |
− | <source lang="java"> | + | |
Map<String, DBWSMetadataSource> metadataMap = new HashMap<String, DBWSMetadataSource>(); | Map<String, DBWSMetadataSource> metadataMap = new HashMap<String, DBWSMetadataSource>(); | ||
StreamSource xml = new StreamSource(inStream); | StreamSource xml = new StreamSource(inStream); | ||
Line 158: | Line 164: | ||
throw new DBWSException(OXM_PROCESSING_EX, e); | throw new DBWSException(OXM_PROCESSING_EX, e); | ||
} | } | ||
+ | </source> Note that the existing unmarshal code in <code>XRServiceFactory.buildSessions</code> should be removed and the above code (or similar) should be used. | ||
+ | |||
+ | === JPA Metadata support === | ||
+ | |||
+ | The existing DBWS builder code utilizes the <code>ObjectPersistenceWorkbenchXMLProject</code> class to marshal the OR project at design time and unmarshal it at runtime. The code will be changed to instead use JPA metadata for these operations. The following page contains information pertaining to EclipseLink's support for JPA annotations via XML metadata: | ||
+ | |||
+ | *http://wiki.eclipse.org/EclipseLink/Development/JPA_2.0/metamodel_api | ||
+ | |||
+ | The DBWS builder creates an OR project; this project's queries and descriptors - and each descriptor's mappings - will be used to generate the JPA metadata <code><entity-mappings></code> element and each of its sub-elements. The following classes are needed to accomplish this task: | ||
+ | |||
+ | *<code>XmlEntityMappingsGenerator</code> - generates an <code><entity-mappings></code> element and each of it's sub-elements based on lists of Query and Descriptor instances | ||
+ | *<code>XRPersistenceUnitInfo</code> - implementation of <code>javax.persistence.spi.PersistenceUnitInfo</code> | ||
+ | *<code>JPAMetadataSource</code> - implementation of <code>org.eclipse.persistence.jpa.metadata.MetadataSource</code> | ||
+ | |||
+ | ==== org.eclipse.persistence.tools.dbws.XmlEntityMappingsGenerator ==== | ||
+ | |||
+ | This class is responsible for generating the JPA metadata <code><entity-mappings></code> element and each of its sub-elements based on given lists of Query and Descriptor instances. The following OR mappings must be supported: | ||
+ | |||
+ | *<code>AggregateMapping</code> | ||
+ | *<code>ArrayMapping</code> | ||
+ | *<code>DirectToFieldMapping</code> | ||
+ | *<code>ObjectArrayMapping</code> | ||
+ | *<code>StructureMapping</code> | ||
+ | |||
+ | The following API is required: <source lang="java"> | ||
+ | /** | ||
+ | * Generate an XMLEntityMappings instance based on a given OR Project's Queries and Descriptors. | ||
+ | * | ||
+ | * @param orProject the ORM Project instance containing Queries and Descriptors to be used to generate an XMLEntityMappings | ||
+ | * @param complexTypes list of composite database types used to generate metadata for advanced Oracle and PL/SQL types | ||
+ | */ | ||
+ | public static XMLEntityMappings generateXmlEntityMappings(Project orProject, List<CompositeDatabaseType> complexTypes) | ||
</source> | </source> | ||
− |
Revision as of 09:25, 21 February 2013
Contents
- 1 Design document for adding JPA/JAXB metadata support to DBWS
- 1.1 Overview
- 1.2 Requirements
- 1.3 JAXB Metadata support
- 1.3.1 org.eclipse.persistence.internal.xr.XmlBindingsModel
- 1.3.2 org.eclipse.persistence.tools.dbws.XmlBindingsGenerator
- 1.3.3 org.eclipse.persistence.internal.xr.XRServiceFactory$DBWSMetadataSource
- 1.3.4 Example: XmlBindings list generation and marshal operation
- 1.3.5 Example: Unmarshal a JAXB metadata file and use DynamicJAXBContext to retrieve the resulting OX Project
- 1.4 JPA Metadata support
Design document for adding JPA/JAXB metadata support to DBWS
The purpose of this document is to outline what changes are to be made to the DBWS codebase to allow support for reading/writing JPA/JAXB metadata in place of EclipseLink deployment XML. This feature is required to resolve EclipseLink Bug 332227.
Overview
The DBWS builder constructs OR/OX projects, which are marshalled to a given output stream by the builder and placed in a generated .war archive for use by the DBWS runtime. The builder currently utilizes the legacy EclipseLink deployment XML format for this purpose, but is required to move to the modern JPA/JAXB metadata format.
Requirements
- Support generation and marshal of JPA and JAXB metadata files in the DBWS builder
- Support unmarshal of JPA and JAXB metadata files in the DBWS runtime
- Support unmarshal of legacy OR/OX deployment XML for backward compatibility
JAXB Metadata support
The existing DBWS builder code utilizes the ObjectPersistenceWorkbenchXMLProject
class to marshal the OX project at design time and unmarshal it at runtime. The code will be changed to instead use JAXB metadata for these operations. The following pages contain information pertaining to EclipseLink's support for JAXB annotations via XML metadata:
- http://wiki.eclipse.org/EclipseLink/DesignDocs/277920
- http://wiki.eclipse.org/EclipseLink/DesignDocs/293925
- http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions
The DBWS builder creates an OX project; this project's descriptors - and each descriptor's mappings - will be used to generate one or more <xml-bindings>
elements (one per package) that make up the JAXB metadata file. Three classes are needed to accomplish this task:
XmlBindingsModel
- used to create a JAXB context that can be used to marshal/unmarshal the metadata file.XmlBindingsGenerator
- generates one or more<xml-bindings>
elements (one per package) based on a list of Descriptor instancesDBWSMetadataSource
- implementation oforg.eclipse.persistence.jaxb.metadata.MetadataSource
to allow passingorg.eclipse.persistence.jaxb.xmlmodel.XmlBindings
to aorg.eclipse.persistence.jaxb.dynamic.DynamicJAXBContextFactory
instance
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xml-bindings-list xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"> <xml-bindings package-name="simpletable"> ... </xml-bindings> <xml-bindings package-name="complextable"> ... </xml-bindings> ... </xml-bindings-list>
org.eclipse.persistence.internal.xr.XmlBindingsModel
TheXmlBindingsModel
class will be used to create a JAXBContext
instance that is able to marshal and unmarshal the generated JAXB metadata file. /** * This class is responsible for holding a list of XmlBindings. * */ @XmlAccessorType(javax.xml.bind.annotation.XmlAccessType.FIELD) @XmlRootElement(name="xml-bindings-list", namespace="http://www.eclipse.org/eclipselink/xsds/persistence/oxm") public class XmlBindingsModel { @XmlElement(name="xml-bindings", namespace="http://www.eclipse.org/eclipselink/xsds/persistence/oxm") public List<XmlBindings> bindingsList; /** * Return the list of XmlBindings */ public List<XmlBindings> getBindingsList() { return bindingsList; } /** * Set the list of XmlBindings. */ public void setBindingsList(List<XmlBindings> bindingsList) { this.bindingsList = bindingsList; } }
org.eclipse.persistence.tools.dbws.XmlBindingsGenerator
This class is responsible for generating one or more <xml-bindings>
elements (one per package) based on a given list of Descriptor instances - these elements will make up the JAXB metadata file. The following OX mappings must be supported:
XMLBinaryDataMapping
XMLCompositeCollectionMapping
XMLCompositeDirectCollectionMapping
XMLCompositeObjectMapping
XMLDirectMapping
/** * Generate one or more XmlBindings based on a given list of * ClassDescriptor instances. * */ public static List<XmlBindings> generateXmlBindings(List<ClassDescriptor> descriptors)
/**
* Generate an XmlBindings instance based on a list of XML descriptors.
*
* OXM metadata files are processed on a per package basis, hence it is
* assumed that the given list of descriptors are from the same package.
*
*/
public static XmlBindings generateXmlBindings(String packageName, List<XMLDescriptor> descriptors)org.eclipse.persistence.internal.xr.XRServiceFactory$DBWSMetadataSource
This inner class holds on to anorg.eclipse.persistence.jaxb.xmlmodel.XmlBindings
instance, allowing it to be passed to the DynamicJAXBContextFactory. /** * Implementation of MetadataSource to allow passing XmlBindings * to the DynamicJAXBContextFactory * */ public class DBWSMetadataSource implements MetadataSource { XmlBindings xmlbindings; public DBWSMetadataSource(XmlBindings bindings) { xmlbindings = bindings; } @Override public XmlBindings getXmlBindings(Map<String, ?> properties, ClassLoader classLoader) { return xmlbindings; } }
Example: XmlBindings
list generation and marshal operation
The following example illustrates how the XmlBindingsGenerator
can be used to generate a list of org.eclipse.persistence.jaxb.xmlmodel.XmlBindings
instances, and how this list can be marshalled to a given output stream: List<XmlBindings> xmlBindingsList = XmlBindingsGenerator.generateXmlBindings(oxProject.getOrderedDescriptors()); if (xmlBindingsList.size() > 0) { XmlBindingsModel model = new XmlBindingsModel(); model.setBindingsList(xmlBindingsList); try { JAXBContext jc = JAXBContext.newInstance(XmlBindingsModel.class); Marshaller marshaller = jc.createMarshaller(); marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true); marshaller.marshal(model, dbwsOxStream); } catch (JAXBException jaxbEx) { throw new DBWSException(OXM_MARSHAL_EX_MSG, jaxbEx); } }
BaseDBWSBuilderHelper.writeOrOxProjects
should be removed and the above code (or similar) should be used.
Example: Unmarshal a JAXB metadata file and use DynamicJAXBContext to retrieve the resulting OX Project
The following example illustrates how DBWS generated JAXB metadata can be unmarshalled to anXmlBindingsModel
, and how this can be used with DynamicJAXBContext
to retrieve the OX Project. Map<String, DBWSMetadataSource> metadataMap = new HashMap<String, DBWSMetadataSource>(); StreamSource xml = new StreamSource(inStream); try { JAXBContext jc = JAXBContext.newInstance(XmlBindingsModel.class); Unmarshaller unmarshaller = jc.createUnmarshaller(); JAXBElement<XmlBindingsModel> jaxbElt = unmarshaller.unmarshal(xml, XmlBindingsModel.class); XmlBindingsModel model = jaxbElt.getValue(); for (XmlBindings xmlBindings : model.getBindingsList()) { metadataMap.put(xmlBindings.getPackageName(), new DBWSMetadataSource(xmlBindings)); } } catch (JAXBException jaxbex) { throw new DBWSException(OXM_PROCESSING_EX, jaxbex); } Map<String, Map<String, DBWSMetadataSource>> properties = new HashMap<String, Map<String, DBWSMetadataSource>>(); properties.put(JAXBContextProperties.OXM_METADATA_SOURCE, metadataMap); try { DynamicJAXBContext jCtx = DynamicJAXBContextFactory.createContextFromOXM(xrdecl, properties); oxProject = jCtx.getXMLContext().getSession(0).getProject(); } catch (JAXBException e) { throw new DBWSException(OXM_PROCESSING_EX, e); }
XRServiceFactory.buildSessions
should be removed and the above code (or similar) should be used.
JPA Metadata support
The existing DBWS builder code utilizes the ObjectPersistenceWorkbenchXMLProject
class to marshal the OR project at design time and unmarshal it at runtime. The code will be changed to instead use JPA metadata for these operations. The following page contains information pertaining to EclipseLink's support for JPA annotations via XML metadata:
The DBWS builder creates an OR project; this project's queries and descriptors - and each descriptor's mappings - will be used to generate the JPA metadata <entity-mappings>
element and each of its sub-elements. The following classes are needed to accomplish this task:
XmlEntityMappingsGenerator
- generates an<entity-mappings>
element and each of it's sub-elements based on lists of Query and Descriptor instancesXRPersistenceUnitInfo
- implementation ofjavax.persistence.spi.PersistenceUnitInfo
JPAMetadataSource
- implementation oforg.eclipse.persistence.jpa.metadata.MetadataSource
org.eclipse.persistence.tools.dbws.XmlEntityMappingsGenerator
This class is responsible for generating the JPA metadata <entity-mappings>
element and each of its sub-elements based on given lists of Query and Descriptor instances. The following OR mappings must be supported:
AggregateMapping
ArrayMapping
DirectToFieldMapping
ObjectArrayMapping
StructureMapping
/** * Generate an XMLEntityMappings instance based on a given OR Project's Queries and Descriptors. * * @param orProject the ORM Project instance containing Queries and Descriptors to be used to generate an XMLEntityMappings * @param complexTypes list of composite database types used to generate metadata for advanced Oracle and PL/SQL types */ public static XMLEntityMappings generateXmlEntityMappings(Project orProject, List<CompositeDatabaseType> complexTypes)