26 Deploying Coherence REST

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

This chapter includes the following sections:

26.1 Deploying with the Embedded HTTP Server

Coherence provides two embedded HTTP servers that can be used to host REST Web services: com.tangosol.coherence.rest.server.DefaultHttpServer (backed by Oracle's lightweight HTTP server) and com.tangosol.coherence.rest.server.GrizzlyHttpServer (backed by Grizzly). 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>

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

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

To configure a domain for Coherence REST:

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

  2. Deploy COHERENCE_HOME/lib/coherence-rest.jar as a shared library that is targeted to the managed Coherence server.

    Note:

    The coherence-rest.jar can also be added to the system classpath or included in the /lib directory of the GAR file.
  3. Coherence REST requires the JAXB provider from the GlassFish reference implementation. WebLogic Server uses the Eclipse MOXy JAXB provider by default. To configure WebLogic Server to use the GlassFish JAXB provider, set the following system properties when starting WebLogic Server:

    -Dcom.sun.xml.ws.spi.db.BindingContextFactory=com.sun.xml.ws.db.
    glassfish.JAXBRIContextFactory
    
    -Djavax.xml.bind.JAXBContext=com.sun.xml.bind.v2.ContextFactory
    

    For more details on configuring the GlassFish JAXB provider for WebLogic Server, see Oracle® Fusion Middleware Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

26.2.2 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. Copy the following JAR files from the ORACLE_HOME/oracle_common/modules/ directory to the /WEB-INF/lib directory:

    • jackson-core-asl-1.9.2.jar

    • jackson-jaxrs-1.9.2.jar

    • jackson-mapper-asl-1.9.2.jar

    • jackson-xc-1.9.2.jar

    • jersey-core-1.18.jar

    • jersey-json-1.18.jar

    • jersey-multipart-1.18.jar

    • jersey-server-1.18.jar

    • jersey-servlet-1.18.jar

  3. 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>com.sun.jersey.spi.container.servlet.ServletContainer
          </servlet-class>
          <init-param>
             <param-name>com.sun.jersey.config.property.resourceConfigClass
             </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>
    
  4. Save the web.xml file to the /WEB-INF/ directory.

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

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

    The coherence-rest-pof-config.xml file is located in the coherence-rest.jar library and is automatically loaded at runtime.

  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 *
    

26.2.4 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 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>
    
  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 *
    

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

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

26.3.1 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 following JARs from the COHERENCE_HOME/lib directory and the ORACLE_HOME/oracle_common/modules/ directory to the /WEB-INF/lib directory:

    • coherence.jar

    • coherence-rest.jar

    • jackson-core-asl-1.9.2.jar

    • jackson-jaxrs-1.9.2.jar

    • jackson-mapper-asl-1.9.2.jar

    • jackson-xc-1.9.2.jar

    • jersey-core-1.18.jar

    • jersey-json-1.18.jar

    • jersey-multipart-1.18.jar

    • jersey-server-1.18.jar

    • jersey-servlet-1.18.jar

  3. 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>com.sun.jersey.spi.container.servlet.ServletContainer
          </servlet-class>
          <init-param>
             <param-name>com.sun.jersey.config.property.resourceConfigClass
             </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>
    
  4. Save the web.xml file to the /WEB-INF/ directory.

  5. Copy the coherence-rest-config.xml file to the /WEB-INF/classes directory.

  6. Copy your coherence-cache-config.xml file and tangosol-coherence-override.xml file to the WEB-INF/classes directory.

  7. 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/jersey-server-1.18.jar
    /WEB-INF/lib/jersey-servlet-1.18.jar
    /WEB-INF/lib/jersey-core-1.18.jar
    /WEB-INF/lib/jersey-json-1.18.jar
    /WEB-INF/lib/jersey-multipart-1.18.jar
    /WEB-INF/lib/jersey-grizzly2-1.12.jar
    /WEB-INF/lib/jackson-core-asl-1.9.2.jar
    /WEB-INF/lib/jackson-jaxrs-1.9.2.jar
    /WEB-INF/lib/jackson-mapper-asl-1.9.2.jar
    /WEB-INF/lib/jackson-xc-1.9.2.jar
    

26.3.2 Deploying to GlassFish

To deploy Coherence REST to GlassFish server:

  1. From the GlassFish administration console (http://localhost:4848/), click Configuration->JVM Settings.

  2. Click the JVM Options tab and add the following option:

    -Dcom.sun.enterprise.overrideablejavaxpackages=javax.ws.rs,javax.ws.rs.core,javax.ws.rs.ext

  3. Package Coherence REST as a WAR file as described in "Packaging Coherence REST for Deployment". In addition, override the version of Jersey distributed in GlassFish with the version of Jersey distributed with Coherence REST by setting the class loader delegation to false in WEB-INF/sun-web.xml or WEB-INF/glassfish-web.xml. For example:

    <sun-web-app error-url="">
       <class-loader delegate="false"/>
    </sun-web-app>
    
  4. Deploy the WAR using the GlassFish administration console.

  5. From a browser, verify the deployment by navigating to http://localhost:8080/coherence_rest/{cacheName}.

26.3.3 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