27 Deploying Coherence REST

This chapter provides instructions for deploying Coherence REST to an embedded HTTP server and WebLogic Server. Generic servlet container instructions are also provided. For details on securing Coherence REST, seeSecuring Oracle Coherence .

This chapter includes the following sections:

27.1 Deploying with the Embedded HTTP Server

Coherence provides multiple embedded HTTP server implementations that can be used to host REST Web services:

DefaultHttpServer (backed by Oracle's lightweight HTTP server)
GrizzlyHttpServer (backed by Grizzly HTTP server and recommended for production environments)
SimpleHttpServer (backed by Simple HTTP server)
JettyHttpServer (backed by Jetty HTTP server)

See "Changing the Embedded HTTP Server" for details on changing the default HTTP server.

The HTTP server must be enabled on a Coherence proxy server. To enable the HTTP server, edit the proxy's cache configuration file and add an <http-acceptor> element, within the <proxy-scheme> element, and include the host and port for the HTTP server.

The following example configures the HTTP server to accept requests on localhost 127.0.0.1 and port 8080. The example explicitly defines the HTTP server class and Jersey resource configuration class and uses / as the context path for the Coherence REST application. However; these are default values and need not be included. The context path can be changed as required and additional Coherence REST applications can be defined with different context paths. See Developing Applications with Oracle Coherence for a detailed reference of all <http-acceptor> subelements.

<proxy-scheme>
   <service-name>ExtendHttpProxyService</service-name>
   <acceptor-config>
      <http-acceptor>
         <class-name>
            com.tangosol.coherence.rest.server.DefaultHttpServer</class-name>
         <local-address>
            <address>127.0.0.1</address>
            <port>8080</port>
         </local-address>
         <resource-config>
            <context-path>/</context-path>
            <instance>
               <class-name>
                  com.tangosol.coherence.rest.server.DefaultResourceConfig
               </class-name>
            </instance>
         </resource-config>
      </http-acceptor>
   </acceptor-config>
   <autostart>true</autostart>
</proxy-scheme>

If you are using POF, make sure that the pof-config.xml file includes the location of the REST POF types. For details, see "Configuring REST Server Access to POF-Enabled Services."

27.2 Deploying to WebLogic Server

WebLogic Server includes a Coherence integration that standardizes the way Coherence applications are packaged, deployed, and managed within a WebLogic Server domain. Coherence REST must follow the integration standards. For details on configuring a Coherence cluster in a WebLogic Server domain, see Administering Clusters for Oracle WebLogic Server. In addition, Coherence applications must be packaged as a Grid ARchive (GAR). For details on creating a GAR, see, Developing Oracle Coherence Applications for Oracle WebLogic Server.

This section contains the following tasks:

27.2.1 Task 1: Configure a WebLogic Server Domain for Coherence REST

Create a managed Coherence server in your WebLogic Server domain that will host Coherence REST. The server should be configured as a storage disabled member of a Coherence cluster. If more than one managed Coherence server is required for a Coherence REST solution, the servers should be managed as a tier in a WebLogic Server cluster. For details on configuring managed Coherence servers, see Administering Clusters for Oracle WebLogic Server.

27.2.2 Task 2: Package the Coherence REST Web Application

To package the Coherence REST Web application:

Create a Web application directory structure as follows:
```
/
/WEB-INF/
/WEB-INF/classes/
/WEB-INF/lib/
```

Create a Web application deployment descriptor (web.xml) and include a servlet definition for the REST application as follows:

Note:

A default servlet context listener is included in the coherence-rest.jar that shuts down the cluster member during the REST application shutdown. The listener is registered as shown below. If the cluster member is not shut down, a variety of exceptions are thrown post shutdown.

<web-app>
   ...
   <listener>
      <listener-class>
         com.tangosol.coherence.rest.servlet.DefaultServletContextListener
      </listener-class>
   </listener>
   <servlet>
      <servlet-name>Coherence REST</servlet-name>
      <servlet-class>org.glassfish.jersey.servlet.ServletContainer
      </servlet-class>
      <init-param>
         <param-name>javax.ws.rs.Application</param-name>
         <param-value>
            com.tangosol.coherence.rest.server.ContainerResourceConfig
         </param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>Coherence REST</servlet-name>
      <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>
      ...
</web-app>

Save the web.xml file to the /WEB-INF/ directory.
Create a WAR file using the jar utility. For example, issue the following command from a command prompt at the root of the Web application directory:
```
jar -cvf coherence_rest.war *
```

27.2.3 Task 3: Package the Coherence Application

To package the Coherence application:

Copy the coherence-rest-config.xml file to the root of your Coherence application. The structure should be as follows:

/
/com/myco/MyClass.class
/lib/
/META-INF/
/META-INF/coherence-application.xml
/META-INF/coherence-cache-config.xml
/META-INF/pof-config.xml
coherence-rest-config.xml

Edit the pof-config.xml file to include the coherence-rest-pof-config.xml POF configuration file that contains the Coherence REST default user types. For details, see "Configuring REST Server Access to POF-Enabled Services."
Create a GAR file using the jar utility. For example, issue the following command from a command prompt at the root of the GAR directory:
```
jar -cvf MyCohApp.gar *
```

27.2.4 Task 4: Package the Enterprise Application

To package the enterprise application:

Create an enterprise application directory structure and copy the Coherence REST WAR file and the Coherence application GAR file to the root of the EAR. For example:
```
/
/META-INF/
/META-INF/application.xml
/META-INF/weblogic-application.xml
/coherence_rest.war
/MyCohApp.gar
```

Edit the application.xml file and add a module definition for the Coherence REST Web application. For example:

<application>
   <module>
      <web>
         <web-uri>coherence_rest.war</web-uri>
         <context-root>/</context-root>
      </web>
   </module>
</application>

Edit the weblogic-application.xml file and add a library reference for the coherence-rest.jar shared library and a module reference for the Coherence application GAR file. For example:

<weblogic-application>
   <module>
      <name>person</name>
      <type>GAR</type>
      <path>MyCohApp.gar</path>
   </module>
   <library-ref>
      <library-name>coherence-rest</library-name>
   </library-ref>
</weblogic-application>

Create the EAR file using the jar utility. For example, issue the following command from a command prompt at the root of the EAR directory:
```
jar -cvf MyCohRestApp.ear *
```

27.2.5 Task 5: Deploy the Enterprise Application

To deploy the Enterprise application:

Use the WebLogic Server Administration Console or WLST tool to deploy the EAR to the managed Coherence server created in Task 1.
From a browser, verify the deployment by navigating to the managed Coherence server's listening port and include the cache name as part of the URL. For example: http://host:port/rest/{cacheName}.

27.3 Deploying to a Java EE Server (Generic)

This section provides instructions for deploying Coherence Rest to a Java EE environment:

The following topics are included in this section:

27.3.1 Packaging Coherence REST for Deployment

To package a Coherence REST application:

Create a basic Web application directory structure as follows:
```
/
/WEB-INF
/WEB-INF/classes
/WEB-INF/lib
```
Copy the coherence.jar and coherence-rest.jar libraries from the COHERENCE_HOME/lib directory to the /WEB-INF/lib directory.
Copy the Coherence REST dependencies from the ORACLE_HOME/oracle_common/modules/ directory to the /WEB-INF/lib directory. For the list of dependencies, see "Dependencies for Coherence REST").

Create a Web application deployment descriptor (web.xml) and include a servlet definition for the REST application as follows:

Note:

<web-app>
   ...
   <listener>
      <listener-class>
         com.tangosol.coherence.rest.servlet.DefaultServletContextListener
      </listener-class>
   </listener>
   <servlet>
      <servlet-name>Coherence REST</servlet-name>
      <servlet-class>org.glassfish.jersey.servlet.ServletContainer
      </servlet-class>
      <init-param>
         <param-name>javax.ws.rs.Application</param-name>
         <param-value>
            com.tangosol.coherence.rest.server.ContainerResourceConfig
         </param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>Coherence REST</servlet-name>
      <url-pattern>/*</url-pattern>
    </servlet-mapping>
      ...
</web-app>

Save the web.xml file to the /WEB-INF/ directory.
Copy the coherence-rest-config.xml file to the WEB-INF/classes directory.
Copy your coherence-cache-config.xml file and tangosol-coherence-override.xml file to the WEB-INF/classes directory.
If you are using POF, copy the pof-config.xml file to the WEB-INF/classes directory. Make sure that the pof-config.xml file includes the location of the REST POF types. For details, see "Configuring REST Server Access to POF-Enabled Services."

Create a Web ARchive file (WAR) using the jar utility. For example, issue the following command from a command prompt at the root of the Web application directory:

jar -cvf coherence_rest.war *

The archive should contain the following files:

/WEB-INF/web.xml
/WEB-INF/classes/coherence-rest-config.xml
/WEB-INF/classes/tangosol-coherence-override.xml
/WEB-INF/classes/coherence-cache-config.xml
/WEB-INF/lib/coherence.jar
/WEB-INF/lib/coherence-rest.jar
/WEB-INF/lib/coherence_dependencies

27.3.2 Deploying to a Servlet Container

Coherence REST can be deployed to any servlet container by packaging Coherence REST as a WAR file. See "Packaging Coherence REST for Deployment" for details. Refer to your vendors documentation for details on deploying WAR files. In addition, See the Jersey user guide for additional servlet container deployment options:

http://jersey.java.net/nonav/documentation/latest/user-guide.html#d4e194

27.4 Configuring REST Server Access to POF-Enabled Services

POF-enabled services must include the defined Coherence REST POF user types. The user types are defined in the coherence-rest-pof-config.xml file that is located in the coherence-rest.jar library and is automatically loaded at runtime.

To configure the REST default user types, edit the pof-config.xml file to include the coherence-rest-pof-config.xml POF configuration file. For example:

<pof-config>
   <user-type-list>
      <include>coherence-pof-config.xml</include>
      <include>coherence-rest-pof-config.xml</include>
      ...
   </user-type-list>
</pof-config>