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

(API)
(Note/Issues)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Document History  ==
 
== Document History  ==
 
* April 26, 2013 - Initial Draft
 
* April 26, 2013 - Initial Draft
 +
* May 17, 2013 - Updated after initial checkin
  
 
== Requirements  ==
 
== Requirements  ==
Line 15: Line 16:
 
public String name;
 
public String name;
  
@XmlVariableNode(attributeName="thingName")
+
@XmlVariableNode("thingName")
 
public List<Thing> things;
 
public List<Thing> things;
 
}
 
}
Line 98: Line 99:
 
== External Bindings ==
 
== External Bindings ==
 
<source lang="java">
 
<source lang="java">
     <xs:element name="xml-variable-element" substitutionGroup="java-attribute">
+
     <xs:element name="xml-variable-node" substitutionGroup="java-attribute">
 
         <xs:complexType>
 
         <xs:complexType>
 
             <xs:complexContent>
 
             <xs:complexContent>
Line 105: Line 106:
 
                         <xs:element ref="xml-access-methods" minOccurs="0" />
 
                         <xs:element ref="xml-access-methods" minOccurs="0" />
 
                         <xs:element ref="xml-java-type-adapter" minOccurs="0"/>
 
                         <xs:element ref="xml-java-type-adapter" minOccurs="0"/>
 +
                        <xs:element ref="xml-element-wrapper" minOccurs="0"/>
 
                         <xs:element ref="xml-properties" minOccurs="0" />
 
                         <xs:element ref="xml-properties" minOccurs="0" />
                        <xs:element ref="xml-element-refs" minOccurs="0" />
 
 
                     </xs:all>
 
                     </xs:all>
                     <xs:attribute name="xml-mixed" type="xs:boolean" default="false" />
+
                     <xs:attribute name="xml-path" type="xs:string" />
                    <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="read-only" type="xs:boolean" default="false" />
 
                     <xs:attribute name="write-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:attribute name="container-type" type="xs:string" default="##default" />
 
                     <xs:attribute name="type" type="xs:string" default="##default" />
 
                     <xs:attribute name="type" type="xs:string" default="##default" />
    <xs:attribute name="java-attribute" type="xs:string"  />
+
                    <xs:attribute name="isAttribute" type="xs:boolean" default="false" />
 +
                    <xs:attribute name="java-variable-attribute" type="xs:string"  />
 +
                    <xs:attribute name="nillable" type="xs:boolean" default="false" />
 +
                    <xs:attribute name="required" type="xs:boolean" default="false" />
 
                 </xs:extension>
 
                 </xs:extension>
 
             </xs:complexContent>
 
             </xs:complexContent>
Line 127: Line 128:
 
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
 
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
 
<java-types>
 
<java-types>
<java-type name="org.eclipse.persistence.testing.jaxb.xmlvariableelement.RootNoAnnotations">
+
<java-type name="org.eclipse.persistence.testing.jaxb.xmlvariablenode.RootNoAnnotations">
 +
            <xml-root-element name="root" />
 
             <java-attributes>
 
             <java-attributes>
                 <xml-variable-element java-attribute="things" java-variable-attribute="thingName">
+
                 <xml-variable-node java-attribute="things" java-variable-attribute="thingName"/>
                    <!--xml-java-type-adapter value="org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlanyelement.MyDomAdapter" /-->
+
                </xml-variable-element>
+
 
             </java-attributes>
 
             </java-attributes>
 
</java-type>
 
</java-type>
Line 139: Line 139:
  
 
== Design  ==
 
== Design  ==
A new mapping will be created XMLVariableXPathMapping and it will extend the AnyCollectionMapping
+
2 new mappings will be created XMLVariableXPathObjectMapping and XMLVariableXPathCollectionMapping it will extend the CompositeMappings
  
This mapping will assume that the key names are unique so will never write ['s in JSON
+
The Annotation will be allowed on Single objects as well as lists or maps and can be used in conjunction with several other annotations like XmlElementWrapper, Xpath and XmlJavaTypeAdapter.  When used with an adapter the variable attribute must exist on the adapted type.
  
This annotation only makes sense when the referenced type is a complex thing.  An exception will be thrown if this annotation is used on a simple object or List of simple things.
+
When specified on a Map property the variable attribute will be used as the key in the map
 +
 
 +
For Schema generation when this is present an xs:any will be added to the xsd
 +
 
 +
Exception Cases
 +
*This annotation only makes sense when the referenced type is a complex thing.  An exception will be thrown if this annotation is used on a simple object or List of simple things.
 +
*The variable attribute can only be a simple thing - String, QName or Number type
 +
*The value of the variable attribute can not be null - exception will be thrown
  
 
== Limitations  ==
 
== Limitations  ==
Line 149: Line 156:
  
 
==  Note/Issues  ==
 
==  Note/Issues  ==
*inheritance
+
 
*List<Object>
+
*single case ie:not on a collection XMLVariableXPathObjectMapping XMLVariableXPathCollectionMapping
+
*external bindings
+
 
*don`t write out that property itself as nested if it is the variable field - currently need to mark that property as transient.
 
*don`t write out that property itself as nested if it is the variable field - currently need to mark that property as transient.
*startcollection and endcollection [ ]'s in JSON
 
*could specify get/set method instead of attribute
 
*in conjunction with adapters?
 
*elementwrapper
 
*schemagen
 
 
*Binder
 
*Binder
*isnil  nullpolicy
 
*map
 
*map <a,b> doesn't automatically pull in B
 

Latest revision as of 13:08, 17 May 2013

Document History

  • April 26, 2013 - Initial Draft
  • May 17, 2013 - Updated after initial checkin

Requirements

Example

@XmlRootElement
public class Root {
 
	public String name;
 
	@XmlVariableNode("thingName")
	public List<Thing> things;
}
 
public class Thing {
        @XmlTransient
	public String thingName;
	public String thingValue;
}
Root r = new Root();
r.name = "theRootName";
r.things = new ArrayList<Thing>();
Thing thing1 = new Thing();
thing1.thingName = "thinga";
thing1.thingValue = "thingavalue";
 
Thing thing2 = new Thing();
thing2.thingName = "thingb";
thing2.thingValue = "thingbvalue";
 
Thing thing3 = new Thing();
thing3.thingName = "thingc";
thing3.thingValue = "thingcvalue";
r.things.add(thing1);
r.things.add(thing2);
r.things.add(thing3);
marshaller.marshal(r, System.out)
XML
<root>
   <name>theRootName</name>
   <thinga>
       <thingValue>thingavalue</thingValue>
   </thinga>
   <thingb>
       <thingValue>thingbvalue</thingValue>
   </thingb>
   <thingc>
       <thingValue>thingcvalue</thingValue>
   </thingc>
</root>
marshaller.marshal(r, System.out)
JSON
{"root":{
   "name":"theRootName"
   "thinga":{
       "thingValue":"thingavalue"},   
   "thingb":{
       "thingValue":"thingbvalue"},
   "thingc":{
       "thingValue":"thingcvalue"}
}}

API

The following annotation will be added
org.eclipse.persistence.oxm.annotations.XmlVariableNode

@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface XmlVariableNode {
 
    String value() default "##default";
 
    Class type() default DEFAULT.class;   
 
    static final class DEFAULT {}
 
    boolean attribute() default false;
}

External Bindings

     <xs:element name="xml-variable-node" 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-element-wrapper" minOccurs="0"/>
                        <xs:element ref="xml-properties" minOccurs="0" />
                    </xs:all>
                    <xs:attribute name="xml-path" type="xs:string" />
                    <xs:attribute name="read-only" type="xs:boolean" default="false" />
                    <xs:attribute name="write-only" type="xs:boolean" default="false" />
                    <xs:attribute name="container-type" type="xs:string" default="##default" />
                    <xs:attribute name="type" type="xs:string" default="##default" />
                    <xs:attribute name="isAttribute" type="xs:boolean" default="false" />
                    <xs:attribute name="java-variable-attribute" type="xs:string"  />
                    <xs:attribute name="nillable" type="xs:boolean" default="false" />
                    <xs:attribute name="required" type="xs:boolean" default="false" />
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
 <?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
	<java-types>
		<java-type name="org.eclipse.persistence.testing.jaxb.xmlvariablenode.RootNoAnnotations">
            <xml-root-element name="root" />
            <java-attributes>
                <xml-variable-node java-attribute="things" java-variable-attribute="thingName"/>
            </java-attributes>
		</java-type>
	</java-types>
</xml-bindings>

Design

2 new mappings will be created XMLVariableXPathObjectMapping and XMLVariableXPathCollectionMapping it will extend the CompositeMappings

The Annotation will be allowed on Single objects as well as lists or maps and can be used in conjunction with several other annotations like XmlElementWrapper, Xpath and XmlJavaTypeAdapter. When used with an adapter the variable attribute must exist on the adapted type.

When specified on a Map property the variable attribute will be used as the key in the map

For Schema generation when this is present an xs:any will be added to the xsd

Exception Cases

  • This annotation only makes sense when the referenced type is a complex thing. An exception will be thrown if this annotation is used on a simple object or List of simple things.
  • The variable attribute can only be a simple thing - String, QName or Number type
  • The value of the variable attribute can not be null - exception will be thrown

Limitations

Since this makes use of the any logic during unmarshal and MOXy only handles one Any mapping on a class if a class makes use of the XmlVariableNode annotation then that class can not have XmlAnyElement annotations or any other variables that would cause AnyObject or AnyCollection mappings to be created. Potential future considerations would be to allow multiple XmlVariableNode annotations on the same object with some type of regular expression/pattern to differentiate them.

Note/Issues

  • don`t write out that property itself as nested if it is the variable field - currently need to mark that property as transient.
  • Binder

Copyright © Eclipse Foundation, Inc. All Rights Reserved.