This chapter provides instructions for deploying Coherence applications to a WebLogic Server domain. Coherence applications must be packaged as a Grid ARchive (GAR) for deployment. For details on creating a GAR, see Packaging Coherence Applications.
This chapter includes the following sections:
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.
For details on creating Coherence data tiers and setting up Coherence clusters for deployment, see Administering Clusters for Oracle WebLogic Server.
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. For details on using the WebLogic Server Administration Console, see Oracle WebLogic Server Administration Console Online Help. For details on using WLST, see Understanding the WebLogic Scripting Tool. For detailed instructions on the other deployment options, 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. For details on creating Coherence deployment 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.
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:
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>
...
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.
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>
Deploy the EAR to the application tier.
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.
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.
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 data loss by ensuring that the data partitions on a server are fully transmitted to another server during redeployment.
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. Cached 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. For details on this metric, see Managing Oracle Coherence.
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 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 of redeploying Coherence applications in the Coherence container (including ensuring MACHINE_SAFE status), see the Coherence container examples that are part of the WebLogic Server Examples.
deploy('MyCohApp', '/myapps/MyCohApp.gar', 'server1', specifiedTargetsOnly='true')
<wldeploy
user="${admin.username}"
password="${admin.password}"
adminurl="t3://${admin.host}:${admin.port}"
debug="false"
action="deploy"
name="Coherence Container GAR"
source="${gar.filename}"
targets="ms3"
specifiedtargetsonly="true"
failonerror="true"/>
java weblogic.Deployer -adminurl t3://localhost:7001 -username username -password password -targets ms3 -deploy -name MyCohApp /myapps/MyCohApp.gar -specifiedtargetsonly
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.common.**</package-name>
</prefer-application-packages>
<prefer-application-resources>
<resource-name>com.tangosol.*</resource-name>
<resource-name>com.oracle.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>
For details on securing Coherence applications that are deployed to the Coherence container, see Securing Oracle Coherence.