Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/MOXy/Advanced XML Schema Concepts/Substitution Groups and Choices"

m (New page: {{EclipseLink_UserGuide |info=y |api=y |apis=* [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/mappings/XMLTransient.html XMLTransient] * [http://www.eclipse.org/ecl...)
 
m
Line 7: Line 7:
  
 
==Substitution Groups ==
 
==Substitution Groups ==
 +
With JAXB, you can use the element ''name'', instead of using the '''xsi:type''' attribute, to represent inheritance by using XML schema '''substitution groups'''.
  
JAXB and Inheritance - Using Substitution Groups
 
In a previous blog post I described how to leverage the xsi:type attribute to represent inheritance.  In this post I'll demonstrate how to use the element name instead by leveraging the XML Schema concept of substitution groups.
 
  
Java Model
+
In this example, the Java model contains an abstract superclass for all types of contact information:
  
The model will contain an abstract super class for all types of contact information.
+
<source lang="Java">
 
+
1
+
2
+
3
+
4
+
5
+
+
 
package blog.inheritance;
 
package blog.inheritance;
 
   
 
   
Line 27: Line 19:
 
}
 
}
  
Address and PhoneNumber will be the concrete implementations of ContactInfo.  Since we will be using the element name as the inheritance indicator we will annotate each of the sub-classes with @XmlRootElement.
+
</source>
  
1
+
 
2
+
The '''Address''' and '''PhoneNumber''' classes are the concrete implementations of '''ContactInfo'''.  Both classes use the '''@XmlRootElement'' annotation because the element name is used as the inheritance indicator.
3
+
 
4
+
<source lang="Java">
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
+
 
package blog.inheritance;
 
package blog.inheritance;
 
   
 
   
Line 67: Line 44:
 
}
 
}
  
1
 
2
 
3
 
4
 
5
 
6
 
7
 
8
 
 
package blog.inheritance;
 
 
import javax.xml.bind.annotation.XmlRootElement;
 
 
 
@XmlRootElement
 
@XmlRootElement
 
public class PhoneNumber extends ContactInfo {
 
public class PhoneNumber extends ContactInfo {
 
   
 
   
 
}
 
}
 +
</source>
  
The Customer object can have different types of contact info set on it, so the property will refer to the super class.  We will annotate the contactInfo property with @XmlElementRef to indicate the value type will be derived from the element name (and namespace URI).
 
  
1
+
Because the '''Customer'' object can have different types of contact information, the property refers to the superclass. The '''contactInfo''' property contains the '''@XmlElementRef''' annotation to specify that the value type will be derived from the element name (and namespace URI).
2
+
 
3
+
<source lang="Java">
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
+
 
package blog.inheritance;
 
package blog.inheritance;
 
   
 
   
Line 129: Line 75:
 
}
 
}
  
Demo Code
+
</source>
  
We will use the following demo code to demonstrate the use of the xsi:type attribute to represent inheritance.
 
  
1
+
This schema represents the JAXB view of the object model. The schema type inheritance matches the Java class inheritance.   
2
+
<source lang="xml">
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
+
package blog.inheritance;
+
+
import javax.xml.bind.JAXBContext;
+
import javax.xml.bind.Marshaller;
+
+
public class Demo {
+
+
    public static void main(String[] args) throws Exception {
+
        Customer customer = new Customer();
+
        Address address = new Address();
+
        address.setStreet("1 A Street");
+
        customer.setContactInfo(address);
+
+
        JAXBContext jc = JAXBContext.newInstance(Customer.class, Address.class, PhoneNumber.class);
+
+
        Marshaller marshaller = jc.createMarshaller();
+
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
+
        marshaller.marshal(customer, System.out);
+
    }
+
+
}
+
 
+
XML
+
 
+
The following is the resulting XML document.  Note that the Address object is marshalled to the address element.
+
 
+
 
+
1
+
2
+
3
+
4
+
5
+
+
<customer>
+
    <address>
+
        <street>1 A Street</street>
+
    </address>
+
</customer>
+
 
+
How does this All Work?
+
 
+
First we will take a look at the schema that represents JAXB's view on this object model. There is an inheritance among the schema types that matches the inheritance among the Java classesEach type has a corresponding global element.  The address and phoneNumber elements specify that they may be substituted for the contactInfo element.
+
 
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
+
 
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
   
 
   
Line 281: Line 121:
 
   
 
   
 
</xs:schema>
 
</xs:schema>
 +
 +
</source>
 +
 +
Notice that each '''type''' has a corresponding global element.  Additionally, the '''address''' and '''phoneNumber''' elements may be substituted for the '''contactInfo''' element.
 +
 +
 +
==Example ==
 +
 +
This example code demonstrates using the '''xsi:type''' attribute to represent inheritance:
 +
 +
<source lang="Java">
 +
 +
package blog.inheritance;
 +
 +
import javax.xml.bind.JAXBContext;
 +
import javax.xml.bind.Marshaller;
 +
 +
public class Demo {
 +
 +
    public static void main(String[] args) throws Exception {
 +
        Customer customer = new Customer();
 +
        Address address = new Address();
 +
        address.setStreet("1 A Street");
 +
        customer.setContactInfo(address);
 +
 +
        JAXBContext jc = JAXBContext.newInstance(Customer.class, Address.class, PhoneNumber.class);
 +
 +
        Marshaller marshaller = jc.createMarshaller();
 +
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
 +
        marshaller.marshal(customer, System.out);
 +
    }
 +
 +
}
 +
 +
The example produces the following XML:
 +
 +
<source lang="xml">
 +
 +
<customer>
 +
    <address>
 +
        <street>1 A Street</street>
 +
    </address>
 +
</customer>
 +
 +
</source>
 +
 +
 +
Notice that the '''Address''' object is marshalled to the '''address''' element.
 +
 +
 +
 +
 +
How does this All Work?
 +
  
 
Summary
 
Summary

Revision as of 11:58, 5 April 2011



Substitution Groups

With JAXB, you can use the element name, instead of using the xsi:type attribute, to represent inheritance by using XML schema substitution groups.


In this example, the Java model contains an abstract superclass for all types of contact information:

 
package blog.inheritance;
 
public abstract class ContactInfo {
 
}


The Address' and PhoneNumber classes are the concrete implementations of ContactInfo. Both classes use the @XmlRootElement annotation because the element name is used as the inheritance indicator.

package blog.inheritance;
 
import javax.xml.bind.annotation.XmlRootElement;
 
@XmlRootElement
public class Address extends ContactInfo {
 
    private String street;
 
    public String getStreet() {
        return street;
    }
 
    public void setStreet(String street) {
        this.street = street;
    }
 
}
 
@XmlRootElement
public class PhoneNumber extends ContactInfo {
 
}


Because the Customer object can have different types of contact information, the property refers to the superclass. The contactInfo' property contains the @XmlElementRef annotation to specify that the value type will be derived from the element name (and namespace URI).

 
package blog.inheritance;
 
import javax.xml.bind.annotation.XmlElementRef;
import javax.xml.bind.annotation.XmlRootElement;
 
@XmlRootElement
public class Customer {
 
    private ContactInfo contactInfo;
 
    @XmlElementRef
    public ContactInfo getContactInfo() {
        return contactInfo;
    }
 
    public void setContactInfo(ContactInfo contactInfo) {
        this.contactInfo = contactInfo;
    }
 
}


This schema represents the JAXB view of the object model. The schema type inheritance matches the Java class inheritance.

 
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
    <xs:element name="customer" type="customer"/>
 
    <xs:element name="contactInfo" type="contactInfo"/>
 
    <xs:element name="address" type="address"
        substitutionGroup="contactInfo"/>
 
    <xs:element name="phoneNumber" type="phoneNumber"
        substitutionGroup="contactInfo"/>
 
    <xs:complexType name="customer">
        <xs:sequence>
            <xs:element ref="contactInfo"/>
        </xs:sequence>
    </xs:complexType>
 
    <xs:complexType name="contactInfo" abstract="true">
        <xs:sequence/>
    </xs:complexType>
 
    <xs:complexType name="address">
        <xs:complexContent>
            <xs:extension base="contactInfo">
                <xs:sequence>
                    <xs:element name="street" type="xs:string" minOccurs="0"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name="phoneNumber">
        <xs:complexContent>
            <xs:extension base="contactInfo">
                <xs:sequence/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
</xs:schema>

Notice that each type has a corresponding global element. Additionally, the address and phoneNumber elements may be substituted for the contactInfo element.


Example

This example code demonstrates using the xsi:type attribute to represent inheritance:

package blog.inheritance;
 
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;
 
public class Demo {
 
    public static void main(String[] args) throws Exception {
        Customer customer = new Customer();
        Address address = new Address();
        address.setStreet("1 A Street");
        customer.setContactInfo(address);
 
        JAXBContext jc = JAXBContext.newInstance(Customer.class, Address.class, PhoneNumber.class);
 
        Marshaller marshaller = jc.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        marshaller.marshal(customer, System.out);
    }
 
}
 
The example produces the following XML:
 
<source lang="xml">
 
<customer>
    <address>
        <street>1 A Street</street>
    </address>
</customer>


Notice that the Address object is marshalled to the address element.



How does this All Work?


Summary

Not all XML binding tools support inheritance. The ones that do often use different strategies. Some include the class name of the subclass as the qualifier, this strategy makes it difficult to send the resulting XML document to another tool. JAXB on the other hand leverages existing XML schema concepts to produce very portable XML documents. In a future post I'll discuss a MOXy extension for an alternate means of representing inheritance (check out the following for a sneak peak).


Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...