This chapter demonstrates basic tasks that are required to build and run Coherence REST applications. Many of the concepts demonstrated in this chapter are detailed in subsequent chapters.
The following sections are included in this chapter:
This chapter is organized into a set of steps that are used to configure and run a basic Coherence REST application. The steps demonstrate fundamental concepts, such as: configuring a proxy server responsible for handling HTTP request, configuring a remote cache, and using the Coherence REST API. The example in this chapter uses an embedded HTTP server in order to deploy a standalone application that does not require an application server. For details about deployment options with application servers, such as WebLogic and GlassFish, see Chapter 29, "Deploying Coherence REST."
Coherence for Java must be installed to complete the steps in this chapter. In addition, the following user-defined variables are used in this example:
DEV_ROOT - The path to root folder where user is performing all of the listed steps, or in other words all of the following folders are relative to DEV_ROOT.
COHERENCE_HOME - The path to folder containing Coherence JARs (coherence.jar and coherence-rest.jar)
Coherence REST requires both a cache and a proxy scheme. The proxy scheme must defines an HTTP acceptor to handle incoming HTTP request. The cache and proxy are configured in the cluster-side cache configuration deployment descriptor. For this example, the proxy is configured to accept client HTTP requests on localhost and port 8080. A distributed cache named dist-http-example is defined and is used to store client data in the cluster.
To configure the cluster side:
Create an XML file named example-server-config.xml in the DEV_ROOT\config folder.
Copy the following XML to the file:
<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd">
<caching-scheme-mapping>
<cache-mapping>
<cache-name>dist-http-example</cache-name>
<scheme-name>dist-http</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<distributed-scheme>
<scheme-name>dist-http</scheme-name>
<backing-map-scheme>
<local-scheme/>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>
<proxy-scheme>
<service-name>ExtendHttpProxyService</service-name>
<thread-count>5</thread-count>
<acceptor-config>
<http-acceptor>
<local-address>
<address>localhost</address>
<port>8080</port>
</local-address>
</http-acceptor>
</acceptor-config>
<autostart>true</autostart>
</proxy-scheme>
</caching-schemes>
</cache-config>
Save and close the file.
Create the Person user type, which is stored in the cache and used to demonstrate basic REST operations.
To create the Person object:
Create a text file in a DEV_ROOT\example folder.
Copy the following Java code to the file:
package example;
import java.io.Serializable;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement(name="person")
@XmlAccessorType(XmlAccessType.PROPERTY)
public class Person implements Serializable {
public Person() {}
public Person(String name, int age)
{
m_name = name;
m_age = age;
}
public String getName() { return m_name; }
public void setName(String name) { m_name = name; }
public int getAge() { return m_age; }
public void setAge(int age) { m_age = age; }
protected String m_name;
protected int m_age;
}
Save the file as Person.java and close the file.
Compile Person.java:
javac example\Person.java
The Coherence RESTful services require metadata about the cache that it exposes. The metadata includes the cache entry's key and value types as well as key converters and value marshallers. The key and value types are required in order for Coherence to be able to use built-in converters and marshallers (XML and JSON supported).
To configure the RESTful services:
Create an XML file named coherence-rest-config.xml in DEV_ROOT\config folder.
Copy the following XML to the file:
<?xml version="1.0"?>
<rest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-rest-config"
xsi:schemaLocation=
"http://xmlns.oracle.com/coherence/coherence-rest-config
coherence-rest-config.xsd">
<resources>
<resource>
<cache-name>dist-http-example</cache-name>
<key-class>java.lang.String</key-class>
<value-class>example.Person</value-class>
</resource>
</resources>
</rest>
Save and close the file
RESTful services are exposed as part of a cache server process (DefaultCacheServer). The cache server's classpath must be configured to find all the configuration files that were created in the previous steps as well as the Person.class. The classpath must also contain the required dependency libraries (see "Dependencies for Coherence REST"). For the sake of brevity, all of the above files are placed in DEV_ROOT\libs folder.
The DEV_ROOT folder should appear as follows:
/ /config /config/example-server-config.xml /config/coherence-rest-config.xml /example /example/Person.class /libs /libs/jersey-server-1.7.jar /libs/jersey-core-1.7.jar /libs/jersey-json-1.7.jar /libs/jaxb-api.jar /libs/jaxb-impl.jar /libs/jacskon-all-1.8.1.jar
The following command line starts a cache server process and explicitly names the cache configuration file created in Step 1 by using the tangosol.coherence.cacheconfig system property. In addition in sets all the needed libraries and configuration files to classpath variable:
java -cp DEV_ROOT\config;DEV_ROOT\example;DEV_ROOT\libs\jersey-server-1.7.jar;DEV_ROOT\libs\jersey-core-1.7.jar;DEV_ROOT\libs\jersey-json-1.7.jar;DEV_ROOT\libs\jaxb-api.jar;DEV_ROOT\libs\jaxb-impl.jar;DEV_ROOT\libs\jackson-all-1.8.1.jar;COHERENCE_HOME\coherence.jar;COHERENCE_HOME\coherence-rest.jar -Dtangosol.coherence.cacheconfig=DEV_ROOT\config\example-server-config.xml com.tangosol.net.DefaultCacheServer
Check the console output to verify that the proxy service has started. The output message should include the following:
(thread=Proxy:ExtendHttpProxyService:HttpAcceptor, member=1): Started: HttpAcceptor{Name=Proxy:ExtendHttpProxyService:HttpAcceptor, State=(SERVICE_STARTED), HttpServer=com.tangosol.coherence.rest.server.DefaultHttpServer, LocalAddress=localhost, LocalPort=8080, ResourceConfig=com.tangosol.coherence.rest.server.DefaultResourceConfig, RootResource=com.tangosol.coherence.rest.DefaultRootResource}
The following examples demonstrates using the Coherence RESTful API to invoke services through an HTTP client. See Chapter 28, "Using the Coherence REST API," for complete details on the Coherence RESTful API.
PUT http://localhost:8080/dist-http-example/1 Content-Type=application/json
Request Body: {"name":"chris","age":30}
PUT http://localhost:8080/dist-http-example/2 Content-Type=application/json
Request Body: {"name":"adam","age":26}
GET http://localhost:8080/dist-http-example/1.json GET http://localhost:8080/dist-http-example/1.xml GET http://localhost:8080/dist-http-example?q=name is 'adam' GET http://localhost:8080/dist-http-example;p=name GET http://localhost:8080/dist-http-example/count() GET http://localhost:8080/dist-http-example/double-average(age)
POST http://localhost:8080/dist-http-example/increment(age,1)