See Packaging Coherence Applications for details on creating a GAR.
This chapter includes the following sections:
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.
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.
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:
<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>
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. 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
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>
See Securing Oracle Coherence for details on securing the Coherence applications.