Introduction to Coherence REST

28 Introduction to Coherence REST

Before using Coherence REST, take some time learn how Coherence REST is implemented. Users should be familiar with Web services and JAX-RS to use Coherence REST.

This chapter includes the following sections:

Overview of Coherence REST
Coherence REST provides easy access to Coherence caches and cache entries over the HTTP protocol.
Dependencies for Coherence REST
The Coherence REST implementation is packaged in the COHERENCE_HOME/lib/coherence-rest.jar library and depends on the coherence.jar library.
Overview of Configuration for Coherence REST
Coherence REST is configured using the cache configuration file and the REST configuration file.
Understanding Data Format Support
Coherence REST supports both XML and JSON formats as input and output.
Authenticating and Authorizing Coherence REST Clients
Coherence REST provides both authentication and authorization to restrict access to cluster resources.

Parent topic: Using Coherence REST

Overview of Coherence REST

Coherence REST provides easy access to Coherence caches and cache entries over the HTTP protocol. It is 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, Coherence REST uses HTTP as the underlying protocol and can marshal data in both JSON and XML representation formats.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.

Coherence REST Example

The Coherence distribution includes an end-to-end example of a REST application. See Coherence REST Examples in Installing Oracle Coherence.

Parent topic: Introduction to Coherence REST

Dependencies for Coherence REST

The Coherence REST implementation is packaged in the COHERENCE_HOME/lib/coherence-rest.jar library and depends on the coherence.jar library. In addition, the Coherence REST implementation has many library dependencies and also supports various HTTP server implementations (Netty HTTP Server, Simple HTTP Server, Jetty HTTP Server, and Grizzly HTTP Server). To manage these dependencies, it is strongly recommended that applications use Maven. If you are new to Maven, see: https://maven.apache.org/.

To use Coherence REST with the Netty HTTP server, add the following dependencies in the in the Maven pom.xml file:

Note:

When copying this pom.xml for your use, update all <coherence.version> elements and <coherence.groupId> elements to match the edition and Coherence version you are using.

<dependencies>
   <dependency>
      <groupId>${coherence.groupId}</groupId>
      <artifactId>coherence</artifactId>
      <version>${coherence.version}</version>
   </dependency>
   <dependency>
      <groupId>${coherence.groupId}</groupId>
      <artifactId>coherence-rest</artifactId>
      <version>${coherence.version}</version>
   </dependency>
    <dependency>
      <groupId>${coherence.groupId}</groupId>
      <artifactId>coherence-http-netty</artifactId>
      <version>${coherence.version}</version>
   </dependency>
</dependencies>

All the required libraries are automatically downloaded. To see the complete list of libraries, run the following Maven command:

mvn dependency:list

Refer to the Coherence REST examples for a complete pom.xml file.

Parent topic: Introduction to Coherence REST

Overview of Configuration for Coherence REST

Coherence REST is configured using the cache configuration file and the REST configuration file.

Note:

When deploying Coherence REST to a JavaEE server, configuration of the web.xml file is also required. See Deploying to a Java EE Server (Generic).

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 http-acceptor in Developing Applications with Oracle Coherence.

At run time, the first cache configuration file that is found on the classpath is used. The coherence.cacheconfig system property can also be used to explicitly specify a cache configuration file. The file can also be set programmatically. See Specifying a Cache Configuration File in Developing Applications with Oracle Coherence.
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 coherence.rest.config system property. See REST Configuration Elements.

Parent topic: Introduction to Coherence REST

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.

This section includes the following topics:

Parent topic: Introduction to Coherence REST

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 implements Serializable{
    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 implements Serializable {
    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 Address getAddr() {
        return address;
    }

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

Parent topic: Understanding Data Format Support

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. If Jackson bindings are not found, JAXB bindings are used instead. Using Jackson annotations gives user more power on controlling the output JSON format. However, 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 implements Serializable {
   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 implements Serializable {
   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 Address getAddr() {
      return address;
   }

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

Parent topic: Understanding Data Format Support

Authenticating and Authorizing Coherence REST Clients

Coherence REST provides both authentication and authorization to restrict access to cluster resources. Authentication support includes both HTTP basic authentication and SSL authentication. Authorization is implemented using Coherence*Extend-styled authorization, which relies on interceptor classes that provide fine-grained access for named cache and invocation service operations. See Securing Oracle Coherence REST in Securing Oracle Coherence.

Parent topic: Introduction to Coherence REST