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/DesignDocs/277920"

m (→‎Annotations)
m (→‎XML Any Attribute Mapping)
Line 749: Line 749:
 
</xml-any-attribute-mapping>
 
</xml-any-attribute-mapping>
 
</source>
 
</source>
 +
 +
=== XML Attribute
  
 
== Testing ==
 
== Testing ==

Revision as of 14:14, 29 September 2009

Design Specification: OXM XSD

ER 277920

Document History

Date Author Version Description & Notes
2009/05/26 Blaise Doughan Skeleton

Project overview

Overview of the project/feature. Why is it desired, what are its goals.

Goals:

  • goal 1
  • goal 2

Concepts

Present any concepts relevant to the feature.

Requirements

The following sections will expand the goals of this project into more concrete requirements.

Design Constraints

JAXB Annotations

The XML should have the same feel as the JAXB annotations.

javax.xml.bind.annotation Javadoc

EclipseLink JPA Metadata

The XML should have the same feel as the equivalent XML for EclipseLink JPA

EclipseLink JPA XSD

EclipseLink MOXy Metadata

At a minimum the metadata available in EclipseLink 1.1 must be available in the new format (see below).

XML Direct Mapping

<xml-direct-mapping
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<null-value>String</null-value>
	<converter/>
	<attribute-classification>String</attribute-classification>
	<is-cdata>1</is-cdata>
	<null-policy>
		<xsi-nil-represents-null>false</xsi-nil-represents-null>
		<empty-node-represents-null>false</empty-node-represents-null>
		<null-representation-for-xml>XSI_NIL</null-representation-for-xml>
	</null-policy>
</xml-direct-mapping>

XML Composite Direct Collection Mapping

<xml-composite-direct-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<value-converter/>
	<value-converter-class>String</value-converter-class>
	<container>
		<collection-type>String</collection-type>
	</container>
	<is-cdata>1</is-cdata>
</xml-composite-direct-collection-mapping>

XML Composite Object Mapping

<xml-composite-object-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<field name="String"/>
	<container-attribute>Text</container-attribute>
	<container-get-method>Text</container-get-method>
	<container-set-method>Text</container-set-method>
	<null-policy>
		<xsi-nil-represents-null>false</xsi-nil-represents-null>
		<empty-node-represents-null>false</empty-node-represents-null>
		<null-representation-for-xml>XSI_NIL</null-representation-for-xml>
	</null-policy>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-composite-object-mapping>

XML Composite Collection Mapping

<xml-composite-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
	<container-attribute>Text</container-attribute>
	<container-get-method>Text</container-get-method>
	<container-set-method>Text</container-set-method>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-composite-collection-mapping>

XML Object Reference Mapping

<xml-object-reference-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<allow-null>true</allow-null>
	<field-translations>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
	</field-translations>
	<source-to-target-key-field-association>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
	</source-to-target-key-field-association>
	<source-to-target-key-fields>
		<field name="String"/>
		<field name="String"/>
	</source-to-target-key-fields>
</xml-object-reference-mapping>

XML Collection Reference Mapping

<xml-collection-reference-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<allow-null>true</allow-null>
	<field-translations>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
	</field-translations>
	<source-to-target-key-field-association>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
	</source-to-target-key-field-association>
	<source-to-target-key-fields>
		<field name="String"/>
		<field name="String"/>
	</source-to-target-key-fields>
	<containerpolicy>
		<collection-type>String</collection-type>
	</containerpolicy>
	<uses-single-node>1</uses-single-node>
</xml-collection-reference-mapping>

XML Binary Data Mapping

<xml-binary-data-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<null-value>String</null-value>
	<converter/>
	<attribute-classification>String</attribute-classification>
	<is-cdata>1</is-cdata>
	<null-policy>
		<xsi-nil-represents-null>false</xsi-nil-represents-null>
		<empty-node-represents-null>false</empty-node-represents-null>
		<null-representation-for-xml>XSI_NIL</null-representation-for-xml>
	</null-policy>
	<is-swa-ref>1</is-swa-ref>
	<mime-type>String</mime-type>
	<should-inline-data>1</should-inline-data>
</xml-binary-data-mapping>

XML Binary Data Collection Mapping

XML Any Object Mapping

<xml-any-object-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<use-xml-root>false</use-xml-root>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-any-object-mapping>

XML Any Collection Mapping

<xml-any-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
	<use-xml-root>false</use-xml-root>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-any-collection-mapping>

XML Fragment Mapping

<xml-fragment-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<null-value>String</null-value>
	<converter/>
	<attribute-classification>String</attribute-classification>
	<is-cdata>1</is-cdata>
	<null-policy>
		<xsi-nil-represents-null>false</xsi-nil-represents-null>
		<empty-node-represents-null>false</empty-node-represents-null>
		<null-representation-for-xml>XSI_NIL</null-representation-for-xml>
	</null-policy>
</xml-fragment-mapping>

XML Fragment Collection

<xml-fragment-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
</xml-fragment-collection-mapping>

XML Choice Object Mapping

<xml-choice-object-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
</xml-choice-object-mapping>

XML Choice Collection Mapping

<xml-choice-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<container-policy>
		<collection-type>String</collection-type>
	</container-policy>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
</xml-choice-collection-mapping>

XML Transformation Mapping

<xml-transformation-mapping xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<attribute-method>String</attribute-method>
	<attribute-transformer>String</attribute-transformer>
	<mutable>true</mutable>
	<indirection/>
	<field-transformations>
		<field-transformation>
			<field name="String"/>
		</field-transformation>
		<field-transformation>
			<field name="String"/>
		</field-transformation>
	</field-transformations>
</xml-transformation-mapping>

XML Any Attribute Mapping

<xml-any-attribute-mapping xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
	<include-namespace-declaration>1</include-namespace-declaration>
	<include-schema-instance>1</include-schema-instance>
</xml-any-attribute-mapping>

Null Policy

<null-policy>
    <xsi-nil-represents-null>false</xsi-nil-represents-null>
    <empty-node-represents-null>false</empty-node-represents-null>
    <null-representation-for-xml>XSI_NIL</null-representation-for-xml>
</null-policy>

Design / Functionality

Boot Strapping

Default Behaviour

When creating a JAXBContext an eclipselink-oxm.xml file will be looked for, for each item on the context path. 

JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader);

The ClassLoader parameter will be used to find the eclipselink-oxm.xml file in a manner similar to: 

InputStream externalizedMetadata1 = 
     aClassLoader.getResourceAsStream("org/example/customer/eclipselink-oxm.xml";
InputStream externalizedMetadata2 = 
     aClassLoader.getResourceAsStream("org/example/employee/eclipselink-oxm.xml";

Specifying the Externalized Metadata File

If you want to override the name and location of the externalized metadata this can be done through a property when creating the JAXBContext. 

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("eclipselink.oxm.metadata", 
     "org/example/employee/metadata.xml:org/example/customer/metadata.xml");

If the property is specified then no eclipselink-oxm.xml files will be looked for, only the specified files will be used. 

JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);

Use of the property is the only means of using the externalized metadata when creating the JAXBContext based on an array of classes. 

Class[] classes = new Class[3];
classes[0] = Customer.class;
classes[1] = Employee.class;
classes[2] = Address.class;
JAXBContext.newInstance(classes, properties);

Common Mapping Metadata

XML Schema

<xs:complexType name="xml-mapping">
	<xs:all>
		<xs:element ref="properties"/>
	</xs:all>
	<xs:attribute name="attribute-name" type="xs:string"/>
	<xs:attribute name="get-method" type="xs:string"/>
	<xs:attribute name="set-method" type="xs:string"/>
	<xs:attribute name="read-only" type="xs:boolean" default="false"/>
</xs:complexType>
 
<xs:element name="properties">
	<xs:complexType>
		<xs:sequence>
			<xs:element name="property" minOccurs="0" maxOccurs="unbounded">
				<xs:complexType>
					<xs:attribute name="name" type="xs:string"/>
					<xs:attribute name="value" type="xs:string"/>
				</xs:complexType>
			</xs:element>
		</xs:sequence>
	</xs:complexType>
</xs:element>

XML

<xml-mapping 
	attribute-name="String" 
	read-only="false" 
	get-method="String" 
	set-method="String">
	<properties>
		<property name="String" value="String"/>
		<property name="String" value="String"/>
	</properties>
</xml-mapping>

XML Any Attribute Mapping

Annotations

@XmlAnyAttribute
@IncludeNamespaceDeclaration(value=true)
@IncludeSchemaInstance(value=true)

XML Schema

<xs:element name="xml-any-attribute-mapping">
	<xs:complexType>
		<xs:complexContent>
			<xs:extension base="xml-mapping">
				<xs:attribute name="include-namespace-declaration" type="xs:boolean"/>
				<xs:attribute name="include-schema-instance" type="xs:boolean"/>
			</xs:extension>
		</xs:complexContent>
	</xs:complexType>
</xs:element>

XML

<xml-any-attribute-mapping 
	attribute-name="String"
	read-only="false"
	get-method="String"
	set-method="String"
	include-namespace-declaration="true" 
	include-schema-instance="true">
	<properties>
		<property name="String" value="String"/>
	</properties>
</xml-any-attribute-mapping>

=== XML Attribute

Testing

API

GUI

Config files

Documentation

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Issue # Owner Description / Notes

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Issue # Description / Notes Decision

Future Considerations

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/277920&oldid=172649"

Back to the top