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/317962/Phase2.1"

(→‎xml-properties)
(→‎xml-property)
Line 64: Line 64:
 
Descriptors and mappings can contain a Map of properties. <code>@XmlProperties</code> and <code>xml-properties</code> will be used as a wrapper for one or more property entries.  See [http://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/317962/Phase2.1#XmlProperty below] for additional information and examples of use.
 
Descriptors and mappings can contain a Map of properties. <code>@XmlProperties</code> and <code>xml-properties</code> will be used as a wrapper for one or more property entries.  See [http://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/317962/Phase2.1#XmlProperty below] for additional information and examples of use.
  
−
== xml-property ==
+
== XmlProperty ==
 
=== Purpose ===
 
=== Purpose ===
−
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.
+
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 ===
+
=== Java Metadata ===
 +
 
 +
=== XML Metadata ===
 +
==== XML Schema ====
 
Since there can be multiple properties on a mapping or descriptor, and <xs:all> doesn't allow maxOccurs="unbounded", we will wrap <code>xml-property</code> in <code>xml-properties</code>.  Following are the proposed schema changes:
 
Since there can be multiple properties on a mapping or descriptor, and <xs:all> doesn't allow maxOccurs="unbounded", we will wrap <code>xml-property</code> in <code>xml-properties</code>.  Following are the proposed schema changes:
 
<source lang="xml">
 
<source lang="xml">
Line 97: Line 100:
 
*xml-transformation
 
*xml-transformation
  
−
=== Example: type-level xml-property ===
+
=== Example: type-level property ===
−
The following example will demonstrate how a type-level <code>xml-property</code> can be applied.
+
The following example will demonstrate how a type-level property can be applied.
  
 
Setting <code>xml-property</code> on a type via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] can be accomplished as follows:
 
Setting <code>xml-property</code> on a type via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] can be accomplished as follows:
Line 110: Line 113:
 
</source>
 
</source>
  
−
=== Example: property-level xml-property ===
+
=== Example: property-level property ===
−
The following example will demonstrate how a property-level <code>xml-property</code> can be applied.
+
The following example will demonstrate how a property-level property can be applied.
  
 
Setting <code>xml-property</code> on a property via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] can be accomplished as follows:
 
Setting <code>xml-property</code> on a property via [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions EclipseLink XML metadata] can be accomplished as follows:
Line 126: Line 129:
 
</java-type>
 
</java-type>
 
</source>
 
</source>
−
 
−
 
  
 
== xml-transformation ==
 
== xml-transformation ==

Revision as of 15:39, 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

XML Metadata

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>

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>

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.
Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/317962/Phase2.1&oldid=213771"

Back to the top