Revision as of 13:48, 2 December 2010

Phase 6 - Substitution Groups

Provide support for substitution groups.

Annotations

The following annotations will be targeted in this phase:

Annotation	XML Metadata Tag	Field	Method
XmlElements	xml-elements	X	X
XmlElementRef	xml-element-ref	X	X
XmlElementRefs	xml-element-refs	X	X

Example: XmlElements annotation

Java Metadata

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

org.example.Foo.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Foo {
    @javax.xml.bind.annotation.XmlElementWrapper(name="items")
    @javax.xml.bind.annotation.XmlElements({
        @javax.xml.bind.annotation.XmlElement(name="A", type=Integer.class),
        @javax.xml.bind.annotation.XmlElement(name="B", type=Float.class)
    })
    public java.util.List items;
}

XML Metadata

xml-elements

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.Foo 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.Foo">
            <xml-root-element name="foo"/>
            <java-attributes>
                <xml-elements java-attribute="items">
                    <xml-element java-attribute="A" type="java.lang.Integer" />
                    <xml-element java-attribute="B" type="java.lang.Float" />
                </xml-elements>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlElements with XmlJoinNodes

Java Metadata

The following example will demonstrate how the XmlElements annotation can be used with the XmlJoinNodes annotation:

org.example.Root.java

package org.example;
public class Root {
    @XmlElement
    @XmlPath("client")
    public List<Client> clients;
 
    @XmlElement
    @XmlPath("address")
    public List<Address> addresses;
 
    @XmlElement
    @XmlPath("phone-number")
    public List<PhoneNumber> phoneNumbers;
}

org.example.Client.java

package org.example;
public class Client {
    @XmlAttribute
    @XmlID
    public String id;
 
    @XmlElements({
        @XmlElement(name="mail", type=Address.class),
        @XmlElement(name="phone", type=PhoneNumber.class)
    })
    @XmlJoinNodesContainer({
        @XmlJoinNodes({
            @XmlJoinNode(xmlPath="mail/@id", referencedXmlPath="@aid"),
            @XmlJoinNode(xmlPath="mail/type/text()", referencedXmlPath="@type"),
        }),
        @XmlJoinNodes({
            @XmlJoinNode(xmlPath="phone/@id", referencedXmlPath="@pid"),
            @XmlJoinNode(xmlPath="phone/type/text()", referencedXmlPath="@type"),
        })
    })
    public Object preferredContactMethod;
}

@XmlJoinNodesContainer is being proposed as a container for corresponding @XmlJoinNodes entries, and does not yet exist.

org.example.PhoneNumber.java

package org.example;
public class PhoneNumber {
    @XmlAttribute(required=true)
    @XmlPath("@id")
    @XmlID
    public String id;
 
    @XmlElement(name="value")
    public String number;
 
    @XmlAttribute(required=true)
    @XmlPath("@type")
    @XmlKey
    public String type;
}

org.example.Address.java

package org.example;
public class Address {
    @XmlAttribute(required=true)
    @XmlPath("@id")
    @XmlID
    public String id;
 
    @XmlElement(name="value")
    public String address;
 
    @XmlAttribute(required=true)
    @XmlPath("@type")
    @XmlKey
    public String type;
}

XML Metadata

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the org.example.Root, org.example.Client, org.example.Address and org.example.PhoneNumber classes.

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example">
    <java-types>
        <java-type name="Root">
            <xml-root-element/>
            <java-attributes>
                <xml-element java-attribute="clients" xml-path="client" />
                <xml-element java-attribute="addresses" xml-path="address" />
                <xml-element java-attribute="phoneNumbers" xml-path="phone-number" />
            </java-attributes>
        </java-type>
        <java-type name="Client">
            <xml-root-element name="client" />
            <java-attributes>
                <xml-attribute java-attribute="id" />
                <xml-elements java-attribute="preferredContactMethod">
                    <xml-element java-attribute="mail" type="org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.choice.reference.Address" />
                    <xml-element java-attribute="phone" type="org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.choice.reference.PhoneNumber" />
                    <xml-join-nodes>
                        <xml-join-node xml-path="mail/@id" referenced-xml-path="@aid" />
                        <xml-join-node xml-path="mail/type/text()" referenced-xml-path="@type" />
                    </xml-join-nodes>
                    <xml-join-nodes>
                        <xml-join-node xml-path="phone/@id" referenced-xml-path="@pid" />
                        <xml-join-node xml-path="phone/type/text()" referenced-xml-path="@type" />
                    </xml-join-nodes>
                </xml-elements>
            </java-attributes>
        </java-type>
        <java-type name="PhoneNumber">
            <xml-root-element name="phone-number" />
            <java-attributes>
                <xml-attribute java-attribute="id" xml-path="@pid" xml-id="true" required="true" />
                <xml-attribute java-attribute="type" xml-path="@type" xml-key="true" required="true" />
                <xml-element java-attribute="number" name="value" />
            </java-attributes>
        </java-type>
        <java-type name="Address">
            <xml-root-element name="address" />
            <java-attributes>
                <xml-attribute java-attribute="id" xml-path="@aid" xml-id="true" required="true" />
                <xml-attribute java-attribute="type" xml-path="@type" xml-key="true" required="true"  />
                <xml-element java-attribute="address" name="value" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlElementRef annotation

Java Metadata

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

org.example.Foos.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Foos {
    @javax.xml.bind.annotation.XmlElementWrapper(name="items")
    @javax.xml.bind.annotation.XmlElementRef(type=Bar.class)
    public java.util.List<Bar> items;
}

org.example.Bar.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement(name="foobar")
public class Bar {
    public int id;
}

XML Metadata

xml-element-ref

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.Foos and org.example.Bar classes.

<?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.externalizedmetadata.xmlelementref.Foos">
            <xml-root-element name="foos" />
            <java-attributes>
                <xml-element-ref java-attribute="items" type="org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlelementref.Bar" >
                    <xml-element-wrapper name="items" />
                </xml-element-ref>
            </java-attributes>
        </java-type>
        <java-type name="org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlelementref.Bar">
            <xml-root-element name="foobar" />
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlElementRefs annotation

Java Metadata

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

org.example.Foos.java

package org.example;
 
import java.util.List;
 
import javax.xml.bind.JAXBElement;
import javax.xml.bind.annotation.XmlElementRef;
import javax.xml.bind.annotation.XmlElementRefs;
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlRootElement;
 
@XmlRootElement(name="my-foos")
public class Foos {
    @XmlElementWrapper(name="items")
    @XmlElementRefs({
        @XmlElementRef(name="integer-root", namespace="myns"), 
        @XmlElementRef(name="root")
    })
    public List<JAXBElement> items;
}

org.example.ObjectFactory.java

package org.example;
 
import javax.xml.bind.JAXBElement;
import javax.xml.namespace.QName;
 
@javax.xml.bind.annotation.XmlRegistry
public class ObjectFactory {
    @javax.xml.bind.annotation.XmlElementDecl(name="root")
    public JAXBElement<String> createRoot() {
        return new JAXBElement<String>(new QName("root"), String.class, "");
    }
 
    @javax.xml.bind.annotation.XmlElementDecl(namespace="myns", name="integer-root")
    public JAXBElement<Integer> createIntegerRoot() {
        return new JAXBElement<Integer>(new QName("myns", "integer-root"), Integer.class, new Integer(0));
    }
}

XML Metadata

xml-element-refs

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.Foos 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.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlelementrefs.Foos">
            <xml-root-element name="my-foos" />
            <java-attributes>
                <xml-element-refs java-attribute="items" >
                    <xml-element-wrapper name="items" />
                    <xml-element-ref name="integer-root" namespace="myns" />
                    <xml-element-ref name="root" />
                </xml-element-refs>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

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.

Difference between revisions of "EclipseLink/DesignDocs/293925/Phase6"

Revision as of 13:48, 2 December 2010

Contents

Phase 6 - Substitution Groups

Annotations

Example: XmlElements annotation

Java Metadata

org.example.Foo.java

XML Metadata

xml-elements

org/example/eclipselink-oxm.xml

Example: XmlElements with XmlJoinNodes

Java Metadata

org.example.Root.java

org.example.Client.java

org.example.PhoneNumber.java

org.example.Address.java

XML Metadata

org/example/eclipselink-oxm.xml

Example: XmlElementRef annotation

Java Metadata

org.example.Foos.java

org.example.Bar.java

XML Metadata

xml-element-ref

org/example/eclipselink-oxm.xml

Example: XmlElementRefs annotation

Java Metadata

org.example.Foos.java

org.example.ObjectFactory.java

XML Metadata

xml-element-refs

org/example/eclipselink-oxm.xml

@@ Line 88: / Line 88: @@
 </source>
-== Example: XmlElements annotation with XmlJoinNodes annotation ==
+== Example: XmlElements with XmlJoinNodes ==
 === Java Metadata  ===
@@ Line 94: / Line 94: @@
 The following example will demonstrate how the [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlElements.html XmlElements] annotation can be used with the [http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlJoinNodes.html XmlJoinNodes] annotation:
-==== org.example.Foo.java  ====
+==== org.example.Root.java ====
 <source lang="java">
 package org.example;
+public class Root {
+    @XmlElement
+    @XmlPath("client")
+    public List<Client> clients;
+    @XmlElement
+    @XmlPath("address")
+    public List<Address> addresses;
-@javax.xml.bind.annotation.XmlRootElement
+    @XmlElement
-public class Foo {
+    @XmlPath("phone-number")
-     @javax.xml.bind.annotation.XmlElementWrapper(name="items")
+    public List<PhoneNumber> phoneNumbers;
-     @javax.xml.bind.annotation.XmlElements({
+}
-         @javax.xml.bind.annotation.XmlElement(name="A", type=Integer.class),
+</source>
-         @javax.xml.bind.annotation.XmlElement(name="B", type=Float.class)
+==== org.example.Client.java ====
+<source lang="java">
+package org.example;
+public class Client {
+     @XmlAttribute
+    @XmlID
+    public String id;
+     @XmlElements({
+         @XmlElement(name="mail", type=Address.class),
+         @XmlElement(name="phone", type=PhoneNumber.class)
      })
-     public java.util.List items;
+    @XmlJoinNodesContainer({
+        @XmlJoinNodes({
+            @XmlJoinNode(xmlPath="mail/@id", referencedXmlPath="@aid"),
+            @XmlJoinNode(xmlPath="mail/type/text()", referencedXmlPath="@type"),
+        }),
+        @XmlJoinNodes({
+            @XmlJoinNode(xmlPath="phone/@id", referencedXmlPath="@pid"),
+            @XmlJoinNode(xmlPath="phone/type/text()", referencedXmlPath="@type"),
+        })
+    })
+     public Object preferredContactMethod;
+}
+</source>
+* @XmlJoinNodesContainer is being proposed as a container for corresponding @XmlJoinNodes entries, and does not yet exist.
+==== org.example.PhoneNumber.java ====
+<source lang="java">
+package org.example;
+public class PhoneNumber {
+    @XmlAttribute(required=true)
+    @XmlPath("@id")
+    @XmlID
+    public String id;
+    @XmlElement(name="value")
+    public String number;
+    @XmlAttribute(required=true)
+    @XmlPath("@type")
+    @XmlKey
+    public String type;
 }
 </source>
-=== XML Metadata  ===
+==== org.example.Address.java ====
+<source lang="java">
+package org.example;
+public class Address {
+    @XmlAttribute(required=true)
+    @XmlPath("@id")
+    @XmlID
+    public String id;
+    @XmlElement(name="value")
+    public String address;
-==== xml-elements  ====
+    @XmlAttribute(required=true)
+    @XmlPath("@type")
+    @XmlKey
+    public String type;
+}
+</source>
-If this is present in the XML then it completely replaces the corresponding annotation.
+=== XML Metadata  ===
 ==== org/example/eclipselink-oxm.xml  ====
-This XML file represents metadata overrides for the <code>org.example.Foo</code> class.
+This XML file represents metadata overrides for the <code>org.example.Root</code>, <code>org.example.Client</code>, <code>org.example.Address</code> and <code>org.example.PhoneNumber</code> classes.
 <source lang="xml">
 <?xml version="1.0" encoding="US-ASCII"?>
-<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
+<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example">
      <java-types>
-         <java-type name="org.example.Foo">
+         <java-type name="Root">
-             <xml-root-element name="foo"/>
+             <xml-root-element/>
              <java-attributes>
-                 <xml-elements java-attribute="items">
+                <xml-element java-attribute="clients" xml-path="client" />
-                     <xml-element java-attribute="A" type="java.lang.Integer" />
+                <xml-element java-attribute="addresses" xml-path="address" />
-                     <xml-element java-attribute="B" type="java.lang.Float" />
+                <xml-element java-attribute="phoneNumbers" xml-path="phone-number" />
+            </java-attributes>
+        </java-type>
+        <java-type name="Client">
+            <xml-root-element name="client" />
+            <java-attributes>
+                <xml-attribute java-attribute="id" />
+                 <xml-elements java-attribute="preferredContactMethod">
+                     <xml-element java-attribute="mail" type="org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.choice.reference.Address" />
+                     <xml-element java-attribute="phone" type="org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.choice.reference.PhoneNumber" />
+                    <xml-join-nodes>
+                        <xml-join-node xml-path="mail/@id" referenced-xml-path="@aid" />
+                        <xml-join-node xml-path="mail/type/text()" referenced-xml-path="@type" />
+                    </xml-join-nodes>
+                    <xml-join-nodes>
+                        <xml-join-node xml-path="phone/@id" referenced-xml-path="@pid" />
+                        <xml-join-node xml-path="phone/type/text()" referenced-xml-path="@type" />
+                    </xml-join-nodes>
                  </xml-elements>
+            </java-attributes>
+        </java-type>
+        <java-type name="PhoneNumber">
+            <xml-root-element name="phone-number" />
+            <java-attributes>
+                <xml-attribute java-attribute="id" xml-path="@pid" xml-id="true" required="true" />
+                <xml-attribute java-attribute="type" xml-path="@type" xml-key="true" required="true" />
+                <xml-element java-attribute="number" name="value" />
+            </java-attributes>
+        </java-type>
+        <java-type name="Address">
+            <xml-root-element name="address" />
+            <java-attributes>
+                <xml-attribute java-attribute="id" xml-path="@aid" xml-id="true" required="true" />
+                <xml-attribute java-attribute="type" xml-path="@type" xml-key="true" required="true"  />
+                <xml-element java-attribute="address" name="value" />
              </java-attributes>
          </java-type>

Breadcrumbs

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.

Difference between revisions of "EclipseLink/DesignDocs/293925/Phase6"

Revision as of 13:48, 2 December 2010

Contents

Phase 6 - Substitution Groups

Annotations

Example: XmlElements annotation

Java Metadata

org.example.Foo.java

XML Metadata

xml-elements

org/example/eclipselink-oxm.xml

Example: XmlElements with XmlJoinNodes

Java Metadata

org.example.Root.java

org.example.Client.java

org.example.PhoneNumber.java

org.example.Address.java

XML Metadata

org/example/eclipselink-oxm.xml

Example: XmlElementRef annotation

Java Metadata

org.example.Foos.java

org.example.Bar.java

XML Metadata

xml-element-ref

org/example/eclipselink-oxm.xml

Example: XmlElementRefs annotation

Java Metadata

org.example.Foos.java

org.example.ObjectFactory.java

XML Metadata

xml-element-refs

org/example/eclipselink-oxm.xml