26 Introducing Coherence Rest

This chapter provides an introduction to Coherence REST support. Users should be familiar with Web services and JAX-RS to use Coherence REST.

The following sections are included in this chapter:

26.1 Overview of Coherence REST

Coherence REST provides easy access to Coherence caches and cache entries over HTTP protocol. It is somewhat similar to Coherence*Extend, as it allows remote clients to access data stored in Coherence without being members of the cluster themselves. However, unlike Coherence*Extend, which is a proprietary protocol that requires POF serialization to be used both on the client and within the cluster, Coherence REST uses HTTP as the underlying protocol and can marshal data in multiple representation formats, such as JSON and XML.The benefit of Coherence REST is that it allows applications written in others languages, such as Ruby and Python (that are not natively supported by Coherence), to interact with cached data.

26.2 Dependencies for Coherence REST

Coherence REST depends on the following Oracle and third-party libraries. The Jersey and Jackson JARS are included in the COHERENCE_HOME/lib directory. Grizzly JARS can be downloaded from the Grizzly project page:

http://grizzly.java.net/

Name Description License Type JAR Files
Jersey 1.8 Reference implementation of JAX-RS (JSR 311: The Java API for RESTful Web Services)
  • CDDL v1.1
  • GPL v2

  • jersey-core-1.8.jar
  • jersey-json-1.8.jar

  • jersey-server-1.8.jar

  • jersey-grizzly2-1.8.jar – must be downloaded from the Jersey Project page:

    http://jersey.java.net/

Grizzly 2.1.1 Embedded web server that integrates well with Jersey (part of Glassfish).
  • CDDL v1.1
  • GPL v2

  • grizzly-framework-2.1.1.jar
  • grizzly-http-2.1.1.jar

  • grizzly-http-server-2.1.1.jar

Jackson 1.8.1 JSON serializer Apache 2.0 jackson-all-1.8.1.jar

26.3 Overview of Configuration for Coherence REST

Coherence REST is configured using two configurations files. The files include:

  • Cache Configuration Deployment Descriptor – This file is used to define client-side cache services and the HTTP acceptor which accepts connections from remote REST clients over HTTP. The acceptor includes the address and port of the cluster-side HTTP server to which clients connects. The schema for this file is the coherence-cache-config.xsd file. See Oracle Coherence Developer's Guide for a complete reference of the <http-acceptor> element.

    At run time, the first cache configuration file that is found on the classpath is used. The tangosol.coherence.cacheconfig system property can also be used to explicitly specify a cache configuration file. The file can also be set programmatically. See Oracle Coherence Developer's Guide for general information about the cache configuration deployment descriptor.

  • REST Configuration Deployment Descriptor – This file is used to configure the Jersey resource configuration class as well as custom aggregators and custom entry processors. The default name of the descriptor is coherence-rest-config.xml and the schema is defined in the coherence-rest-config.xsd file. The file must be found on the classpath and the name can be overridden using the tangosol.coherence.rest.config system property. See Appendix A, "REST Configuration Elements," for a detailed reference of REST configuration deployment descriptor.

26.4 Understanding Data Format Support

Coherence REST supports both XML and JSON formats as input and output. To use these formats the correct bindings are required when creating a user type. Both formats are demonstrated in this section.

The following topics are included in this section:

26.4.1 Using XML as the Data Format

Objects that are represented in XML must have the appropriate JAXB bindings defined in order to be stored in a cache. The following example creates an object that uses annotations to add JAXB bindings:

@XmlRootElement(name="Address")
@XmlAccessorType(XmlAccessType.PROPERTY)
public class Address {
    private String street;
    private String city;
    private String country;

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }

    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }
}

@XmlRootElement(name="Person")
@XmlAccessorType(XmlAccessType.PROPERTY)
public class Person {
    private Long id;
    private String name;
    private Address address;
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

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

    @XmlElement(name = "address")
    public AddressXml getAddr() {
        return addr;
    }

    public void setAddr(AddressXml addr) {
        this.addr = addr;
    }
}

26.4.2 Using JSON as the Data Format

Objects that are represented in JSON must have the appropriate Jackson bindings or JAXB bindings defined in order to be stored in a cache. The default Coherence REST JSON marshaller gives priority to Jackson bindings, and if not found, fails safe to JAXB bindings. Using Jackson annotations gives user more power on controlling the output JSON format, but in case when both XML and JSON formats are needed, JAXB annotations can be enough for both formats.

The following example creates an object that uses annotations to add Jackson bindings:

@JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include= JsonTypeInfo.As.PROPERTY,
   property="@type")
public class Address {
   private String street;
   private String city;
   private String country;

   public String getStreet() {
       return street;
   }

   public void setStreet(String street) {
       this.street = street;
   }

   public String getCity() {
      return city;
   }

   public void setCity(String city) {
      this.city = city;
   }

   public String getCountry() {
      return country;
   }

   public void setCountry(String country) {
      this.country = country;
   }
}

@JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include= JsonTypeInfo.As.PROPERTY,
   property="@type")
public class Person {
   private Long id;
   private String name;
   private Address address;

   public Long getId() {
      return id;
   }

   public void setId(Long id) {
      this.id = id;
   }

   public String getName() {
      return name;
   }

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

   @JsonProperty("address")
   public AddressJson getAddr() {
      return addr;
   }

   public void setAddr(AddressJson addr) {
      this.addr = addr;
   }
}