This chapter includes the following sections:
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. For detailed instructions on running the Coherence REST Example, see Installing Oracle Coherence.
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 (Grizzly HTTP Server, Simple HTTP Server, and Jetty 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 Grizzly HTTP Server, add the following dependencies in the in the Maven pom.xml file:
<dependencies>
<dependency>
<groupId>com.oracle.coherence</groupId>
<artifactId>coherence</artifactId>
<version>12.2.1-0-0</version>
</dependency>
<dependency>
<groupId>com.oracle.coherence</groupId>
<artifactId>coherence-rest</artifactId>
<version>12.2.1-0-0</version>
</dependency>
<dependency>
<groupId>org.glassfish.grizzly</groupId>
<artifactId>grizzly-http-server</artifactId>
<version>2.3.19</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.
Coherence REST is configured using two configuration files. The files include:
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)" for additional details.
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 Developing Applications with Oracle Coherence 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 coherence.cacheconfig system property can also be used to explicitly specify a cache configuration file. The file can also be set programmatically. See Developing Applications with Oracle Coherence 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 coherence.rest.config system property. See REST Configuration Elements, for a detailed reference of REST configuration deployment descriptor.
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:
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 address;
}
public void setAddr(AddressXml addr) {
this.addr = addr;
}
}
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 {
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 address;
}
public void setAddr(AddressJson addr) {
this.addr = addr;
}
}
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. For detailed instructions on Coherence REST security, see Securing Oracle Coherence.