MOXy's Object Graphs - Input/Output Partial Models to XML & JSON

Suppose you have a domain model that you want to expose as a RESTful service.  The problem is you only want to input/output part of your data.  Previously you would have created a separate model representing  the subset and then have code to move data between the models.  In EclipseLink 2.5.0 we have a new feature called Object Graphs that enables you to easily define partial views on your model.

You can try this out today by downloading an EclipseLink 2.5.0 nightly download starting on March 24, 2013 from:

• http://www.eclipse.org/eclipselink/downloads/nightly.php

Java Model

Below is the Java model that we will use for this example.  The model represents customer data.  We will use an object graph to output just enough information so that someone could contact the customer by phone.

Customer

The @XmlNamedObjectGraph extension is used to specify subsets of the model we wish to marshal/unmarshal. This is done by specifying one or more @XmlNamedAttributeNode annotations.  If you want an object graph applied to a property you can specify a subgraph for it.  The subgraph can either be defined as a @XmlNamedSubgraph or as a @XmlNamedObjectGraph on the target class.

package blog.objectgraphs.metadata;

import java.util.List;
import javax.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.*;

@XmlNamedObjectGraph(
    name="contact info",
    attributeNodes={
        @XmlNamedAttributeNode("name"),
        @XmlNamedAttributeNode(value="billingAddress", subgraph="location"),
        @XmlNamedAttributeNode(value="phoneNumbers", subgraph="simple")
    },
    subgraphs={
        @XmlNamedSubgraph(
            name="location",
            attributeNodes = { 
                @XmlNamedAttributeNode("city"),
                @XmlNamedAttributeNode("province")
            }
        )
    }
)
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {

    @XmlAttribute
    private int id;

    private String name;

    private Address billingAddress;

    private Address shippingAddress;

    @XmlElementWrapper
    @XmlElement(name="phoneNumber")
    private List<PhoneNumber> phoneNumbers;

}

Address 

Because we defined the object graph for the Address class as a subgraph on the Customer class there is nothing we need to do here.

package blog.objectgraphs.metadata;

import javax.xml.bind.annotation.*;

@XmlAccessorType(XmlAccessType.FIELD)
public class Address {

    private String street;
    
    private String city;
    
    private String province;
    
    private String postalCode;

}

PhoneNumber 

For the phoneNumbers property on the Customer class we specified that an object graph called simple should be used to scope the data.  We will define this object graph on the PhoneNumber class.  An advantage of this approach is that it makes the object graphs easier to be reused.

package blog.objectgraphs.metadata;

import javax.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.*;

@XmlNamedObjectGraph(
    name="simple",
    attributeNodes={
        @XmlNamedAttributeNode("value"),
    }
)
@XmlAccessorType(XmlAccessType.FIELD)
public class PhoneNumber {

    @XmlAttribute
    private String type;
    
    @XmlValue
    private String value;

}

Demo Code

Demo

In the demo code below we will read in an XML document to fully populate our Java model.  After marshalling it out to prove that everything was fully mapped we will specify an object graph on the marshaler (line 22), and output a subset to both XML and JSON.

package blog.objectgraphs.metadata;

import java.io.File;
import javax.xml.bind.*;
import org.eclipse.persistence.jaxb.MarshallerProperties;

public class Demo {

    public static void main(String[] args) throws Exception {
        JAXBContext jc = JAXBContext.newInstance(Customer.class);
        
        Unmarshaller unmarshaller = jc.createUnmarshaller();
        File xml = new File("src/blog/objectgraphs/metadata/input.xml");
        Customer customer = (Customer) unmarshaller.unmarshal(xml);
        
        // Output XML
        Marshaller marshaller = jc.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        marshaller.marshal(customer, System.out);
        
        // Output XML - Based on Object Graph
        marshaller.setProperty(MarshallerProperties.OBJECT_GRAPH, "contact info");
        marshaller.marshal(customer, System.out);

        // Output JSON - Based on Object Graph
        marshaller.setProperty(MarshallerProperties.MEDIA_TYPE, "application/json");
        marshaller.setProperty(MarshallerProperties.JSON_INCLUDE_ROOT, false);
        marshaller.setProperty(MarshallerProperties.JSON_WRAPPER_AS_ARRAY_NAME, true);
        marshaller.marshal(customer, System.out);
    }

}

input.xml/Output 

We will use the following document to populate our domain model.  We will also marshal it back out to demonstrate that all of the content is actually mapped.

<?xml version="1.0" encoding="UTF-8"?>
<customer id="123">
   <name>Jane Doe</name>
   <billingAddress>
      <street>1 A Street</street>
      <city>Any Town</city>
      <province>Ontario</province>
      <postalCode>A1B 2C3</postalCode>
   </billingAddress>
   <shippingAddress>
      <street>2 B Road</street>
      <city>Another Place</city>
      <province>Quebec</province>
      <postalCode>X7Y 8Z9</postalCode>
   </shippingAddress>
   <phoneNumbers>
      <phoneNumber type="work">555-1111</phoneNumber>
      <phoneNumber type="home">555-2222</phoneNumber>
   </phoneNumbers>
</customer>

XML Output Based on Object Graph

The XML below was produced by the exact same model as the previous XML document.  The difference is that we leveraged a named object graph to select a subset of the mapped content.

<?xml version="1.0" encoding="UTF-8"?>
<customer>
   <name>Jane Doe</name>
   <billingAddress>
      <city>Any Town</city>
      <province>Ontario</province>
   </billingAddress>
   <phoneNumbers>
      <phoneNumber>555-1111</phoneNumber>
      <phoneNumber>555-2222</phoneNumber>
   </phoneNumbers>
</customer>

JSON Output Based on Object Graph

Below is the same subset as the previous XML document represented as JSON.  We have used the new JSON_WRAPPER_AS_ARRAY_NAME property (see Binding to JSON & XML - Handling Collections) to improve the representation of collection values.

{
   "name" : "Jane Doe",
   "billingAddress" : {
      "city" : "Any Town",
      "province" : "Ontario"
   },
   "phoneNumbers" : [ "555-1111", "555-2222" ]
}

External Metadata 

MOXy also offers an external binding document which allows you to provide metadata for third party objects or apply alternate mappings for your model (see: Mapping Object to Multiple XML Schemas - Weather Example).  Below is the mapping document for this example.

<?xml version="1.0"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
    package-name="blog.objectgraphs.metadata"
    xml-accessor-type="FIELD">
    <java-types>
        <java-type name="Customer">
            <xml-named-object-graphs>
                <xml-named-object-graph name="contact info">
                    <xml-named-attribute-node name="name"/>
                    <xml-named-attribute-node name="billingAddress" subgraph="location"/>
                    <xml-named-attribute-node name="phoneNumbers" subgraph="simple"/>
                    <xml-named-subgraph name="location">
                        <xml-named-attribute-node name="city"/>
                        <xml-named-attribute-node name="province"/>
                    </xml-named-subgraph>
                </xml-named-object-graph>
            </xml-named-object-graphs>
            <xml-root-element/>
            <java-attributes>
                <xml-attribute java-attribute="id"/>
                <xml-element java-attribute="phoneNumbers" name="phoneNumber">
                    <xml-element-wrapper/>
                </xml-element>
            </java-attributes>
        </java-type>
        <java-type name="PhoneNumber">
            <xml-named-object-graphs>
                <xml-named-object-graph name="simple">
                    <xml-named-attribute-node name="value"/>
                </xml-named-object-graph>
            </xml-named-object-graphs>
            <java-attributes>
                <xml-attribute java-attribute="type"/>
                <xml-value java-attribute="value"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Further Reading

If you enjoyed this post then you may also be interested in:

• Specifying EclipseLink MOXy as Your JAXB Provider
• Extending JAXB - Representing Metadata as XML
• JSON Binding with EclipseLink MOXy - Twitter Example