Introduction

New in this release of Coherence*Web is a deployment option on the WebLogic Server platform that enables a tighter integration with WebLogic Server. The installation and configuration options described here only apply to WebLogic Server 10.3 deployments. It should be noted that the configuration of Coherence*Web for WebLogic Server is likely to change in future releases as Coherence*Web is even more tightly integrated into the WebLogic Server.

Overview of Coherence*Web SPI

Coherence*Web is not a replacement for WebLogic Server's in-memory HTTP state replication services. However, Coherence*Web should be considered when an application has large Http Session State objects, when running into memory constraints due to storing Http Session object data, and/or have existing Coherence Cluster and would like to offload Http Session storage to a Coherence Cluster.

The most significant change introduced by this new deployment option is that applications deployed using the Coherence*Web SPI module no longer require an application to be instrumented by the Coherence*Web WebInstaller.

Installation

Location of the WebLogic Server Coherence*Web SPI in Coherence Distribution

The Weblogic Server Coherence*Web SPI consists of the coherence-web-spi.war file, located in the coherence\lib directory in the Coherence distribution. The coherence.jar file, located in the same directory, is also necessary for enabling Coherence*Web functionality in WebLogic Server.

Requirements for using Coherence*Web SPI

The Coherence*Web SPI for Weblogic Server requires that a load balancer which enforces http session JVM affinity is running in front of the WebLogic Server tier. WebLogic Server ships with several different proxy plug-ins which will enforce JVM session stickiness. Documentation for configuring the WebLogic Server proxy plug-in is available here.

Overview Of Configuration and Deployment

The Coherence*Web distribution includes a deployable shared library that contains a native plugin to WebLogic Server's Http Session Management interface. To enable Coherence*Web on WebLogic Server for a web application, you must complete the following steps:

1. Apply WebLogic Server publically available Patch ID N41D to all WebLogic Server instances that are hosting the web application(s) that will leverage Coherence*Web. Please see the instructions for using Smart Update to install WebLogic Server patches. For production environments it is recommended that you review the Smart Update production installation notes.
   1. Login in using your Support ID and Password.
      
   2. Download and apply patch N41D. Restart WebLogic Server.
      
2. Optionally modify the session-cache-config.xml to customize the Cache topology for Coherence*Web. This configuration file is located in the /WEB-INF/classes directory within the coherence-web-spi.war file. If this file is modified, it should be updated in coherence-web-spi.war.
3. Start a Cache Server Tier in a seperate JVM from the one running WebLogic Server per the instructions below.
4. Determine the appropriate packaging based on your deployment requirements and follow the appropriate packaging instructions.
5. Optionally modify the web.xml and weblogic.xml files in the WAR deployment if advanced configuration is required for a web application using Coherence*Web.

   If you are deploying Coherence*Web in a WebLogic Portal environment please see the Coherence*Web and WebLogic Portal page for installation instructions.

Coherence*Web WebLogic SPI-Specific Configurations

There are two differences between the default cache configuration for the Coherence*Web SPI for WebLogic Server and Coherence*Web:

1. The Coherence*Web SPI for WebLogic Server is configured with local-storage disabled. This means a Coherence Cache Server must be running in its own JVM, separate from the JVM running WebLogic Server.
2. The timeout for requests to the cache server to respond is 30 seconds. If a request to the cache server has not responded in 30 seconds, a com.tangosol.net.RequestTiemoutException exception is thrown.

The Coherence caches used by the Coherence*Web SPI is configured by the session-cache-config.xml file. The session-cache-config.xml file is located inside the coherence-web-spi.war file under the WEB-INF\classes directory. Any cache configuration change should be put inside session-cache-config.xml, and then should be repackaged inside coherence-web-spi.war.

To Configure and Start a Cache Server

A Cache Server JVM is a dedicated Coherence JVM that is responsible for storing and managing all cached data (in this case, HttpSession state). One or more Cache Server JVMs must be started before the WLS/WLP JVMs can be started.

1. Create a script for starting a Cache Server JVM. The following is an very simple example of a script that starts a storage-enabled Cache Server for use with Coherence*Web. This example assumes that you are using a Sun JVM. See this page for information on tuning your particular JVM.
   
   java -server -Xms512m -Xmx512m -cp <Coherence installation dir>/lib/coherence.jar:<Coherence installation dir>/lib/coherence-web-spi.war -Dtangosol.coherence.management.remote=true -Dtangosol.coherence.cacheconfig=WEB-INF/classes/session-cache-config.xml -Dtangosol.coherence.session.localstorage=true com.tangosol.net.DefaultCacheServer
   
   
2. Start one or more Cache Server JVMs using the script described above.

Packaging and Configuration Considerations

As part of the Coherence*Web SPI for WebLogic Server you will find the coherence.jar and coherence-web-spi.war located in the /lib directory of the Coherence 3.4.2 distribution.

Coherence cluster nodes are class loader scoped. Therefore, controlling the number of unique Coherence cluster nodes in a Coherence*Web deployment needs to be decided prior to packaging the application(s). The different options are listed below and are described in detail on the Cluster Node Isolation in Coherence*Web page:

• Application Server Scoped Cluster Nodes
• EAR Scoped Cluster Nodes
• WAR Scoped Cluster Nodes

  Be Careful The Application Server Scoped Cluster Nodes configuration should be considered very carefully and never used in environments where application interaction is unknown or unpredictable. An example of such environment may be a deployment where multiple development teams are deploying independently written applications without coordinating and enforcing their conventions and naming standards carefully. With this configuration, all applications are part of the same cluster and the likelihood of collisions between namespaces for caches, services and other configuration settings is quite high and may lead to unexpected results. For these reasons we strongly recommend either the EAR Scoped or WAR Scoped cluster node configurations. If you are in doubt as to which deployment topology to choose or if this warning applies to your deployment, please do not choose this configuration.

Packaging and Configuring Application Server Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
2. Edit you WebLogic Server system classpath to include coherence.jar or copy coherence.jar to you $DOMAIN_HOME/lib directory.
3. Enable Coherence*Web in your web application by adding the following to stanza in the weblogic.xml in each WAR file deployed in the WebLogic Server that intends to leverage Coherence*Web:
   
   

   <weblogic-web-app>
   
   	...
   
    	<library-ref>
   
    		<library-name>coherence-web-spi</library-name>
   
   		<specification-version>1.0.0.0</specification-version>
   
           	<implementation-version>1.0.0.0</implementation-version>
   
   		<exact-match>false</exact-match>
   
   	</library-ref>
   
   	...
   
   
   
   </weblogic-web-app>

Packaging and Configuring EAR Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server.
2. Place coherence.jar in the EAR's APP-INF/lib directory.
3. To enable Coherence*Web create a shared library reference in each web application in the EAR by adding the following stanza weblogic.xml:
   
   

   <weblogic-web-app>
   
   	...
   
    	<library-ref>
   
    		<library-name>coherence-web-spi</library-name>
   
   		<specification-version>1.0.0.0</specification-version>
   
   		<implementation-version>1.0.0.0</implementation-version>
   
   		<exact-match>false</exact-match>
   
   	</library-ref>
   
   	...
   
   </weblogic-web-app>

Packaging and Configuring WAR Scoped Cluster Nodes

1. Deploy coherence-web-spi.war as a shared library on each WebLogic Server
2. Place coherence.jar in the WAR's WEB-INF/lib directory.
3. Create a reference to the shared library by modifying the weblogic.xml in web applications WEB-INF directory.
   
   

   <weblogic-web-app>
   
   	...
   
    	<library-ref>
   
    		<library-name>coherence-web-spi</library-name>
   
   		<specification-version>1.0.0.0</specification-version>
   
   		<implementation-version>1.0.0.0</implementation-version>
   
   		<exact-match>false</exact-match>
   
   	</library-ref>
   
   	...
   
   <weblogic-web-app>

Coherence*Web Configuration Options

Since Coherence*Web is in control of the http session lifecycle, most data from the <session-descriptor> element in either weblogic.xml or weblogic-application.xml is ignored. Most of Coherence*Web configuration can be done through <context-param> in web.xml. The default configuration included in the SPI should be sufficient for most web application usages, but all configurations options can be overidden using <context-param>. 

The following Coherence*Web settings can be configured in web.xml using <context-param>:

Please see the Configuring Coherence*Web page for detailed information on each of the above parameters.

The generated Http session cookie can be configured in weblogic.xml or weblogic-application.xml using <session-descriptor>:

In WebLogic SPI module the following Coherence Web Configuration parameters are not controlled by the Coherence Web Configuration parameters and will need to be specified as outlined below instead:

Using SAML SSO

By default, WebLogic Server provides basic SSO functionality. To leverage SAML SSO functionality with Coherence*Web, the saml2.war web application must be modified.

1. Backup the existing saml2.war in the WebLogic Server installation.
2. Unjar the saml2.war into a temporary directory. The saml2.war is located in the $WL_SERVER_HOME/server/lib directory.
3. Create a lib and classes directory under the WEB-INF directory.
4. Unjar the coherence-web-spi.war to retrieve coherence-web.jar and coherence-web-spi.jar. Put these two jars in the /WEB-INF/lib directory.
5. Copy the session-cache-config.xml, located in the /WEB-INF/classes directory from the exploded coherence-web-spi.war, into the the created /WEB-INF/classes directory.
6. Place the coherence.jar in the proper location, based on the cluster node scoping you selected: Application Server, EAR or WAR scoped.
7. Add the following to the /WEB-INF/web.xml file:
   
   

   <?xml version="1.0" encoding="UTF-8"?>
   
   	<web-app>..
   
   	<context-param>
   
   		<param-name>coherence-web-sessions-enabled</param-name>
   
   		<param-value>true</param-value>
   
   	</context-param>
   
   	...
   
   	</web-app>

8. Re-assemble the saml2.war by using the jar command, e.g.:
   
   

   jar cvf saml2.war $tempdir

9. Backup the existing saml2.war in the WebLogic Server installation.
10. Replace the saml2.war in the WebLogic installation with the modified saml2.war.

Known Limitations

By default, Coherence*Web creates a single HTTP session across all web applications for each client and scopes the session attributes to a each web application. This means that if a session is invalidated in one web application, that same session is invalidated for all web applications in WebLogic Server using Coherence*Web.

This functionality requires that the session cookie path is set to "/", making the same session cookie available to all web applications. If this is not the desired behavior, a potential workaround is to reduce the scope the session cookie by adding the following entry to weblogic.xml in each web application:

<weblogic-web-app>

	...

	<session-descriptor>

		<cookie-path>[path of web-app context, for example "/mainApp/subApp"]</cookie-path>

	</session-descriptor>

	...

</weblogic-web-app>

This will ensure a unique session is created for each web application. It is also possible to scope the session to all web-applications within an EAR file by setting the session cookie path to the context root of the deployed EAR.

This workaround around will not work if you deploy an EAR or web-application with '/' as the context path, or if you require WebLogic Single Sign-On. WebLogic Single Sign-On requires that the session cookie path be set to '/'.

Taxonomy of BPEL Faults

A bpel fault has a fault name, which is a qname (name qualified with a namespace), and a possible messageType. There are two categories of faults in BPEL: business faults and runtime faults.

Business faults are application specific faults and occur when an explicit <throw> activity is executed or an <invoke> activity gets a fault as response. The fault name of a business fault is specified by the BPEL process and the messageType, if one exists, is defined in the WSDL.

Runtime faults are not user defined and will not appear in the WSDL for a process or service. The BPEL spec defines 11 standard faults: selectionFailure, conflictingReceive, conflictingRequest, mismatchedAssignmentFailure, joinFailure, forcedTermination, correlationViolation, uninitializedVariable, repeatedCompensation and invalidReply. They are all in the namespace "http://schemas.xmlsoap.org/ws/2003/03/business-process/" and are typeless, meaning they don't have associated messageTypes. The Oracle BPEL Process Manager also introduces two more runtime faults: bindingFault and remoteFault. They are in the namespace of "http://schemas.oracle.com/extension" and are associated with an Oracle defined messageType "RuntimeFaultMessage". The WSDL that defines the RuntimeFaultMessage messageType is available in the c:/orabpel/system/xmllib directory.

RemoteFault is retryable. It has the following possible fault codes

BindingFault is not retryable. It has the following possible fault codes:

Securing Oracle Service Bus with Oracle Web Services Manager

You can use Oracle Web Services Manager 10.1.3.x and later in conjunction with Oracle Service Bus to help secure your SOA environment.

This document provides use cases that highlight the interaction between Oracle Service Bus and Oracle Web Services Manager features in providing security throughout the service pipeline.

No configuration in Oracle Service Bus is required for interaction with Oracle Web Services Manager. You implement Oracle Web Services Manager features at the desired client and service locations, and the interaction and enforcement occurs automatically.

For more information about Oracle Web Services Manager, see http://www.oracle.com/appserver/Web-services-manager.html.

This document describes the following security use cases with Oracle Web Services Manager:

Perimeter Security

Figure 11-1 illustrates using Oracle Web Services Manager Gateway for enforcing perimeter security.

Oracle Web Services Manager Gateway virtualizes the service exposed by the Oracle Service Bus proxy service. The inbound request to the Oracle Web Services Manager Gateway has a message protection policy. The client sends a secure request to the Oracle Web Services Manager Gateway virtualized service, which is signed and encrypted.

The Oracle Web Services Manager Gateway acts as a security enforcement point and decrypts and verifies the signature. Oracle Web Services Manager Gateway then routes the plain request to the proxy service over SSL. The proxy service forwards the request to the business service, which invokes the Web service and gets the plain response back. The response moves back through the proxy service and Oracle Web Services Manager Gateway to the client.

Identity Propagation

Figure 11-2 illustrates using the Oracle Web Services Manager Gateway for identity propagation using SAML (Security Assertion Markup Language) token version 1.1.

The client sends a basic HTTP authentication request to the Oracle Web Services Manager Gateway. Oracle Web Services Manager Gateway authenticates the user using the user name and password from the HTTP header. Oracle Web Services Manager Gateway generates a SAML sender voucher assertion with the authenticated user identity (token mediation), inserts the SAML token, and sends the assertion to the proxy service. The proxy service receives the SAML assertion with the user identity and, acting as an active intermediary, verifies the user identity. The proxy service then passes the request to the business service. The response travels back through the business service, proxy service, and Oracle Web Services Manager Gateway to the client.

Message Protection

This section describes the following use cases:

Message Protection with Client Agent

Figure 11-3 illustrates using the Oracle Web Services Manager Client Agent for message protection.

The proxy service has an inbound message protection policy. The Oracle Web Services Manager Client Agent sends a signed and encrypted request to the proxy service. The proxy service receives the secured request and, acting as an active intermediary, decrypts and verifies signature and routes the request to the business service. The business service invokes the Web service, gets the response back, and sends it to the proxy service. The proxy service signs and encrypts the response and sends it to the Oracle Web Services Manager Client Agent. The Client Agent receives the secure response, decrypts and verifies the signature, and passes the response to the client.

Message Protection with Gateway

The client sends a plain request through the proxy and business services in Oracle Service Bus. The business service signs and encrypts the request and sends the message to the Oracle Web Services Manager Gateway. The Gateway decrypts and verifies the request. The plain message response is passed back to the client.

Message Protection with Server Agent

The client sends a plain request through the proxy and business services in Oracle Service Bus. The business service signs and encrypt the request and sends the message to the Oracle Web Services Manager Server Agent. The Server Agent decrypts and verifies the request. The plain message response is passed back to the client.

Message Protection with Client and Server Agents

The Oracle Web Services Manager Client Agent signs and encrypts a client request and sends the request through the proxy and business services to the Web service. The Web service has a Server Agent injected in it. The Server Agent has an inbound message protection policy that decrypts and verifies the signature, then signs and encrypts the response. The response is sent back to the Client Agent, which decrypts and verifies the response, then returns the plain request to the client.

Authentication

Figure 11-7 illustrates using the Oracle Web Services Manager Client Agent for authentication.

The proxy service has a user name token policy. The client, through Oracle Web Services Manager Client Agent, sends a request to the proxy service with user credentials at the message level in a user name token. The proxy service maps the user credential from the user name token using credential mapping and sends it through the business service to the Web service for authentication. The Web service is protected using an Oracle Web Services Manager service agent with an inbound user name token policy. The Oracle Web Services Manager Service Client Agent extracts and authenticates the user credentials. The response is then sent back through the business service and the proxy service to the client.