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"
(→xml-write-transformer) |
(→xml-write-transformer) |
||
Line 149: | Line 149: | ||
==== xml-write-transformer ==== | ==== xml-write-transformer ==== | ||
− | Defines transformation of the attribute value to a single node value. This corresponds to a field transformer on <code>XmlTransformationMapping</code> | + | Defines transformation of the attribute value to a single node value. This corresponds to a field transformer on the <code>XmlTransformationMapping</code>. |
==== XML Schema ==== | ==== XML Schema ==== |
Revision as of 16:27, 3 August 2010
Phase 2 - Additional MOXy annotation/xml metadata support
This phase of development involves providing additional MOXy annotations and XML metadata support that will allow configuration similar to that of deployment XML
Annotations/XML Metadata
The following MOXy annotations/XML metadata will be targeted in this phase:
MOXy Annotation | XML Metadata Tag | Package | Type | Field | Method |
---|---|---|---|---|---|
XmlProperties | xml-properties | X | X | X | |
XmlProperty | xml-property | X | X | X | |
XmlTransformation | xml-transformation | X | X | ||
XmlReadTransformer | xml-read-transformer | X | X | ||
XmlWriteTransformer | xml-write-transformer | X | X | ||
XmlClassExtractor | xml-class-extractor | X |
XmlProperties
Purpose
Descriptors and mappings can contain a Map of properties. @XmlProperties
and xml-properties
will be used as a wrapper for one or more property entries. See below for additional information and examples of use.
XmlProperty
Purpose
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.
Java Metadata
TBD.
XML Metadata
xml-property
The xml-property
metadata tag will be used to configure a property.
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 property
The following example will demonstrate how a type-level 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 property
The following example will demonstrate how a property-level 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>
XmlTransformation
Purpose
Provides a means 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.
Java Metadata
TBD.
XML Metadata
xml-transformation
The xml-transformation
metadata tag will be used to configure a transformation.
xml-read-transformer
Defines transformation of node(s) value(s) into an attribute value. This corresponds to an attribute transformer on the XmlTransformationMapping
.
xml-write-transformer
Defines transformation of the attribute value to a single node value. This corresponds to a field transformer on the XmlTransformationMapping
.
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 a 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>
XmlClassExtractor
Purpose
A class extractor provides a means for complex inheritance support. A ClassExtractor instance 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.
Java Metadata
@XmlClassExtractor
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(); }
XML Metadata
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>
Example
The following example will demonstrate how a 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; } }
Testing
This section identifies the test package(s) for each feature outlined on this page.
XML Metadata
XML Metadata | Package |
---|---|
xml-properties | org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.direct
|
xml-property | org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.direct
|
xml-transformation | org.eclipse.persistence.testing.jaxb.externalizedmetadata.???
|
xml-class-extractor | org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlclassextractor
|
Annotations
Annotation | Package |
---|---|
XmlProperties | |
XmlProperty | |
XmlTransformation | |
XmlClassExtractor |
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. |