4 Deploying Coherence Applications in WebLogic Server

To manage Coherence servers in a WebLogic Server domain, you must deploy Coherence applications packaged as a Grid ARchive (GAR).

See Packaging Coherence Applications for details on creating a GAR.

This chapter includes the following sections:

• Understanding Coherence Deployment Tiers
  Coherence is setup in tiers within a WebLogic Server domain. The tiers often include: a data tier for storing data; an application tier for consuming cached data; and a proxy tier for allowing remote clients (non cluster members) to use a cluster.
• Deploying Applications to Managed Coherence Servers
  Coherence application GAR contains the artifacts of a Coherence application and includes a deployment descriptor. A GAR can be deployed as a standalone module or as a part of an EAR using any WebLogic Server deployment tool.
• Deploying Coherence Applications as Shared Libraries
  Coherence applications are packaged as Grid ARchive (GAR) and deployed as shared libraries in a single-tier or multi-tier domain.
• Referencing Shared Libraries from a Coherence Application
  A GAR module can use shared libraries that are deployed to WebLogic Server.
• Performing a Rolling Redeploy
  GAR modules that are targeted to a WebLogic Server cluster are simultaneously redeployed to all managed Coherence servers.
• Loading Coherence From the Application Classloader
  The Coherence library (coherence.jar) is included in the system classpath of WebLogic Server. It is a best practice to always use this library and not include the coherence.jar library within the /lib directory of a Web application.
• Securing Coherence Applications in WebLogic Server
  Coherence applications that are deployed to managed Coherence servers can be secured.

Understanding Coherence Deployment Tiers

Coherence is setup in tiers within a WebLogic Server domain. The tiers often include: a data tier for storing data; an application tier for consuming cached data; and a proxy tier for allowing remote clients (non cluster members) to use a cluster.

The use of a dedicated storage tier that is separate from the application tier and proxy tier is a best practice that ensures optimal performance of a Coherence cluster.

The deployment tiers contain managed servers that are part of a Coherence cluster. Managed servers that are part of a Coherence cluster are referred to as managed Coherence servers. Coherence tiers are typically associated with respective WebLogic Server clusters. The use of WebLogic Server clusters simplifies the deployment of an application and the management of the deployment topology, especially in large clusters. However, managed Coherence servers in each tier can be individually managed as required.

During development and simple testing, setting up Coherence deployment tiers may be impractical. In this case, a Coherence application can be deployed to a single managed server and a single-server cluster is automatically created using default cluster settings.

See Administering Clusters for Oracle WebLogic Server.

Deploying Applications to Managed Coherence Servers

Coherence application GAR contains the artifacts of a Coherence application and includes a deployment descriptor. A GAR can be deployed as a standalone module or as a part of an EAR using any WebLogic Server deployment tool.

Coherence application GAR modules get deployed the same way as JavaEE modules and can be deployed using any WebLogic Server deployment tool: the WebLogic Server Administration Console, the Oracle WebLogic Scripting Tool (WLST), the WebLogic Server Deployer class, and the WebLogic Server <wldeploy> ANT target.

See Oracle WebLogic Server Administration Console Online Help.

See Understanding the WebLogic Scripting Tool.

See Deploying Applications to Oracle WebLogic Server.

Note:

Production redeployment of an EAR containing a GAR is only supported for storage-disabled cluster clients. In addition, any changes to the code in the GAR must be backward compatible with the existing deployment. For example, entity classes that are changing must implement the Evolvable interface. See Deploying Applications to Oracle WebLogic Server.

GAR modules should be deployed as standalone modules and also as part of an EAR. The following list describes how GAR modules are deployed in a WebLogic Server domain that uses Coherence tiers. See Administering Clusters for Oracle WebLogic Server.

• Data Tier – Deploy a standalone GAR to each managed Coherence server of the data tier. If the data tier is setup as a WebLogic Server cluster, deploy the GAR to the cluster and have the module copied to each managed Coherence server.

• Application Tier – Deploy the EAR that contains both the client implementation (Web Application, EJB, and so on) and the GAR to each managed Coherence server in the cluster. If the application tier is setup as a WebLogic Server cluster, deploy the EAR to the cluster and have the module copied to each managed Coherence server.

• Proxy Tier – Deploy the standalone GAR to each managed Coherence server of the proxy tier. The cache configuration file packaged in the GAR must include a proxy service definition. If the application tier is setup as a WebLogic Server cluster, deploy the GAR to the cluster and have the module copied to each managed Coherence server.

• Extend Client Tier – Deploy the EAR that contains the extend client implementation (Web Application, EJB, and so on) as well as the GAR to each managed server that hosts the extend client. The client's cache configuration file must include a remote cache service definition that defines the address of a proxy server. If the extend client tier is setup as a WebLogic Server cluster, deploy the EAR to the cluster and the WebLogic deployment infrastructure copies the module to each managed Coherence server.

Deploying Coherence Applications as Shared Libraries

Coherence applications are packaged as Grid ARchive (GAR) and deployed as shared libraries in a single-tier or multi-tier domain.

A standalone GAR can be deployed as a shared library and referenced by multiple EAR files. For general information about shared libraries and their deployment, see Creating Shared Java EE Libraries and Optional Packages in Developing Applications for Oracle WebLogic Server.

To use the GAR at runtime, the weblogic-application.xml deployment descriptor in an EAR must contain a reference to the GAR. For example:

<weblogic-application>
   <library-ref>
      <library-name>ExampleGAR</library-name>
   </library-ref>
</weblogic-application>

The above configuration works in single-tier domain where both the application tier and data tier are on a single managed Coherence server. However, in a multi-tiered domain, additional configuration is required to ensure that a GAR that is deployed as a shared library results in storage-enabled members starting as expected.

To deploy a GAR as shared library in multi-tiered domain:

1. Edit the cache configuration file in the GAR and explicitly set the <scope-name> element to the GAR name. For details about configuring the scope name, see Administering Oracle Coherence.

   For example, if the GAR is named ExampleGAR.gar, the <scope-name> element is defined as follows:

   <cache-config>
      <defaults>
         <scope-name>ExampleGAR</scope-name>
      </defaults>
      ...
   

2. Deploy the GAR to the application (storage-disabled) tier as a shared library and specify the GAR name as the application name. For example, if the GAR is named ExampleGAR.gar, then the GAR name is specified as ExampleGAR.
3. Edit the weblogic-application.xml deployment descriptor in the EAR and include a reference for the GAR. For example:

   <weblogic-application>
      <library-ref>
         <library-name>ExampleGAR</library-name>
      </library-ref>
   </weblogic-application>
   

4. Deploy the EAR to the application tier.
5. Deploy the same GAR to the data (storage-enabled) tier and modify the name. For example, ExampleGAR-DataTier. If a name is not specified, a -1 is appended to the deployment name because the GAR already exists as a shared library.
6. After the deployment completes, the GARs that are deployed to both tiers (for example, ExampleGAR and ExampleGAR-DataTier) join the same services and client request processing and data storage are separated as expected.

Referencing Shared Libraries from a Coherence Application

A GAR module can use shared libraries that are deployed to WebLogic Server.

To use a shared library, reference the shared library within a <library-ref> node in the weblogic-coh-app.xml deployment descriptor and package the deployment descriptor in the /META-INF directory of the GAR module.

For a detailed reference of the available elements in the descriptor, see weblogic-coh-app.xml Deployment Descriptor Elements. For example:

<?xml version="1.0"?>
<weblogic-coh-app 
   xmlns:wls="http://xmlns.oracle.com/weblogic/weblogic-coh-app">
   <library-ref>
      <library-name>mySharedLibrary</library-name>
      <specification-version>2.0</specification-version>
      <implementation-version>8.1beta</implementation-version>
      <exact-match>false</exact-match>
   </library-ref>
</weblogic-coh-app>

Performing a Rolling Redeploy

GAR modules that are targeted to a WebLogic Server cluster are simultaneously redeployed to all managed Coherence servers.

There are no provisions that guard against in-memory cache data loss when utilizing simultaneous redeployment across all managed Coherence servers.

Note:

To ensure there is no persistence or write-through cache data loss during a simultaneous redeployment of GAR modules to all managed Coherence servers, you can leverage the service suspend feature. A service is considered suspended only after all the data is fully written, including active persistence mode, asynchronous persistence tasks, entries in the write-behind queue of a read-write backing map, and other asynchronous operations. Outstanding operations are completed and no new operations are allowed against the suspended services. Thus, for a controlled complete redeploy of GAR modules to all managed Coherence servers, Oracle recommends executing the Coherence ClusterMBean operation suspendService("impactedService") which suspends each service with potential asynchronous operations gracefully before undeploying GAR modules from all managed Coherence servers.

A rolling redeploy is a technique for updating a GAR across a WebLogic Server cluster by individually redeploying the GAR on each managed Coherence server and cycling through all servers. A rolling redeploy allows cached data to be redistributed while the GAR is redeployed. Only in-memory cache data is otherwise lost if a GAR is redeployed to all cache servers simultaneously.

Note:

Always check the StatusHA metric on the partitioned service between server-targeted deployments to ensure MACHINE_SAFE status. See Managing Oracle Coherence for details on this metric.

To perform a rolling redeploy, a GAR must be deployed using the specifiedtargetsonly option, which ensures that subsequent updates to the GAR results in a deployment on the current target and not on all targets that contain the GAR. The specifiedtargetsonly option is not available through the WebLogic Server Administration Console and must be specified using either WLST, weblogic.Deployer, or the <wldeploy> ANT target.

The full path and name to the GAR file must match exactly the path and name that was used to originally deploy the GAR. If a different path or name is used, then a -1, -2, or, -1 and -2 is appended to the GAR name and the rolling redeploy will not work correctly. In addition, if the GAR was originally deployed using the upload=true option, then you must redeploy using the upload=true option; otherwise, the rolling redeploy will not work correctly.

For a complete example (including a WLST script) of redeploying Coherence applications (including ensuring MACHINE_SAFE status), see the Coherence examples that are part of the WebLogic Server examples. The examples are available by performing a custom WebLogic Server installation and selecting to install the Server Examples. See Understanding Oracle WebLogic Server.

WLST

deploy('MyCohApp', '/myapps/MyCohApp.gar', 'server1', specifiedTargetsOnly='true')

<wldeploy> ANT Target

<wldeploy
   user="${admin.username}"
   password="${admin.password}"
   adminurl="t3://${admin.host}:${admin.port}"
   debug="false"
   action="deploy"
   name="Coherence GAR"
   source="${gar.filename}"
   targets="ms3"
   specifiedtargetsonly="true"
   failonerror="true"/>

weblogic.Deployer

java weblogic.Deployer -adminurl t3://localhost:7001 -username username -password password -targets ms3 -deploy -name MyCohApp /myapps/MyCohApp.gar -specifiedtargetsonly

Loading Coherence From the Application Classloader

The Coherence library (coherence.jar) is included in the system classpath of WebLogic Server. It is a best practice to always use this library and not include the coherence.jar library within the /lib directory of a Web application.

For advanced use cases that include the coherence.jar library in a Web application, the Coherence resources must be defined in the weblogic.xml file using the <prefer-application-packages> and <prefer-application-resources> elements. For example:

<container-descriptor>
   <prefer-application-packages>
     <package-name>com.tangosol.*</package-name>
     <package-name>com.oracle.coherence.common.**</package-name>
   </prefer-application-packages>
 
   <prefer-application-resources>
     <resource-name>com.tangosol.*</resource-name>
     <resource-name>com.oracle.coherence.common.*</resource-name>
     <resource-name>coherence-*.xml</resource-name>
     <resource-name>coherence-*.xsd</resource-name>
     <resource-name>tangosol-*.xml</resource-name>
     <resource-name>tangosol.properties</resource-name>
     <resource-name>tangosol.cer</resource-name>
     <resource-name>tangosol.dat</resource-name>
     <resource-name>internal-txn-cache-config.xml</resource-name>
     <resource-name>txn-pof-config.xml</resource-name>
     <resource-name>pof-config.xml</resource-name>
     <resource-name>management-config.xml</resource-name>
     <resource-name>processor-dictionary.xml</resource-name>
     <resource-name>reports/*</resource-name>
     </prefer-application-resources>
 </container-descriptor>

Securing Coherence Applications in WebLogic Server

Coherence applications that are deployed to managed Coherence servers can be secured.

See Securing Oracle Coherence for details on securing the Coherence applications.