Functional Specification: Support for MOXy 2.1
[enter bug location here]
|Date||Author||Version Description & Notes|
This feature is about supporting MOXy 2.1 features in Dali
- Add MOXy 2.1 platform
- Add support for oxm.xml file
- Support oxm.xml content type
- Associate oxm.xml files with package/namespaces
- Support MOXy 2.1 oxm.xml features
EclipseLink MOXy 2.0 introduced support for oxm.xml files, which act similarly to orm.xml files. They provide standalone support for mapping java classes to XML document data sources and they work in conjunction with JAXB (and soon MOXy) annotations to add and override metadata.
Users associate each file with a package when creating a JAXBContext as such:
InputStream employeeExternalizedMetadata = aClassLoader.getResourceAsStream("org/example/employee/metadata.xml"; InputStream customerExternalizedMetadata = aClassLoader.getResourceAsStream("org/example/customer/metadata.xml"; HashMap<String, Source> metadataSourceMap = new HashMap<String, Source>(); metadataSourceMap.put("org.example.employee", new StreamSource(employeeExternalizedMetadata)); metadataSourceMap.put("org.example.customer", new StreamSource(customerExternalizedMetadata)); Map<String, Map<String, Source>> properties = new HashMap<String, Map<String, Source>>(); properties.put("eclipselink-oxm-xml", metadataSourceMap); JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);
It therefore seems to place the requirement on Dali to associate each file with a package in order to accurately support them.
There are no additional annotations in MOXy 2.1, so the added functionality is almost entirely oxm.xml.
Requirements / Functionality
oxm.xml content type
oxm.xml content type will need to be created similar to orm.xml content type. A resource model will need to be created.
file to package association
In order to correctly associate the files with the packages they represent, we will likely need additional project metadata.
MOXy 2.1 oxm.xml features
MOXy provides support to parallel most/all JAXB 2.x annotations in the 2.1 oxm.xml, but there are additional features specific to MOXy.
xml-customizer appears on java-type elements. An xml-customizer names a class that implements DescriptorCustomizer, which is a catch-all option for users that can't configure their mapping information with metadata alone.
xml-inverse-reference is a new java attribute type mapping, used to point back up to container objects. Instead of specifying an XML construct to map this attribute, you only refer to the mapping in the target class that maps the relationship. A java attribute is allowed to be mapped by an xml-element or an xml-attribute used as an xml-idref.
- mapped-by - specifies the attribute in the target class that maps the relationship
- xml-access-methods - see below
xml-map appears on xml-element elements. (I *believe*) it is used to specify/override the key and value types for default java.util.Map mappings. java.util.Map java attributes are mapped to default schema structures as defined in the spec sect. 8.12.6. This default mapping depends on the parameterized key/value types of the attribute's Map<K,V> specification. This setting allows users to specify these type in the case that there are no parameterized types specified, or to override them if they are.
xml-access-methods appears on most attribute mappings (xml-attribute, xml-any-attribute, xml-element(s), xml-any-element, xml-inverse-reference, xml-value) but not xml-element-ref(s). it's a fifth access type (other than NONE, PUBLIC_MEMBER, FIELD, or PROPERTY) that allows for the possibility that there isn't even a java representative of the attribute (e.g. there may be readFoo() and writeFoo(Foo) on the class, but no "foo" field, and no get/setFoo property).
read-only and write-only appear on most attribute mappings (xml-attribute, xml-any-attribute, xml-element(s), xml-any-element, xml-value) but not xml-element-ref(s) or xml-inverse-reference. If an attribute is read-only, then only unmarshalling is supported. If an attribute is write-only, then only marshalling is supported.
xml-path appears on xml-attribute, xml-any-attribute, xml-element, and xml-any-element, and allows for finer control in specifying the attribute or element tag that is written to.
xml-null-policy/xml-is-set-null-policy appear on xml-attribute, xml-element, and xml-value attribute mappings. I believe the null policies are primarily about handling how null is represented in XML metadata, but still looking for documentation on this. (TO BE FILLED IN)
cdata appears on xml-element and xml-value attribute mappings. It is a boolean setting that indicates whether or not the data is written to the XML with CDATA encoding. It is only intended for use with simple types.