Dali/Indigo/MOXy 2.1

From Eclipsepedia

< Dali‎ | Indigo
Revision as of 10:55, 15 October 2010 by Paul.fullbright.oracle.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Functional Specification: Support for MOXy 2.1

[enter bug location here]

Document History

Date Author Version Description & Notes
10-13-2010 Paul Fullbright Draft

Feature overview

This feature is about supporting MOXy 2.1 features in Dali

Goals:

  • 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

Concepts

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.

References

MOXy oxm.xml support for 2.0

MOXy oxm.xml support for 2.1

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

MOXy xml-customizer documentation

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

MOXy xml-inverse-reference documentation

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

MOXy xml-map documentation

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

MOXy xml-access-methods documentation

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, write-only

MOXy read-only documentation MOXy write-only documentation

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

MOXy xml-path documentation

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

MOXy xml-null-policy metadata documentation MOXy xml-is-set-null-policy metadata documentation

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

MOXy cdata metadata documentation

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.