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:
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>
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:
To configure a 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.
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.
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.
To package the Coherence REST Web application:
Create a Web application directory structure as follows:
/ /WEB-INF/ /WEB-INF/classes/ /WEB-INF/lib/
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.17.1.jar
jersey-json-1.17.1.jar
jersey-multipart-1.17.1.jar
jersey-server-1.17.1.jar
jersey-servlet-1.17.1.jar
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>
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 *
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 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.
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 *
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 *
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}
.
This section provides instructions for deploying Coherence Rest to a Java EE environment:
The following topics are included in this section:
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 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.17.1.jar
jersey-json-1.17.1.jar
jersey-multipart-1.17.1.jar
jersey-server-1.17.1.jar
jersey-servlet-1.17.1.jar
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>
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.
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.17.1.jar /WEB-INF/lib/jersey-servlet-1.17.1.jar /WEB-INF/lib/jersey-core-1.17.1.jar /WEB-INF/lib/jersey-json-1.17.1.jar /WEB-INF/lib/jersey-multipart-1.17.1.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
To deploy Coherence REST to GlassFish server:
From the GlassFish administration console (http://localhost:4848/
), click Configuration->JVM Settings.
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
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>
Deploy the WAR using the GlassFish administration console.
From a browser, verify the deployment by navigating to http://localhost:8080/coherence_rest/
{cacheName}
.
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