This chapter provides an introduction to Coherence REST support. Users should be familiar with Web services and JAX-RS to use Coherence REST.
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 depends on the libraries listed in Table 23-1 below. The Jersey and Jackson JARS are included in the ORACLE_HOME/oracle_common/modules directory. Grizzly JARS can be downloaded from the Grizzly project page:
Table 23-1 Coherence REST Dependencies
| Name | Description | License Type | JAR Files |
|---|---|---|---|
|
Jersey 1.17.1 |
Reference implementation of JAX-RS (JSR 311: The Java API for RESTful Web Services) |
|
|
|
Grizzly 2.2.1 |
Embedded web server that integrates well with Jersey (part of Glassfish). |
|
|
|
Jackson 1.9.2 |
JSON serializer |
Apache 2.0 |
|
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 tangosol.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 tangosol.coherence.rest.config system property. See Appendix A, "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.