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/DBWS/MetadataSupport"

Line 284: Line 284:
 
</source>
 
</source>
  
==== Example: <code>XMLEntityMappings</code> generation and marshal operation  ====
+
==== Example: XMLEntityMappings generation and marshal operation  ====
TBD
+
<source lang="java>
 +
    XMLContext context = new XMLContext(workbenchXMLProject);
 +
    context.getSession(orProject).getEventManager().addListener(new MissingDescriptorListener());
 +
                     
 +
    XMLEntityMappings mappings = XmlEntityMappingsGenerator.generateXmlEntityMappings(orProject, complextypes);
 +
    if (mappings != null) {
 +
        XMLEntityMappingsWriter writer = new XMLEntityMappingsWriter();
 +
        writer.write(mappings, dbwsOrStream);
 +
    }
 +
</source>
  
 
==== Example: Unmarshal a JPA metadata file and retrieve the ORM Project from it  ====
 
==== Example: Unmarshal a JPA metadata file and retrieve the ORM Project from it  ====
TBD
+
<source lang="java">
 +
    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();
 +
</source>

Revision as of 11:31, 21 February 2013

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:

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 instances
  • DBWSMetadataSource - implementation of org.eclipse.persistence.jaxb.metadata.MetadataSource to allow passing org.eclipse.persistence.jaxb.xmlmodel.XmlBindings to a org.eclipse.persistence.jaxb.dynamic.DynamicJAXBContextFactory instance
The generated metadata file will have the format:
<?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

The XmlBindingsModel 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
The following public API is required:
/**
 * 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 an org.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);
    }
}
Note that the existing marshal code in 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 an XmlBindingsModel, 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);
}
Note that the existing unmarshal code in 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 instances
  • XRPersistenceUnitInfo - implementation of javax.persistence.spi.PersistenceUnitInfo
  • JPAMetadataSource - implementation of org.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
The following public API is required:
    /**
     * 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; }
    }

Example: XMLEntityMappings generation and marshal operation

    XMLContext context = new XMLContext(workbenchXMLProject);
    context.getSession(orProject).getEventManager().addListener(new MissingDescriptorListener());
 
    XMLEntityMappings mappings = XmlEntityMappingsGenerator.generateXmlEntityMappings(orProject, complextypes);
    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();

Back to the top