This chapter provides instructions for deploying Coherence applications to managed Coherence servers in 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.
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. For details on production redeployment, 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:
A GAR module can use shared libraries that are deployed to WebLogic Server.
<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>
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 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. For details, 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
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 managed Coherence servers, see Securing Oracle Coherence.