POJO Mapping Support

Info: POJO Mapping is available starting from version 2.1.1.

Overview

The CRISP API provides POJO (Plain Old Java Object) mapping support for both JSON and XML backend data. Resource objects represent a thin abstraction over backend data formats. For JSON data, CRISP uses the Jackson library for mapping, allowing you to use Jackson annotations in your POJO classes. For XML data, CRISP uses the JAXB library, supporting JAXB annotations in your POJOs.

Mapping a Single Resource Object

To map a Resource or ResourceCollection to a POJO or a collection of POJOs, obtain a ResourceBeanMapper from the ResourceServiceBroker. The following example demonstrates this process:

// Retrieve a Resource object using resourceServiceBroker.
Resource resource = resourceServiceBroker.resolve(resourceSpace, ...);
// Obtain the ResourceBeanMapper for the resource space.
ResourceBeanMapper resourceBeanMapper = resourceServiceBroker.getResourceBeanMapper(resourceSpace);
// Map the Resource object to a POJO of type Product.
Product product = resourceBeanMapper.map(resource, Product.class);
copy

The required annotations in your POJO classes depend on whether your backend data is JSON or XML.

Mapping a Resource Collection

ResourceBeanMapper also supports mapping a ResourceCollection to a collection of POJOs:

// Retrieve a Resource object containing a collection of child product resources.
Resource productsRootResource = resourceServiceBroker.resolve(resourceSpace, ...);
// Get the child collection, where each item is a product resource.
ResourceCollection resCol = productsRootResource.getChildren();
// Map all child product resources to a collection of Product POJOs.
Collection<Product> productsCollection = resourceBeanMapper.mapCollection(resCol, Product.class);
copy

ResourceBeanMapper#mapCollection(...) provides several variations to support pagination and custom collection instantiation. The following simplified Javadocs describe the available methods:

/**
 * Map a {@link Resource} object to a bean of {@code type}.
 */
public <T> T map(Resource resource, Class<T> beanType) throws ResourceException;

/**
 * Map all the child resources of the {@link ResourceCollection} to a new collection of {@code beanType} to return.
 */
public <T> Collection<T> mapCollection(ResourceCollection resourceCollection, Class<T> beanType)
        throws ResourceException;

/**
 * Map the child resources of the {@link ResourceCollection} from the {@code offset} index
 * up to {@code limit} size at max to a new collection of {@code beanType} to return.
 */
public <T> Collection<T> mapCollection(ResourceCollection resourceCollection, Class<T> beanType, int offset,
        int limit) throws ResourceException;

/**
 * Map all the child resources of the {@link ResourceCollection} and push them to
 * the given {@code targetBeanCollection} of {@code beanType}.
 */
public <T> void mapCollection(ResourceCollection resourceCollection, Class<T> beanType,
        Collection<T> targetBeanCollection) throws ResourceException;

/**
 * Map the child resources of the {@link ResourceCollection} from the {@code offset} index
 * up to {@code limit} size at max and push them to the given {@code targetBeanCollection}.
 */
public <T> void mapCollection(ResourceCollection resourceCollection, Class<T> beanType,
        Collection<T> targetBeanCollection, int offset, int limit) throws ResourceException;
copy

POJO Mapping for JSON-based Resources

If your backend data is JSON, for example:

{
  "SKU": "4150349",
  "description": "MultiSync X431BT - 109.22 cm (43 \") , 1920 x 480, 16:4, 500 cd\/m\u00b2, 3000:1, 8 ms",
  "name": "NEC MultiSync X431BT",
  "extendedData": {
    "title": "NEC MultiSync X431BT",
    "type": "Link",
    "uri": "Incentro-HIC-Site\/-\/products\/4150349",
    "description": "MultiSync X431BT - 109.22 cm (43 \") , 1920 x 480, 16:4, 500 cd\/m\u00b2, 3000:1, 8 ms"
  }
}
copy

Define your POJO classes using Jackson annotations to control mapping:

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;

@JsonIgnoreProperties(ignoreUnknown = true)
public class Product {

    private String sku;
    private String description;
    private String name;
    private ExtendedData extendedData;

    @JsonProperty("SKU")
    public String getSKU() {
        return sku;
    }

    public void setSKU(String value) {
        this.sku = value;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String value) {
        this.description = value;
    }

    public String getName() {
        return name;
    }

    public void setName(String value) {
        this.name = value;
    }

    public ExtendedData getExtendedData() {
        return extendedData;
    }

    public void setExtendedData(ExtendedData value) {
        this.extendedData = value;
    }
}
copy

This class uses Jackson annotations to ignore unknown JSON properties and to map the "SKU" property. Refer to the Jackson documentation for details on available annotations.

public class ExtendedData {

    private String title;
    private String type;
    private String uri;
    private String description;

    public String getTitle() {
        return title;
    }

    public void setTitle(String value) {
        this.title = value;
    }

    public String getType() {
        return type;
    }

    public void setType(String value) {
        this.type = value;
    }

    public String getUri() {
        return uri;
    }

    public void setUri(String value) {
        this.uri = value;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String value) {
        this.description = value;
    }
}
copy

To map a product Resource to a Product instance:

// Retrieve a product Resource object.
Resource resource = resourceServiceBroker.resolve(resourceSpace, ...);
// Obtain the ResourceBeanMapper.
ResourceBeanMapper resourceBeanMapper = resourceServiceBroker.getResourceBeanMapper(resourceSpace);
// Map the Resource object to a Product POJO.
Product product = resourceBeanMapper.map(resource, Product.class);
copy

You can use the same approach for mapping collections with ResourceBeanMapper#mapCollection(...).

POJO Mapping for XML-based Resources

If your backend data is XML, for example:

<product>
  <SKU>4150349</SKU>
  <description>MultiSync X431BT - 109.22 cm (43 &quot;) , 1920 x 480, 16:4, 500 cd/m&#178;, 3000:1, 8 ms</description>
  <name>NEC MultiSync X431BT</name>
  <extendedData>
    <title>NEC MultiSync X431BT</title>
    <type>Link</type>
    <uri>Incentro-HIC-Site/-/products/4150349</uri>
    <description>MultiSync X431BT - 109.22 cm (43 &quot;) , 1920 x 480, 16:4, 500 cd/m&#178;, 3000:1, 8 ms</description>
  </extendedData>
</product>
copy

Define your POJO classes using JAXB annotations:

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="product")
public class Product {

    private String sku;
    private String description;
    private String name;
    private ExtendedData extendedData;

    @XmlElement(name = "SKU")
    public String getSKU() {
        return sku;
    }

    public void setSKU(String value) {
        this.sku = value;
    }

    @XmlElement
    public String getDescription() {
        return description;
    }

    public void setDescription(String value) {
        this.description = value;
    }

    @XmlElement
    public String getName() {
        return name;
    }

    public void setName(String value) {
        this.name = value;
    }

    @XmlElement
    public ExtendedData getExtendedData() {
        return extendedData;
    }

    public void setExtendedData(ExtendedData value) {
        this.extendedData = value;
    }
}
copy

This class uses JAXB annotations to map XML elements to Java fields. For more information, refer to the JAXB documentation.

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="extendedData")
public class ExtendedData {

    private String title;
    private String type;
    private String uri;
    private String description;

    @XmlElement
    public String getTitle() {
        return title;
    }

    public void setTitle(String value) {
        this.title = value;
    }

    @XmlElement
    public String getType() {
        return type;
    }

    public void setType(String value) {
        this.type = value;
    }

    @XmlElement
    public String getUri() {
        return uri;
    }

    public void setUri(String value) {
        this.uri = value;
    }

    @XmlElement
    public String getDescription() {
        return description;
    }

    public void setDescription(String value) {
        this.description = value;
    }
}
copy

To map a product Resource to a Product instance:

// Retrieve a product Resource object.
Resource resource = resourceServiceBroker.resolve(resourceSpace, ...);
// Obtain the ResourceBeanMapper.
ResourceBeanMapper resourceBeanMapper = resourceServiceBroker.getResourceBeanMapper(resourceSpace);
// Map the Resource object to a Product POJO.
Product product = resourceBeanMapper.map(resource, Product.class);
copy

You can use the same mapping methods for collections with ResourceBeanMapper#mapCollection(...).

Summary

The CRISP API provides POJO mapping for both JSON and XML data using Jackson and JAXB libraries, respectively. Use the appropriate annotations in your POJO classes to control the mapping process. To map a Resource or ResourceCollection to POJOs, retrieve a ResourceBeanMapper from the ResourceServiceBroker for the relevant resource space and use its mapping methods.