Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/DesignDocs/317962/Phase2.1"
m (→org.example.Person.java) |
(→Purpose) |
||
Line 55: | Line 55: | ||
== xml-property == | == xml-property == | ||
=== Purpose === | === Purpose === | ||
− | The <code>xml-property</code> element provides a means to set a property on a mapping or descriptor. | + | The <code>xml-property</code> element provides a means to set a property on a mapping or descriptor. Any annotations set on a property will be completely replaced by XML. Any annotations set on a type will be merged with XML, with XML taking precedence in the case of a conflict. |
=== XML Schema === | === XML Schema === |
Revision as of 15:40, 30 July 2010
Phase 2.1 - Additional MOXy external metadata support
This phase of development involves providing additional MOXy external metadata support that will allow configuration similar to that of deployment XML
XML Metadata Tags
The following XML metadata tags will be targeted in this phase:
XML Metadata Tag | MOXy Annotation | Package | Type | Field | Method |
---|---|---|---|---|---|
xml-property | XmlProperty | X | X | X | |
xml-transformation | XmlTransformation | X | X | ||
xml-read-transformer | XmlReadTransformer | X | X | ||
xml-write-transformer | XmlWriteTransformer | X | X | ||
xml-class-extractor | XmlClassExtractor | X |
xml-property
Purpose
The xml-property
element provides a means to set a property on a mapping or descriptor. Any annotations set on a property will be completely replaced by XML. Any annotations set on a type will be merged with XML, with XML taking precedence in the case of a conflict.
XML Schema
Since there can be multiple properties on a mapping or descriptor, and <xs:all> doesn't allow maxOccurs="unbounded", we will wrap xml-property
in xml-properties
. Following are the proposed schema changes:
<xs:element name="xml-properties" type="xml-properties" /> <xs:complexType name="xml-properties"> <xs:sequence> <xs:element name="xml-property" minOccurs="0" maxOccurs="unbounded" > <xs:complexType> <xs:attribute name="name" type="xs:string" use="required" /> <xs:attribute name="value" type="xs:string" use="required" /> <xs:attribute name="value-type" type="xs:string" default="java.lang.String" /> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType>
An element ref to the new global xml-properties
element will be added to the following:
- java-type
- xml-any-attribute
- xml-attribute
- xml-any-element
- xml-element
- xml-elements
- xml-element-ref
- xml-element-refs
- xml-inverse-reference
- xml-value
- xml-transformation
Example: type-level xml-property
The following example will demonstrate how a type-level xml-property
can be applied.
Setting xml-property
on a type via EclipseLink XML metadata can be accomplished as follows:
<java-type name="org.example.Employee"> <xml-properties> <xml-property name="identifier" value="101" value-type="Integer.class" /> <xml-property name="isTrue" value="false" value-type="Boolean.class" /> </xml-properties> </java-type>
Example: property-level xml-property
The following example will demonstrate how a property-level xml-property
can be applied.
Setting xml-property
on a property via EclipseLink XML metadata can be accomplished as follows:
<java-type name="org.example.Employee"> <java-attributes> <xml-element java-attribute="myelement"> <xml-properties> <xml-property name="isAttribute" value="false" value-type="Boolean.class" /> <xml-property name="comment" value="this is an element" /> </xml-properties> </xml-element> </java-attributes> </java-type>
xml-transformation
Purpose
The xml-transformation
element is used to configure an org.eclipse.persistence.oxm.mappings.XMLTransformationMapping. Transformation mappings are used to create a custom mapping where one or more XML nodes can be used to create the object to be stored in a Java class's attribute.
XML Schema
Following is the proposed schema structure for xml-transformation
:
<xs:element name="xml-transformation" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element name="xml-access-methods" type="xml-access-methods" minOccurs="0"/> <!-- xs:element name="xml-accessor-type" type="xml-access-type" minOccurs="0"/ --> <xs:element name="xml-properties" minOccurs="0"> <xs:complexType> <xs:sequence> <xs:element ref="xml-property" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="xml-read-transformer"> <xs:complexType> <xs:attribute name="method" type="xs:string" /> <xs:attribute name="transformer-class" type="xs:string" /> </xs:complexType> </xs:element> <xs:element name="xml-write-transformer" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="method" type="xs:string" /> <xs:attribute name="xml-path" type="xs:string" /> <xs:attribute name="transformer-class" type="xs:string" /> </xs:complexType> </xs:element> </xs:all> <xs:attribute name="attribute-type" type="xs:string" /> <!-- xs:attribute name="fetch" type="orm:fetch-type"/ --> <xs:attribute name="mutable" type="xs:boolean" default="false"/> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="optional" type="xs:boolean" default="false"/> <xs:attribute name="xml-accessor-type" type="xml-access-type" minOccurs="0" default="PUBLIC_MEMBER"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
Example
The following example will demonstrate how xml-transformation
can be applied.
Setting xml-transformation
via EclipseLink XML metadata can be accomplished as follows:
<java-type name="org.example.Employee"> <java-attributes> <xml-transformation java-attribute="hours" optional="true"> <xml-read-transformer transformer-class="org.example.NormalHoursTransformer" /> <xml-write-transformer xml-path="normal-hours/start-time/text()" transformer-class="org.example.StartTimeTransformer"/> <xml-write-transformer xml-path="normal-hours/end-time/text()" transformer-class="org.example.EndTimeTransformer"/> <xml-access-methods get-method="getNormalHours" set-method="setNormalHours" /> </xml-transformation> </java-attributes> </java-type>
xml-class-extractor
Purpose
The xml-class-extractor
element provides a means for complex inheritance support. A class extractor is registered with the descriptor to override the default inheritance mechanism. This allows for a user defined class indicator in place of providing an explicit class indicator field. The instance registered must extend the org.eclipse.persistence.descriptors.ClassExtractor
class and implement the extractClassFromRow(Record, Session)
method; this method is used to determine which class to instantiate when unmarshalling.
XML Schema
Following is the proposed schema structure for xml-class-extractor
- a global element/complex type pair will be added, and a ref will be added to java-type
:
<xs:element name="xml-class-extractor" type="xml-class-extractor" /> <xs:complexType name="xml-class-extractor"> <xs:attribute name="class" type="xs:string" use="required"/> </xs:complexType>
Annotation
The following is the proposed source code for the XmlClassExtractor annotation:
@Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface XmlClassExtractor { /** * (Required) Defines the name of the class extractor that should be * applied to this entity's descriptor. */ Class value(); }
Example
The following example will demonstrate how the xml-class-extractor
can be applied.
Setting xml-class-extractor
via EclipseLink XML metadata can be accomplished as follows:
<java-type name="org.example.Person"> <xml-class-extractor class="org.example.MyClassExtractor" /> </java-type>
Setting the Class Extractor via Annotations would be accomplished as follows:
org.example.Person.java
package org.example; @XmlClassExtractor(MyClassExtactor.class) class Person { String name; }
org.example.Employee.java
package org.example; class Employee extends Person { String id; }
org.example.MyClassExtractor.java
package org.example; class MyClassExtractor extends org.eclipse.persistence.descriptors.ClassExtractor { /** * This method simply returns Employee.class. Typically, the class to be * returned would be based on the given Record. */ public static Class extractClassFromRow(Record databaseRow, Session session) { return Employee.class; } }
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 |
---|---|---|
1 | xml-class-extraction-method | We will not provide support for setting a class extraction method name on the InheritancePolicy. Please refer to this bug for additional information. |