27 Deploying Coherence REST

You can deploy Coherence REST to an embedded HTTP server, WebLogic Server, and any generic servlet container.

This chapter includes the following sections:

• Deploying with the Embedded HTTP Server
  Coherence provides multiple embedded HTTP server implementations that can be used to host RESTful Web services.
• 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.
• Deploying to a Java EE Server (Generic)
  Coherence REST can be deployed to any standard Java EE environment.
• Configuring REST Server Access to POF-Enabled Services
  POF-enabled services must include the defined Coherence REST POF user types.

Deploying with the Embedded HTTP Server

Coherence provides multiple embedded HTTP server implementations that can be used to host RESTful Web services. See Changing the Embedded HTTP Server.

• DefaultHttpServer (backed by Oracle's lightweight HTTP server)

• NettyHttpServer (backed by Netty HTTP server and recommended for production)

• SimpleHttpServer (backed by Simple HTTP server)

• JettyHttpServer (backed by Jetty HTTP server)

• GrizzlyHttpServer (backed by Grizzly 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 <address> element also supports external NAT addresses that route to local addresses; however, both addresses must use the same port number.

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

<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. See Configuring REST Server Access to POF-Enabled Services.

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. See Configuring and Managing Coherence Clusters in Administering Clusters for Oracle WebLogic Server. In addition, Coherence applications must be packaged as a Grid ARchive (GAR). See Packaging Coherence Applications in Developing Applications with Oracle Coherence.

This section includes the following topics:

• Task 1: Configure a WebLogic Server Domain for Coherence REST
  
• Task 2: Package the Coherence REST Web Application
  
• Task 3: Package the Coherence Application
  
• Task 4: Package the Enterprise Application
  
• Task 5: Deploy the Enterprise Application
  

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, then the servers should be managed as a tier in a WebLogic Server cluster. See Setting Up a Coherence Cluster in Administering Clusters for Oracle WebLogic Server.

Task 2: Package the Coherence REST Web Application

To package the Coherence REST Web application:

1. Create a Web application directory structure as follows:

   /
   /WEB-INF/
   /WEB-INF/classes/
   /WEB-INF/lib/
   

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

   Note:

   The WebLogic Server classpath contains the coherence-rest.jar library which includes a default servlet context listener 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>
   

3. Save the web.xml file to the /WEB-INF/ directory.
4. 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 *
   

Task 3: Package the Coherence Application

To package the Coherence application:

1. 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
   

2. 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. See Configuring REST Server Access to POF-Enabled Services.
3. 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 *
   

Task 4: Package the Enterprise Application

To package the enterprise application:

1. 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
   

2. 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>
   

3. Edit the weblogic-application.xml file and add 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>
   </weblogic-application>
   

4. 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 *
   

Task 5: Deploy the Enterprise Application

To deploy the Enterprise application:

1. Use the WebLogic Server Administration Console or WLST tool to deploy the EAR to the managed Coherence server created in Task 1.
2. 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}.

Deploying to a Java EE Server (Generic)

Coherence REST can be deployed to any standard Java EE environment.

This section includes the following topics:

• Packaging Coherence REST for Deployment
  
• Deploying to a Servlet Container
  

Packaging Coherence REST for Deployment

To package a Coherence REST application:

1. Create a basic Web application directory structure as follows:

   /
   /WEB-INF
   /WEB-INF/classes
   /WEB-INF/lib
   

2. Copy the coherence.jar and coherence-rest.jar libraries from the COHERENCE_HOME/lib directory to the /WEB-INF/lib directory.
3. Copy the Coherence REST dependencies from the ORACLE_HOME/oracle_common/modules/ directory to the /WEB-INF/lib directory. See Dependencies for Coherence REST.
4. 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>/*</url-pattern>
       </servlet-mapping>
         ...
   </web-app>
   

5. Save the web.xml file to the /WEB-INF/ directory.
6. Copy the coherence-rest-config.xml file to the WEB-INF/classes directory.
7. Copy your coherence-cache-config.xml file and tangosol-coherence-override.xml file to the WEB-INF/classes directory.
8. 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. See Configuring REST Server Access to POF-Enabled Services.
9. 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
   

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. 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

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>