Revision as of 11:13, 7 April 2011

Design Specification: Multiple Bindings File Support

ER 339373

Currently MOXy provides the ability to augment the annotation metadata with an XML bindings file. This enhancement request is for the ability to apply multiple binding files to a model.

Sample use case: 1. Initial metadata is specified with annotations. 2. Second version modifies the metadata with an XML bindings file. 3. Subsequent versions continue to modify the metadata with new bindings files.

With the metadata layered in this way a JAXBContext could be created to represent any version of the XML document.

Requirements

1. Must provide an API to allow multiple bindings files to be passed into the context creation
2. Be able to merge multiple bindings files into a single unified XmlBindings
3. Must coincide with JPA rules for overrides with multiple orm .xml files.

Configuration

Currently MOXy allows external bindings files to be passed in through a map of properties. MOXy allows one bindings file per package. The files can be passed into through the properties in 3 formats

1. A Map of Input Sources keyed on package name.
2. A list of Input Sources, one per package.
3. A single Input Source.

To support multiple bindings files for a single package, this will be changed to allow the following additional options:

1. A Map of Lists of Input Sources, keyed on package name. (Map<String, List<Object>>)
2. Allow the list of Input Sources from #2 above to contain more than entry per package.

Example: Using a single list of bindings:

....
 
FileReader bindings1 = new FileReader("base-bindings.xml");
FileReader bindings2 = new FileReader("override-bindings.xml");
 
List<Object> bindingsList = new ArrayList<Object>();
bindingsList.add(bindings1);
bindingsList.add(bindings2);
 
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, bindingsList);
 
JAXBContext ctx = JAXBContext.newInstance(new Class[]{Employee.class}, properties);
 
....

Example: Using a Map for multiple packages:

...
 
FileReader fooPackageBindings1 = new FileReader("foo/base-bindings.xml");
FileReader fooPackageBindings2 = new FileReader("foo/override-bindings.xml");
 
List<Object> fooPackageBindingsList = new ArrayList<Object>();
fooPackageBindingsList.add(bindings1);
fooPackageBindingsList.add(bindings2);
 
FileReader barPackageBindings1 = new FileReader("bar/base-bindings.xml");
FileReader barPackageBindings2 = new FileReader("bar/override-bindings.xml");
 
List<Object> barPackageBindingsList = new ArrayList<Object>();
barPackageBindingsList.add(bindings1);
barPackageBindingsList.add(bindings2);
 
Map<String, List> bindingsMap = new HashMap<String, List>
bindingsMap.put("foo", fooPackageBindingsList);
bindingsMap.put("bar", barPackageBindingsList);
 
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, bindingsMap);
 
JAXBContext ctx = JAXBContext.newInstance(new Class[]{Employee.class}, properties);

Override Rules

When multiple bindings files are encountered for the same package, a unified Bindings will be created by merging the content of all the files. The following rules will be used for merging:

• XmlSchema
  • For values such as namespace, elementform, attributeform, the later file will override
  • The list of namespace declarations from XmlNs will be merged into a single list containing all entries from all files.
    • In the case of conflicting entries (the same prefix bound to multiple namespaces, or the same namespace assigned to multiple prefixes), the last file will override the declarations from previous files win.

• JavaTypes
  • The merged bindings will contain all unique java-type entries from all bindings files
  • If the same java-type occurs in multiple files, any values that are set in the later file, will override values from the previous file
  • Properties on each java-type will be a complete override. If the same property is referenced in multiple files, the last file in the list will completely override that property.
  • Class-Level XmlJavaTypeAdpater entries will be overridden if specified in a later bindings file
  • Class-Level XmlSchemaTypes will create a merged list. If an entry for the same type is listed in multiple bindings files at this level, the last file's entry will override all previous ones.

• JavaEnums
  • The merged bindings will contain all unique java-enum entries from all bindings files
  • For any duplicated java-enums, a merged list of XmlEnumValues will be created. If an entry for the same enum facet occurs in multiple files, the last file will override the value for that facet.

• XmlJavaTypeAdapters
  • Package-Level java type adapters will be merged into a single list. In the case that an adapter is specified for the same class in multiple files, the last file's entry will win.

• XmlRegistries
  • Each unique XmlRegistry entry will be added to the final merged list of XmlRegistries
  • For any duplicated XmlRegistry entries, a merged list of XmlElementDecls will be created
    • In the case tha an XmlElementDecl for the same XmlRegistry class appears in multiple bindings docs, that XmlElementDecl will be replaced with the one from the later bindings.

• XmlSchemaTypes
  • XmlSchemaType entries will be merged into a unified list.
  • In the case that an XmlSchemaType entry for the same java-type appears at the package level in multiple bindings files, the merged bindings will only contain the entry for the last one specified.

Open Questions

1. In EclipseLink JPA multiple mappings files will be merged, but overrides at the mapping level are only allowed in a file specifically named "eclipselink-orm.xml". If a mapping for the same java property appears in multiple other mappings files, an exception is thrown. Should EclipseLink JAXB also support only merges between types and only allow mappings to be overridden by a specifically named file ("eclipselink-oxm.xml")?