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"
Line 79: | Line 79: | ||
*<code>XMLDirectMapping</code> | *<code>XMLDirectMapping</code> | ||
− | The following API is required: <source lang="java"> | + | The following public 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 188: | Line 188: | ||
*<code>StructureMapping</code> | *<code>StructureMapping</code> | ||
− | The following API is required: <source lang="java"> | + | The following public API is required: <source lang="java"> |
/** | /** | ||
* Generate an XMLEntityMappings instance based on a given OR Project's Queries and Descriptors. | * Generate an XMLEntityMappings instance based on a given OR Project's Queries and Descriptors. | ||
Line 196: | Line 196: | ||
*/ | */ | ||
public static XMLEntityMappings generateXmlEntityMappings(Project orProject, List<CompositeDatabaseType> complexTypes) | public static XMLEntityMappings generateXmlEntityMappings(Project orProject, List<CompositeDatabaseType> complexTypes) | ||
+ | </source> | ||
+ | |||
+ | ==== org.eclipse.persistence.internal.xr.XRServiceFactory$JPAMetadataSource ==== | ||
+ | |||
+ | This inner class is responsible for returning an XMLEntityMappings instance built based on given JPA metadata. | ||
+ | |||
+ | <source lang="java"> | ||
+ | /** | ||
+ | * Implementation of MetadataSource to allow passing JPA metadata to the | ||
+ | * MetadataProcessor. | ||
+ | * | ||
+ | */ | ||
+ | public class JPAMetadataSource implements org.eclipse.persistence.jpa.metadata.MetadataSource { | ||
+ | XRDynamicClassLoader xrdecl; | ||
+ | String inStreamAsString; | ||
+ | |||
+ | public JPAMetadataSource(XRDynamicClassLoader loader, String inStreamAsString) { | ||
+ | xrdecl = loader; | ||
+ | this.inStreamAsString = inStreamAsString; | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public Map<String, Object> getPropertyOverrides(Map<String, Object> properties, ClassLoader classLoader, SessionLog log) { | ||
+ | return null; | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public XMLEntityMappings getEntityMappings(Map<String, Object> properties, ClassLoader classLoader, SessionLog log) { | ||
+ | return XMLEntityMappingsReader.read(ORM_MAPPINGS_STR, new StringReader(inStreamAsString), xrdecl, null); | ||
+ | } | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | |||
+ | ==== org.eclipse.persistence.internal.xr.XRServiceFactory$XRPersistenceUnitInfo ==== | ||
+ | |||
+ | This inner class is passed into the constructor of <code>org.eclipse.persistence.internal.jpa.metadata.MetadataProcessor</code>. Other than an <code>XRDynamicClassLoader</code instance, all methods return null, empty lists, etc. | ||
+ | |||
+ | |||
+ | <source lang="java"> | ||
+ | /** | ||
+ | * PersistenceUnitInfo implementation to allow creation of a MetadataProcessor | ||
+ | * instance. Other than an XRDynamicClassLoader instance, all methods return | ||
+ | * null, empty lists, etc. | ||
+ | * | ||
+ | */ | ||
+ | public class XRPersistenceUnitInfo implements PersistenceUnitInfo { | ||
+ | XRDynamicClassLoader xrdecl; | ||
+ | public XRPersistenceUnitInfo(XRDynamicClassLoader loader) { | ||
+ | xrdecl = loader; | ||
+ | } | ||
+ | @Override | ||
+ | public PersistenceUnitTransactionType getTransactionType() { return null; } | ||
+ | @Override | ||
+ | public Properties getProperties() { return new Properties(); } | ||
+ | @Override | ||
+ | public URL getPersistenceUnitRootUrl() { return null; } | ||
+ | @Override | ||
+ | public String getPersistenceUnitName() { return null; } | ||
+ | @Override | ||
+ | public String getPersistenceProviderClassName() { return null; } | ||
+ | @Override | ||
+ | public DataSource getNonJtaDataSource() { return null; } | ||
+ | @Override | ||
+ | public ClassLoader getNewTempClassLoader() { return xrdecl; } | ||
+ | @Override | ||
+ | public List<String> getMappingFileNames() { return new ArrayList<String>(); } | ||
+ | @Override | ||
+ | public List<String> getManagedClassNames() { return new ArrayList<String>(); } | ||
+ | @Override | ||
+ | public DataSource getJtaDataSource() { return null; } | ||
+ | @Override | ||
+ | public List<URL> getJarFileUrls() { return new ArrayList<URL>(); } | ||
+ | @Override | ||
+ | public ClassLoader getClassLoader() { return xrdecl; } | ||
+ | @Override | ||
+ | public boolean excludeUnlistedClasses() { return false; } | ||
+ | @Override | ||
+ | public void addTransformer(ClassTransformer arg0) { } | ||
+ | @Override | ||
+ | public SharedCacheMode getSharedCacheMode() { return null; } | ||
+ | @Override | ||
+ | public ValidationMode getValidationMode() { return null; } | ||
+ | @Override | ||
+ | public String getPersistenceXMLSchemaVersion() { return null; } | ||
+ | } | ||
</source> | </source> |
Revision as of 09:34, 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)
org.eclipse.persistence.internal.xr.XRServiceFactory$JPAMetadataSource
This inner class is responsible for returning an XMLEntityMappings instance built based on given JPA metadata.
/** * Implementation of MetadataSource to allow passing JPA metadata to the * MetadataProcessor. * */ public class JPAMetadataSource implements org.eclipse.persistence.jpa.metadata.MetadataSource { XRDynamicClassLoader xrdecl; String inStreamAsString; public JPAMetadataSource(XRDynamicClassLoader loader, String inStreamAsString) { xrdecl = loader; this.inStreamAsString = inStreamAsString; } @Override public Map<String, Object> getPropertyOverrides(Map<String, Object> properties, ClassLoader classLoader, SessionLog log) { return null; } @Override public XMLEntityMappings getEntityMappings(Map<String, Object> properties, ClassLoader classLoader, SessionLog log) { return XMLEntityMappingsReader.read(ORM_MAPPINGS_STR, new StringReader(inStreamAsString), xrdecl, null); } }
org.eclipse.persistence.internal.xr.XRServiceFactory$XRPersistenceUnitInfo
This inner class is passed into the constructor of org.eclipse.persistence.internal.jpa.metadata.MetadataProcessor
. Other than an XRDynamicClassLoader</code instance, all methods return null, empty lists, etc.
/** * PersistenceUnitInfo implementation to allow creation of a MetadataProcessor * instance. Other than an XRDynamicClassLoader instance, all methods return * null, empty lists, etc. * */ public class XRPersistenceUnitInfo implements PersistenceUnitInfo { XRDynamicClassLoader xrdecl; public XRPersistenceUnitInfo(XRDynamicClassLoader loader) { xrdecl = loader; } @Override public PersistenceUnitTransactionType getTransactionType() { return null; } @Override public Properties getProperties() { return new Properties(); } @Override public URL getPersistenceUnitRootUrl() { return null; } @Override public String getPersistenceUnitName() { return null; } @Override public String getPersistenceProviderClassName() { return null; } @Override public DataSource getNonJtaDataSource() { return null; } @Override public ClassLoader getNewTempClassLoader() { return xrdecl; } @Override public List<String> getMappingFileNames() { return new ArrayList<String>(); } @Override public List<String> getManagedClassNames() { return new ArrayList<String>(); } @Override public DataSource getJtaDataSource() { return null; } @Override public List<URL> getJarFileUrls() { return new ArrayList<URL>(); } @Override public ClassLoader getClassLoader() { return xrdecl; } @Override public boolean excludeUnlistedClasses() { return false; } @Override public void addTransformer(ClassTransformer arg0) { } @Override public SharedCacheMode getSharedCacheMode() { return null; } @Override public ValidationMode getValidationMode() { return null; } @Override public String getPersistenceXMLSchemaVersion() { return null; } }