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/Phase4"

(→‎xml-any-element with xml-element-ref(s))
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
= Phase 4 (page under construction) =
+
<div style="border: 1px solid rgb(0, 0, 0); margin: 5px; padding: 5px; float: right;">__TOC__</div>
 +
= Phase 4 - Any/Choice Content =
  
−
Provide support for high level metadata.  
+
Provide support for wild card data.
  
 
== Annotations  ==
 
== Annotations  ==
Line 7: Line 8:
 
The following annotations will be targetted in this phase:  
 
The following annotations will be targetted in this phase:  
  
−
{| border="1" style="width: 100%;" class="wikitable"
+
{|{{BMTableStyle}}
−
|+ <br>
+
|-{{BMTHStyle}}
−
|-
+
 
! Annotation  
 
! Annotation  
 +
! XML Metadata Tag
 
! Package  
 
! Package  
 
! Type  
 
! Type  
Line 16: Line 17:
 
! Method
 
! Method
 
|-
 
|-
−
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlElementWrapper.html XmlElementWrapper<br>]  
+
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlElementWrapper.html XmlElementWrapper]  
−
| &nbsp;  
+
| xml-element-wrapper
−
| &nbsp;  
+
| align="center" | &nbsp;  
−
| X  
+
| align="center" | &nbsp;  
−
| X
+
| align="center" | X  
 +
| align="center" | X
 +
|-
 +
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlList.html XmlList]
 +
| xml-list
 +
| align="center" | &nbsp;
 +
| align="center" | &nbsp;
 +
| align="center" | X
 +
| align="center" | X
 +
|-
 +
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlValue.html XmlValue]
 +
| xml-value
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" | X
 
|-
 
|-
−
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlList.html XmlList<br>]  
+
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlAnyElement.html XmlAnyElement]  
−
| &nbsp;  
+
| xml-any-element
−
| &nbsp;  
+
| align="center" | &nbsp;  
−
| X  
+
| align="center" | &nbsp;  
−
| X
+
| align="center" | X  
 +
| align="center" | X
 
|-
 
|-
−
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlValue.html XmlValue<br>]  
+
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlAnyAttribute.html XmlAnyAttribute]  
−
|  
+
| xml-any-attribute
−
|  
+
| align="center" | &nbsp;
−
| X  
+
| align="center" | &nbsp;
−
| X
+
| align="center" | X  
 +
| align="center" | X
 
|-
 
|-
−
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlAnyElement.html XmlAnyElement<br>]  
+
| [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlMixed.html XmlMixed]  
−
| &nbsp;  
+
| xml-mixed
−
| &nbsp;  
+
| align="center" | &nbsp;  
−
| X  
+
| align="center" | &nbsp;  
−
| X
+
| align="center" | X  
 +
| align="center" | X
 
|}
 
|}
  
Line 72: Line 91:
 
==== xml-list  ====
 
==== xml-list  ====
  
−
If this is present in the XML then the true/false value set via the corresponding annotation is ignored.
+
If this is present in the XML then the corresponding annotation is ignored.
  
 
==== org/example/eclipselink-oxm.xml  ====
 
==== org/example/eclipselink-oxm.xml  ====
Line 116: Line 135:
  
 
==== xml-value  ====
 
==== xml-value  ====
−
 
−
An @XmlValue annotation cannot be un-set via XML.  Hence, all @XmlValue annotations will be processed in addition to all xml-value entries in XML (for a given class).  Note that only one field/property can be set as @XmlValue or xml-value on a given class.
 
  
 
==== org/example/eclipselink-oxm.xml  ====
 
==== org/example/eclipselink-oxm.xml  ====
Line 205: Line 222:
 
==== xml-any-element  ====
 
==== xml-any-element  ====
  
−
If this is present in the XML then it completely replaces the corresponding annotation. An @XmlAnyElement annotation cannot be un-set via XML.  Hence, all @XmlAnyElement annotations will be processed in addition to all xml-any-element entries in XML (for a given class).  Note that only one field/property can be set as @XmlAnyElement or xml-any-element on a given class.
+
If this is present in the XML then it completely replaces the corresponding annotation.
  
 
==== org/example/eclipselink-oxm.xml  ====
 
==== org/example/eclipselink-oxm.xml  ====
Line 221: Line 238:
 
     </java-type>
 
     </java-type>
 
   </java-types>
 
   </java-types>
 +
</xml-bindings>
 +
</source>
 +
 +
==== xml-any-element with xml-element-ref(s) ====
 +
<code>xml-any-element</code> can be used with <code>xml-element-ref(s)</code> by nesting the <code>xml-element-refs</code> declaration within the <code>xml-any-element</code> structure.  For example:
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="US-ASCII"?>
 +
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
 +
  <java-types>
 +
      <java-type name="org.example.Employee">
 +
        <xml-root-element name="emp" />
 +
        <java-attributes>
 +
            <xml-any-element java-attribute="stuff">
 +
              <xml-element-refs>
 +
                  <xml-element-ref name="a" type="java.lang.String" />
 +
                  <xml-element-ref name="b" type="java.lang.Integer" />
 +
              </xml-element-refs>
 +
            </xml-any-element>
 +
        </java-attributes>
 +
      </java-type>
 +
  </java-types>
 +
</xml-bindings>
 +
</source>
 +
It is assumed here that <code>java-attribute</code> will be set on the enclosing <code>xml-any-element</code>.  If <code>java-attribute</code> is set on the enclosed <code>xml-element-refs</code> it will not be processed.
 +
 +
==== Proposed XSD changes ====
 +
An <code>xml-element-refs</code> element ref will be added to <code>xml-any-element</code>.  We will not support <code>xml-element-ref</code> on its own - in the case where a single <code>xml-element-ref</code> is desired it must be wrapped in an <code>xml-element-refs</code>.  This limitation is necessary due to the fact that the <code>element</code> declarations are in an <code>all</code> which does not support <code>choice</code>.  Switching the <code>all</code> to a <code>sequence</code> would allow for a <code>choice</code>, and hence the ability to have <code>xml-element-refs</code> OR <code>xml-element-ref</code>, but this could potentially cause errors in existing instance documents as <code>sequence</code> forces ordering of elements.
 +
<source lang="xml">
 +
<xs:element name="xml-any-element" substitutionGroup="java-attribute">
 +
  <xs:complexType>
 +
      <xs:complexContent>
 +
        <xs:extension base="java-attribute">
 +
            <xs:all>
 +
              <xs:element ref="xml-access-methods" minOccurs="0" />
 +
              <xs:element ref="xml-java-type-adapter" minOccurs="0"/>
 +
              <xs:element ref="xml-properties" minOccurs="0" />
 +
              <xs:element ref="xml-element-refs" minOccurs="0" />
 +
            </xs:all>
 +
            <xs:attribute name="xml-mixed" type="xs:boolean" default="false" />
 +
            <xs:attribute name="lax" type="xs:boolean" default="false" />
 +
            <xs:attribute name="dom-handler" type="xs:string" default="javax.xml.bind.annotation.W3CDomHandler" />
 +
            <xs:attribute name="read-only" type="xs:boolean" default="false" />
 +
            <xs:attribute name="write-only" type="xs:boolean" default="false" />
 +
            <xs:attribute name="xml-path" type="xs:string" />
 +
            <xs:attribute name="container-type" type="xs:string" default="##default" />
 +
        </xs:extension>
 +
      </xs:complexContent>
 +
  </xs:complexType>
 +
</xs:element>
 +
</source>
 +
 +
== Example: XmlAnyAttribute annotation ==
 +
 +
=== Java Metadata  ===
 +
 +
The following example will demonstrate how the [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlAnyAttribute.html XmlAnyAttribute] annotation can be applied:
 +
 +
==== org.example.Employee.java  ====
 +
 +
<source lang="java">
 +
package org.example;
 +
 +
import javax.xml.namespace.QName;
 +
 +
@javax.xml.bind.annotation.XmlRootElement
 +
public class Employee {
 +
    public int a;
 +
    public String b;
 +
   
 +
    @javax.xml.bind.annotation.XmlAnyAttribute
 +
    public java.util.Map<QName, Object> stuff;
 +
}
 +
</source>
 +
 +
=== XML Metadata  ===
 +
 +
==== xml-any-attribute  ====
 +
 +
If this is present in the XML then the associated property will be treated as an Any property.
 +
 +
==== org/example/eclipselink-oxm.xml  ====
 +
 +
This XML file represents metadata overrides for the "org.example.Employee" class.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="US-ASCII"?>
 +
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
 +
    <java-types>
 +
        <java-type name="org.example.Employee">
 +
            <xml-root-element name="employee" />
 +
            <java-attributes>
 +
                <xml-any-attribute java-attribute="stuff" />
 +
            </java-attributes>
 +
        </java-type>
 +
    </java-types>
 +
</xml-bindings>
 +
</source>
 +
 +
== Example: XmlMixed annotation ==
 +
 +
=== Java Metadata  ===
 +
 +
The following example will demonstrate how the [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlMixed.html XmlMixed] annotation can be applied:
 +
 +
==== org.example.Employee.java  ====
 +
 +
<source lang="java">
 +
package org.example;
 +
 +
@javax.xml.bind.annotation.XmlRootElement
 +
public class Employee {
 +
    public int a;
 +
    public String b;
 +
   
 +
    @javax.xml.bind.annotation.XmlAnyElement
 +
    @javax.xml.bind.annotation.XmlMixed
 +
    public java.util.List<Object> stuff;
 +
}
 +
</source>
 +
 +
=== XML Metadata  ===
 +
 +
==== xml-mixed  ====
 +
 +
If this is present, and set to "true", in the XML then the associated property will be treated as containing mixed content.
 +
 +
==== org/example/eclipselink-oxm.xml  ====
 +
 +
This XML file represents metadata overrides for the "org.example.Employee" class.
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="US-ASCII"?>
 +
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
 +
    <java-types>
 +
        <java-type name="org.example.Employee">
 +
            <xml-root-element name="employee" />
 +
            <java-attributes>
 +
                <xml-any-element java-attribute="stuff" xml-mixed="true"/>
 +
            </java-attributes>
 +
        </java-type>
 +
    </java-types>
 
</xml-bindings>
 
</xml-bindings>
 
</source>
 
</source>

Latest revision as of 10:59, 20 October 2010

Phase 4 - Any/Choice Content

Provide support for wild card data.

Annotations

The following annotations will be targetted in this phase:

Annotation XML Metadata Tag Package Type Field Method
XmlElementWrapper xml-element-wrapper     X X
XmlList xml-list     X X
XmlValue xml-value X X
XmlAnyElement xml-any-element     X X
XmlAnyAttribute xml-any-attribute     X X
XmlMixed xml-mixed     X X

Example: XmlElementWrapper and XmlList annotations

Java Metadata

The following example will demonstrate how the XmlElementWrapper and XmlList annotations can be applied:

org.example.Employee.java

package org.example;
 
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlList;
 
public class Employee {
    @XmlElementWrapper(name="my-digits", namespace="urn:employee", nillable=true, required=true)
    public int[] digits;
 
    @XmlList
    public java.util.List<String> data;
}

XML Metadata

xml-element-wrapper

If this is present in the XML then it completely replaces the corresponding annotation.

xml-list

If this is present in the XML then the corresponding annotation is ignored.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class. 

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
  <java-types>
    <java-type name="org.example.Employee">
        <java-attributes>
            <xml-element java-attribute="digits">
                <xml-element-wrapper name="my-digits" namespace="urn:employee" nillable="true" required="true" />
            </xml-element>
            <xml-element java-attribute="data" xml-list="true" />
        </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

Example: XmlValue annotation

Java Metadata

The following example will demonstrate how the XmlValue annotation can be applied:

org.example.Employee.java

package org.example;
 
import javax.xml.bind.annotation.XmlValue;
 
public class Employee {
    @XmlValue
    public java.math.BigDecimal salary;
}

XML Metadata

xml-value

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class. 

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
  <java-types>
    <java-type name="org.example.Employee">
        <java-attributes>
            <xml-value java-attribute="salary" />
        </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

Example: XmlAnyElement annotation

Java Metadata

The following example will demonstrate how the XmlAnyElement annotation can be applied:

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public int a;
    public String b;
 
    @javax.xml.bind.annotation.XmlAnyElement(lax=true, value=org.example.MyDomHandler.class)
    public java.util.List<Object> stuff;
}

org.example.MyDomHandler.java

package org.example;
 
import javax.xml.bind.ValidationEventHandler;
import javax.xml.bind.annotation.DomHandler;
import javax.xml.bind.annotation.W3CDomHandler;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.dom.DOMResult;
 
import org.w3c.dom.Element;
 
/**
 * This handler simply wraps a W3CDomHandler.
 */
public class MyDomHandler implements DomHandler {
    W3CDomHandler theHandler;
 
    public MyDomHandler() {
        theHandler = new W3CDomHandler();
    }
 
    public Result createUnmarshaller(ValidationEventHandler errorHandler) {
        return theHandler.createUnmarshaller(errorHandler);
    }
 
    public Object getElement(Result rt) {
        if (rt instanceof DOMResult) {
            return theHandler.getElement((DOMResult) rt);
        }
        return null;
    }
 
    public Source marshal(Object n, ValidationEventHandler errorHandler) {
        if (n instanceof Element) {
            return theHandler.marshal((Element) n, errorHandler);
        }
        return null;
    }
}

XML Metadata

xml-any-element

If this is present in the XML then it completely replaces the corresponding annotation.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class. 

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
  <java-types>
    <java-type name="org.example.Employee">
      <java-attributes>
        <xml-any-element java-attribute="stuff" lax="true" dom-handler="org.example.MyDomHandler"/>
      </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

xml-any-element with xml-element-ref(s)

xml-any-element can be used with xml-element-ref(s) by nesting the xml-element-refs declaration within the xml-any-element structure. For example: 

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
   <java-types>
      <java-type name="org.example.Employee">
         <xml-root-element name="emp" />
         <java-attributes>
            <xml-any-element java-attribute="stuff">
               <xml-element-refs>
                  <xml-element-ref name="a" type="java.lang.String" />
                  <xml-element-ref name="b" type="java.lang.Integer" />
               </xml-element-refs>
            </xml-any-element>
         </java-attributes>
      </java-type>
   </java-types>
</xml-bindings>

It is assumed here that java-attribute will be set on the enclosing xml-any-element. If java-attribute is set on the enclosed xml-element-refs it will not be processed.

Proposed XSD changes

An xml-element-refs element ref will be added to xml-any-element. We will not support xml-element-ref on its own - in the case where a single xml-element-ref is desired it must be wrapped in an xml-element-refs. This limitation is necessary due to the fact that the element declarations are in an all which does not support choice. Switching the all to a sequence would allow for a choice, and hence the ability to have xml-element-refs OR xml-element-ref, but this could potentially cause errors in existing instance documents as sequence forces ordering of elements. 

<xs:element name="xml-any-element" substitutionGroup="java-attribute">
   <xs:complexType>
      <xs:complexContent>
         <xs:extension base="java-attribute">
            <xs:all>
               <xs:element ref="xml-access-methods" minOccurs="0" />
               <xs:element ref="xml-java-type-adapter" minOccurs="0"/>
               <xs:element ref="xml-properties" minOccurs="0" />
               <xs:element ref="xml-element-refs" minOccurs="0" />
            </xs:all>
            <xs:attribute name="xml-mixed" type="xs:boolean" default="false" />
            <xs:attribute name="lax" type="xs:boolean" default="false" />
            <xs:attribute name="dom-handler" type="xs:string" default="javax.xml.bind.annotation.W3CDomHandler" />
            <xs:attribute name="read-only" type="xs:boolean" default="false" />
            <xs:attribute name="write-only" type="xs:boolean" default="false" />
            <xs:attribute name="xml-path" type="xs:string" />
            <xs:attribute name="container-type" type="xs:string" default="##default" />
         </xs:extension>
      </xs:complexContent>
   </xs:complexType>
</xs:element>

Example: XmlAnyAttribute annotation

Java Metadata

The following example will demonstrate how the XmlAnyAttribute annotation can be applied:

org.example.Employee.java

package org.example;
 
import javax.xml.namespace.QName;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public int a;
    public String b;
 
    @javax.xml.bind.annotation.XmlAnyAttribute
    public java.util.Map<QName, Object> stuff;
}

XML Metadata

xml-any-attribute

If this is present in the XML then the associated property will be treated as an Any property.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class. 

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-any-attribute java-attribute="stuff" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlMixed annotation

Java Metadata

The following example will demonstrate how the XmlMixed annotation can be applied:

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public int a;
    public String b;
 
    @javax.xml.bind.annotation.XmlAnyElement
    @javax.xml.bind.annotation.XmlMixed
    public java.util.List<Object> stuff;
}

XML Metadata

xml-mixed

If this is present, and set to "true", in the XML then the associated property will be treated as containing mixed content.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class. 

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-any-element java-attribute="stuff" xml-mixed="true"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>
Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/277920/Phase4&oldid=224420"

This page was last modified 10:59, 20 October 2010 by David McCann.

Back to the top