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.
EclipseLink/Development/DBWS/MetadataSupport
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$OXMMetadataSource
- 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 OXM Project
- 1.4 JPA Metadata support
- 1.4.1 org.eclipse.persistence.tools.dbws.XmlEntityMappingsGenerator
- 1.4.2 org.eclipse.persistence.internal.xr.XRServiceFactory$JPAMetadataSource
- 1.4.3 org.eclipse.persistence.internal.xr.XRServiceFactory$XRPersistenceUnitInfo
- 1.4.4 Example: <code>XMLEntityMappings generation and marshal operation
- 1.4.5 Example: Unmarshal a JPA metadata file and retrieve the ORM Project from it
- 1.5 Backwards Compatibility
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$OXMMetadataSource
This inner class holds on to anorg.eclipse.persistence.jaxb.xmlmodel.XmlBindings
instance, allowing it to be passed to the DynamicJAXBContextFactory. /** * <p>INTERNAL: * * Implementation of MetadataSource to allow passing XmlBindings * to the DynamicJAXBContextFactory * */ public class OXMMetadataSource implements MetadataSource { XmlBindings xmlbindings; public OXMMetadataSource(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 OXM 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 * @param crudOperations map of maps keyed on table name - the second map are operation name to SQL string entries */ public static XMLEntityMappings generateXmlEntityMappings(Project orProject, List<CompositeDatabaseType> complexTypes, Map<String, Map<String, String>> crudOperations) {
org.eclipse.persistence.internal.xr.XRServiceFactory$JPAMetadataSource
This inner class is responsible for returning an XMLEntityMappings instance built based on given JPA metadata.
/** * <p>INTERNAL: * * Implementation of MetadataSource to allow passing JPA metadata to the * MetadataProcessor. * */ public class JPAMetadataSource implements org.eclipse.persistence.jpa.metadata.MetadataSource { XRDynamicClassLoader xrdecl; Reader reader; public JPAMetadataSource(XRDynamicClassLoader loader, Reader reader) { xrdecl = loader; this.reader = reader; } @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, reader, 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.
/** * <p>INTERNAL: * * 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; } }
Example: <code>XMLEntityMappings generation and marshal operation
XMLEntityMappings mappings = XmlEntityMappingsGenerator.generateXmlEntityMappings(orProject, complextypes, crudOps); if (mappings != null) { XMLEntityMappingsWriter writer = new XMLEntityMappingsWriter(); writer.write(mappings, dbwsOrStream); }
Example: Unmarshal a JPA metadata file and retrieve the ORM Project from it
MetadataProcessor processor = new MetadataProcessor(new XRPersistenceUnitInfo(xrdecl), new DatabaseSessionImpl(login), xrdecl, false, true, false, false, false, null, null); processor.setMetadataSource(new JPAMetadataSource(xrdecl, DBWS_OR_STREAM.toString())); PersistenceUnitProcessor.processORMetadata(processor, true, PersistenceUnitProcessor.Mode.ALL); processor.addNamedQueries(); orProject = processor.getProject().getProject();
Backwards Compatibility
If either OXM or ORM project cannot be loaded via metadata, we will try to load the project(s) via sessions XML. This will allow existing deployments (i.e. WAR generated prior to metadata support being released) to be successfully processed at runtime.
Example: Attempt to load OXM project via sessions XML
// at this point we may have a legacy deployment XML project String oxSessionKey = xrService.name + DASH_STR + DBWS_OX_SESSION_NAME_SUFFIX; if (sessions.containsKey(oxSessionKey)) { xrService.oxSession = (Session)sessions.get(oxSessionKey); ((XMLLogin)xrService.oxSession.getDatasourceLogin()).setEqualNamespaceResolvers(false); oxProject = xrService.oxSession.getProject(); }
JPA Metadata Generated for Simple Table DDL
CREATE TABLE TABLETYPE ( ID NUMERIC(4) NOT NULL, NAME VARCHAR(25), DEPTNO DECIMAL(2,0), DEPTNAME VARCHAR2(40), PRIMARY KEY (ID) )