Deploying Coherence Applications

1 Deploying Coherence Applications

Coherence can be deployed as a standalone application or as a Java EE application to an application server. Specific instructions are provided for WebLogic Server deployment in addition to instructions for generic application server deployment.

This chapter includes the following topics:

Deploying Standalone Coherence Applications
Standalone Coherence applications are deployed as a set of distributed processes.
Deploying Coherence Applications on Docker and Kubernetes
Oracle Coherence applications can be deployed as Docker containers and orchestrated using Kubernetes. These industry-leading standards offer a modern, cloud-neutral deployment solution that is highly scalable and easy to manage.
Deploying Coherence Applications to WebLogic Server
WebLogic Server includes a Coherence integration that standardizes the way Coherence applications can be deployed and managed within a WebLogic Server domain.
Deploying Coherence Applications to an Application Server (Generic)
Java EE applications that are deployed to an application server, other than WebLogic Server, have two options for deploying Coherence: as an application server library or as part of a Java EE module.
Running Multiple Applications in a Single Cluster
Coherence can be deployed in shared environments where multiple applications use the same cluster but define their own set of Coherence caches and services.

Parent topic: Basic Administration

Deploying Standalone Coherence Applications

Standalone Coherence applications are deployed as a set of distributed processes. For deployment, it is often beneficial to logically group these processes into tiers based on their role; however, it is not a requirement for deployment. The most common tiers are a data tier, application tier, proxy tier, and extend client tier. Tiers facilitate deployment by allowing common artifacts, packaging, and scripts to be defined and targeted specifically for each tier.

This section includes the following topics:

Parent topic: Deploying Coherence Applications

Deploying a Data Tier

A data tier is comprised of cache servers that are responsible for storing cached objects. A Coherence application may require any number of cache servers in the data tier. The number of cache servers depends on the amount of data that is expected in the cache and whether the data must be backed up and survive a server failure. Each cache server is a Coherence cluster member and runs in its own JVM process and multiple cache server processes can be collocated on a physical server. See Cache Size Calculation Recommendations and Hardware Recommendations.

Cache servers are typically started using the com.tangosol.net.DefaultCacheServer class. The class contains a main method and is started from the command line. See Starting Cache Servers in Developing Applications with Oracle Coherence.

The following application artifacts are often deployed with a cache server:

Configuration files such as the operational override configuration file, the cache configuration file and the POF user type configuration file
POF serializers and domain objects
Data grid processing implementations such as queries, entry processor, entry aggregators, and so on
Event processing implementations
Cache store and loader implementations when caching objects from data sources

There are no restrictions on how the application artifacts must be packaged on a data tier. However, the artifacts must be found on the server classpath and all configuration files must be found before the coherence.jar library if the default names are used; otherwise, the default configuration files that are located in the coherence.jar library are loaded. The following example starts a single cache server using the configuration files in the APPLICATION_HOME\config directory and uses the implementations classes in the APPLICATION_HOME\lib\myClasses library:

java -server -Xms4g -Xmx4g -cp APPLICATION_HOME\config;APPLICATION_HOME\lib\myClasses.jar;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

If you choose to include any configuration overrides as system properties (rather than modifying an operational override file), then they can be included as -D arguments to the java command. As a convenience, you can reuse the COHERENCE_HOME\bin\cache-server script and modify it as required.

GAR Deployment

Coherence application artifacts can be packaged as a Grid ARchive (GAR) and deployed with the DefaultCacheServer class. A GAR adheres to a specific directory structure and includes an application descriptor. See Building a Coherence GAR Module. The instructions are included as part of WebLogic server deployment, but are also applicable to a GAR being deployed with the DefaultCacheServer class.

The following example starts a cache server and uses the application artifacts that are packaged in the MyGar.gar file. The default name (MyGAR) is used as the application name, which provides a scope for the application on the cluster.

java -server -Xms4g -Xmx4g -cp APPLICATION_HOME\config;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer D:\example\MyGAR.gar

You can override the default name by providing a different name as an argument. See Overview of the DefaultCacheServer Class in Developing Applications with Oracle Coherence. For details about application scope, see Running Multiple Applications in a Single Cluster.

Parent topic: Deploying Standalone Coherence Applications

Deploying an Application Tier

An application tier is comprised of any number of clients that perform cache operations. Cache operations include loading objects in the cache, using cached objects, processing cached data, and performing cache maintenance. The clients are Coherence cluster members, but are not responsible for storing data.

The following application artifacts are often deployed with a client:

Configuration files such as the operational override configuration file, the cache configuration file and the POF user type configuration file
POF serializers and domain objects
Data grid processing implementations such as queries, entry processor, entry aggregators, and so on
Event processing implementations
Cache store and loader implementations when caching objects from data sources

There are no restrictions on how the application artifacts must be packaged on an application tier. Clients must include the COHERENCE_HOME/lib/coherence.jar library on the application classpath. Coherence configuration files must be included in the classpath and must be found before the coherence.jar library if the default names are used; otherwise, the default configuration files that are located in the coherence.jar library are loaded. The following example starts a client using the configuration files in the APPLICATION_HOME\config directory and uses the implementations classes in the APPLICATION_HOME\lib\myClasses.jar library.

java -cp APPLICATION_HOME\config;APPLICATION_HOME\lib\myClasses.jar;COHERENCE_HOME\lib\coherence.jar com.MyApp

If you choose to include any system property configuration overrides (rather than modifying an operational override file), then they can be included as -D arguments to the java command. For example, to disable storage on the client, the tangosol.coherence.distributed.localstorage system property can be used as follows:

java -Dcoherence.distributed.localstorage=false -cp APPLICATION_HOME\config;APPLICATION_HOME\lib\myClasses.jar;COHERENCE_HOME\lib\coherence.jar com.MyApp

Note:

If a GAR is used for deployment on a cache server, then cache services are restricted by an application scope name. Clients must use the same application scope name; otherwise, the clients can not access the cache services. See Running Multiple Applications in a Single Cluster.

Parent topic: Deploying Standalone Coherence Applications

Deploying a Proxy Tier for Extend Clients

A proxy tier is comprised of proxy servers that are responsible for handling extend client requests. Any number of proxy servers may be required in the proxy tier. The number of proxy servers depends on the expected number of extend clients and the expected request load of the clients. Each proxy server is a cluster member and runs in its own JVM process and multiple proxy server processes can be collocated on a physical server. See Defining Extend Proxy Services in Developing Remote Clients for Oracle Coherence.

A proxy server is typically started using the com.tangosol.net.DefaultCacheServer class. The class contains a main method and is started from the command line. See Starting Cache Servers in Developing Applications with Oracle Coherence. There is no difference between a proxy server and a cache server.

The following application artifacts are often deployed with a proxy:

Configuration files such as the operational override configuration file, the cache configuration file and the POF user type configuration file
POF serializers and domain objects. If an extend client is implemented using C++ or .NET, then a Java version of the objects must also be deployed for certain use cases.
Data grid processing implementations such as queries, entry processor, entry aggregators, and so on
Event processing implementations
Cache store and loader implementations when caching objects from data sources

There are no restrictions on how the application artifacts must be packaged on a proxy tier. However, the artifacts must be found on the server classpath and all configuration files must be found before the coherence.jar library; otherwise, the default configuration files that are located in the coherence.jar library are loaded. The following example starts a single proxy server using the configuration files in the APPLICATION_HOME\config directory and uses the implementations classes in the APPLICATION_HOME\lib\myClasses library:

java -server -Xms512m -Xmx512m -Dcoherence.distributed.localstorage=false -cp APPLICATION_HOME\config;APPLICATION_HOME\lib\myClasses.jar;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

GAR Deployment

The following example starts a proxy server and uses the application artifacts that are packaged in the MyGar.gar file. The default name (MyGAR) is used as the application name, which provides a scope for the application on the cluster.

java -server -Xms512m -Xmx512m -Dcoherence.distributed.localstorage=false -cp APPLICATION_HOME\config;APPLICATION_HOME\lib\myClasses.jar;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer D:\example\MyGAR.gar

You can override the default name by providing a different name as an argument. See Starting Cache Servers in Developing Applications with Oracle Coherence. For details about application scope, see Running Multiple Applications in a Single Cluster.

Parent topic: Deploying Standalone Coherence Applications

Deploying Extend Clients

Extend clients are implemented as Java, C++, or .NET applications. In addition, any client technology that provides a REST client API can use the caching services in a Coherence cluster. Extend clients are applications that use Coherence caches, but are not members of a Coherence cluster. See Configuring Extend Clients in Developing Remote Clients for Oracle Coherence.

The following Coherence artifacts are often deployed with an extend client:

Configuration files such as the operational override configuration file, the cache configuration file and the POF user type configuration file
POF serializers and domain objects
Data grid processing implementations such as queries, entry processor, entry aggregators, and so on
Event processing implementations

Parent topic: Deploying Standalone Coherence Applications

Deploying Coherence Applications on Docker and Kubernetes

Oracle Coherence applications can be deployed as Docker containers and orchestrated using Kubernetes. These industry-leading standards offer a modern, cloud-neutral deployment solution that is highly scalable and easy to manage.

Oracle has released Docker files for Coherence and supporting scripts to GitHub. The posted files are examples to help you get started and include documentation and samples. The Coherence images are available for Java 8 and support both the Coherence full installation and the Coherence quick installation. See docker-images/OracleCoherence on GitHub.

In addition, Oracle has released the Coherence Kubernetes Operator to GitHub. The operator is a Coherence-specific Kubernetes controller that facilitates running and managing containerized Coherence applications on Kubernetes. The operator is installed using Helm and provides integrations with ELK (Elasticsearch, Logstash, and Kibana) for logging, and Prometheus and Grafana for monitoring. The operator includes documentation and samples to help you get started. See the coherence-kubernetes-operator project on GitHub.

Parent topic: Deploying Coherence Applications

Deploying Coherence Applications to WebLogic Server

WebLogic Server includes a Coherence integration that standardizes the way Coherence applications can be deployed and managed within a WebLogic Server domain. The integration allows administrators to set up distributed Coherence environments using familiar WebLogic Server components and infrastructure, such as Java EE-styled packaging and deployment, remote server management, server clusters, WebLogic Scripting Tool (WLST) automation, and configuration through the Administration Console.

This section includes the following topics:

Parent topic: Deploying Coherence Applications

Overview of the WebLogic Server Coherence Integration

Coherence is integrated with WebLogic Server. The integration aligns the lifecycle of a Coherence cluster member with the lifecycle of a managed server: starting or stopping a server JVM starts and stops a Coherence cluster member. The first member of the cluster starts the cluster service and is the senior member. The integration is detailed in Configuring and Managing Coherence Clusters in Administering Clusters for Oracle WebLogic Server.

Like other Java EE modules, Coherence supports its own application module, which is called a Grid ARchive (GAR). The GAR contains the artifacts of a Coherence application and includes a deployment descriptor. A GAR is deployed and undeployed in the same way as other Java EE modules and is decoupled from the cluster service lifetime. Coherence applications are isolated by a service namespace and by class loader.

Coherence is typically setup in tiers that provide functional isolation within a WebLogic Server domain. The most common tiers are: a data tier for caching data and an application tier for consuming cached data. A proxy server tier and an extend client tier should be setup when using Coherence*Extend. An HTTP session tier should be setup when using Coherence*Web. See Using Coherence*Web with WebLogic Server in Administering HTTP Session Management with Oracle Coherence*Web.

WebLogic managed servers that are associated with a Coherence cluster are referred to as managed Coherence servers. Managed Coherence servers in each tier can be individually managed but are typically associated with respective WebLogic Server clusters. A GAR must be deployed to each data and proxy tier server. The same GAR is then packaged within an EAR and deployed to each application and extend client tier server. The use of dedicated storage tiers that are separate from client tiers is a best practice that ensures optimal performance.

Parent topic: Deploying Coherence Applications to WebLogic Server

Packaging Coherence Applications for WebLogic Server

Coherence applications must be packaged as a GAR module for deployment. A GAR module includes the artifacts that comprise a Coherence application and adheres to a specific directory structure. A GAR can be left as an unarchived directory or can be archived with a .gar extension. A GAR is deployed as both a standalone module and within an EAR. An EAR cannot contain multiple GAR modules.

This section includes the following topics:

Parent topic: Deploying Coherence Applications to WebLogic Server

Building a Coherence GAR Module

To build a Coherence GAR module:

Create the following GAR directory structure:
```
/
/lib/
/META-INF/
```
Add the Coherence cache configuration file and the POF configuration file (if required) to a directory within the GAR. For example:
```
/
/lib/
/META-INF/coherence-cache-config.xml
/META-INF/pof-config.xml
```
Note:

The configuration files should not be placed in the root directory of the GAR. If the configuration files are placed in the root, do not use the default names as shown; otherwise, the configuration files are loaded from the coherence.jar file which is located in the system classpath.
Create a coherence-application.xml deployment descriptor file and save it to the /META-INF directory. A Coherence GAR must contain a coherence-application.xml deployment descriptor that is located within the META-INF directory. The presence of the deployment descriptor indicates a valid GAR.
```
/
/lib/
/META-INF/coherence-application.xml
/META-INF/coherence-cache-config.xml
/META-INF/pof-config.xml
```
Edit the coherence-application.xml file and specify the location of the configuration files from step 2. For example:
```
<?xml version="1.0"?>
<coherence-application xmlns="http://xmnls.oracle.com/coherence/coherence-application">
   <cache-configuration-ref>META-INF/coherence-cache-config.xml</cache-configuration-ref>
   <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>
</coherence-application>
```
Note:
- Configuration files can be placed on a network and referenced using a URL instead of copying the files locally to the GAR.
- The cache configuration file can be overridden at runtime with a cluster cache configuration file. See Overriding a Cache Configuration File in Administering Clusters for Oracle WebLogic Server.
- The cache configuration file can also be overridden at runtime using a JNDI property. See Using JNDI to Override Configuration in Developing Oracle Coherence Applications for Oracle WebLogic Server.
Place all Coherence application Java classes (entry processors, aggregators, filters, and so on) in the root directory within the appropriate package structure.
Place any library dependencies in the /lib directory.
Use the Java jar command from the root directory to compress the archive with a .gar extension. For example:
```
jar cvf MyApp.gar *
```

Parent topic: Packaging Coherence Applications for WebLogic Server

Packaging a GAR Module in an EAR Module

A GAR module must be packaged in an EAR module to be referenced by other modules. See Enterprise Applications in Developing Applications for Oracle WebLogic Server.

To include a GAR module within an EAR module:

Copy a GAR to the root directory of an EAR together with any application modules (WAR, EJB, and so on) that use Coherence.

Edit the META-INF/weblogic-application.xml descriptor and include a reference to the GAR using the <module> element. The reference is required so that the GAR is deployed when the EAR is deployed. For example:

<?xml version = '1.0'>
<weblogic-application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-application
   http://www.bea.com/ns/weblogic/weblogic-application/1.0/
   weblogic-application.xsd"
   xmlns="http://www.bea.com/ns/weblogic/weblogic-application">
   <module>
      <name>MyAppGAR</name>
      <type>GAR</type>
      <path>MyApp.gar</path>
   </module>
</weblogic-application>

Parent topic: Packaging Coherence Applications for WebLogic Server

Setting Up a WebLogic Server Domain Topology for Coherence

This section includes the following topics:

Parent topic: Deploying Coherence Applications to WebLogic Server

Guidelines for Setting Up a Domain Topology

Coherence supports different domain topologies within a WebLogic Server domain to provide varying levels of performance, scalability, and ease of use. For example, during development, a single managed Coherence server instance may be used as both a cache server and a cache client. The single-server topology is easy to setup and use, but does not provide optimal performance or scalability. For production, Coherence is typically setup using WebLogic Server clusters. A WebLogic Server cluster is used as a Coherence data tier and hosts one or more cache servers; a different WebLogic Server cluster is used as a Coherence application tier and hosts one or more cache clients; and (if required) different WebLogic Server clusters are used for the Coherence proxy tier that hosts one or more managed Coherence proxy servers and the Coherence extend client tier that hosts extend clients. The tiered topology approach provides optimal scalability and performance. A domain topology should always be based on the requirements of an application.

Use the following guidelines when creating a domain topology for Coherence:

A domain typically contains a single Coherence cluster.
Multiple WebLogic Server clusters can be associated with a Coherence cluster.
A managed server that is associated with a Coherence cluster is referred to as a managed Coherence server and is the same as a Coherence cluster member.
Use different managed Coherence server instances (and preferably different WebLogic Server clusters) to separate Coherence cache servers and clients.
Coherence members managed within a WebLogic Server domain should not join an external Coherence cluster comprised of standalone JVM cluster members. Standalone JVM cluster members cannot be managed within a WebLogic Server domain.

Parent topic: Setting Up a WebLogic Server Domain Topology for Coherence

Create a Coherence Cluster

To create a Coherence cluster using the WebLogic Server console:

From the console home page's Environment section, click Coherence Clusters.
From the Summary of Coherence Clusters page, click New.
From the Create a Coherence Cluster Configuration page, enter a name for the cluster using the Name field.
Click Next and skip to step 6.

Or,

Click to select the Use a Custom Cluster Configuration File check-box. WebLogic Server MBeans expose a subset of the operational settings that are sufficient for most use cases. However, for advanced use cases that require full control over operational settings, a cluster configuration file (such as the tangosol-coherence-override.xml file) can be used. Click Next. See Setting Up a Cluster in Developing Applications with Oracle Coherence.

Note:

The use of an external cluster configuration file is only recommended for operational settings that are not available through the provided MBeans. That is, avoid configuring the same operational settings in both an external cluster configuration file and through the MBeans.
From the Create a Coherence Cluster Configuration File screen, use the File Path field to enter the path and name of a cluster configuration file that is located on the administration server. Click Next and skip to step 7.
From the Coherence Cluster Addressing section, leave the default clustering mode (Unicast) and change the port if required. To use multicast, use the drop-down list and select Multicast and provide a unique multicast address and port for the cluster. Click Next.

If Unicast is used, the cluster automatically creates a Well Known Addresses (WKA) list based on the managed Coherence server instances in the Coherence cluster (one per machine). You can edit the cluster definition using the Administration Console and define your own WKA list if you wish to change the number of members. Addresses must be entered using the actual IP address on the host and not localhost; otherwise, the managed Coherence servers will not be able to join with other cluster members. See Using Well Known Addresses in Developing Applications with Oracle Coherence.
From the Coherence Cluster Members section, click to select the managed Coherence servers or WebLogic Server clusters to be part of the Coherence cluster or skip this section if managed Coherence servers and WebLogic Clusters are yet to be defined.
Click Finish. The Summary of Coherence Clusters screen displays and the Coherence Clusters table lists the cluster.

Parent topic: Setting Up a WebLogic Server Domain Topology for Coherence

Create Coherence Deployment Tiers

The preferred approach for setting up Coherence in a WLS domain is to separate Coherence cache servers, clients, and proxies into different tiers that are associated with the same Coherence cluster. Typically, each tier is associated with its own WebLogic Server cluster of managed Coherence servers. However, a tier may also be comprised of standalone managed Coherence servers. The former approach provides the easiest way to manage and scale Coherence because the managed Coherence servers can inherit the WebLogic Server cluster's Coherence settings and deployments. Use the instructions in this section to create different WebLogic Server clusters for the data, application, and proxy tiers. See Configuring and Managing Coherence Clusters in Administering Clusters for Oracle WebLogic Server.

To create Coherence deployment tiers:

From the console home page's Environment section, click Clusters.
From the Summary of Clusters page, click New and select Cluster.
From the Create a New Cluster page, use the name field to enter a name for the WebLogic Server cluster.
Leave the default messaging mode (Unicast) and change the broadcast channel as required, or use the drop-down list and select Multicast and provide a different multicast address and port if required.
Click OK. The Summary of Clusters page displays and the Cluster table lists the cluster.
From the Clusters table, click the cluster to configure it.
From the Coherence tab, use the Coherence Cluster drop-down list and select a Coherence cluster to associate it with this WebLogic Server cluster. Click Save. By default, the managed Coherence servers assigned to this WebLogic Server cluster will be storage-enabled Coherence members (cache servers) as indicated by the Local Storage Enabled field.
Repeat steps 1 to 6 to create another WebLogic Server cluster to be used for the application tier. From the Coherence tab, use the Coherence Cluster drop-down list and select the Coherence cluster to associate it with this WebLogic Server cluster.
Click the Local Storage Enabled check box to remove the check mark and disable storage on the application tier. The managed Coherence servers assigned to this WebLogic Server cluster will be storage-disabled Coherence members (cache factory clients). Click Save.
(If applicable) Repeat steps 1 to 6 to create another WebLogic Server cluster to be used for the proxy tier. From the Coherence tab, use the Coherence Cluster drop-down list and select the Coherence cluster to associate it with this WebLogic Server cluster.
Click the Local Storage Enabled check box to remove the check mark and disable storage on the proxy tier. The managed Coherence servers assigned to this WebLogic Server cluster are storage-disabled Coherence members. Click Save.
(If applicable) Repeat steps 1 to 6 to create another WebLogic Server cluster to be used for the extend client tier. From the Coherence tab, use the Coherence Cluster drop-down list and select the Coherence cluster to associate it with this WebLogic Server cluster.
Click the Local Storage Enabled check box to remove the check mark and disable storage on the proxy tier. The managed Coherence servers assigned to this WebLogic Server cluster are storage-disabled Coherence members. Click Save.

Parent topic: Setting Up a WebLogic Server Domain Topology for Coherence

Create Managed Coherence Servers For a Coherence Deployment Tier

Managed servers that are associated with a Coherence cluster are Coherence cluster members and are referred to as managed Coherence servers. Use the instructions in this section to create managed servers and associate them with a WebLogic Server cluster that is configured as a Coherence deployment tier. Managed servers automatically inherit Coherence settings from the WebLogic Server cluster. Existing managed Coherence servers can be associated with a WebLogic Server cluster as well.

To create managed servers for a Coherence deployment tier:

From the console home page's Environment section, click Servers.
Click New to create a new managed server.
From the Create a New Server page, enter the server's properties as required.
Click the Yes option to add the server to an existing cluster and use the drop-down list to select a WebLogic Server cluster that has been configured as a Coherence tier. The managed server inherits the Coherence settings from the WebLogic Server cluster.
Click Finish. The Summary of Servers page displays and the new server is listed.
Repeat these steps to create additional managed servers as required.
Click the Control tab and select the servers and click Start.

Parent topic: Setting Up a WebLogic Server Domain Topology for Coherence

Deploying Coherence Applications To a WebLogic Server Domain

This section includes the following topics:

Parent topic: Deploying Coherence Applications to WebLogic Server

Overview of WebLogic Server Domain Deployment

Each Coherence deployment tier must include a Coherence application module. Deploying the application module starts the services that are defined in the GAR's cache configuration file. See Packaging Coherence Applications for WebLogic Server.

Deploy Coherence modules as follows:

Data Tier (cache servers) – 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 the WebLogic deployment infrastructure copies the module to each managed Coherence server.
Application Tier (cache clients) – Deploy the EAR that contains GAR and the client implementation (Web Application, EJB, and so on) 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 the WebLogic deployment infrastructure copies the module to each managed Coherence server.
Proxy Tier (proxy servers) – Deploy the standalone GAR to each managed Coherence server of the proxy tier. If the proxy tier is setup as a WebLogic Server cluster, deploy the GAR to the cluster and the WebLogic deployment infrastructure copies the module to each managed Coherence server.

Note:

Proxy tier managed Coherence servers must include a proxy service definition in the cache configuration file. You can deploy the same GAR to each tier, and then override the cache configuration file of just the proxy tier servers by using a cluster-level cache configuration file. See Overriding a Cache Configuration File in Administering Clusters for Oracle WebLogic Server.
Extend Client Tier (extend clients) – Deploy the EAR that contains the GAR and the extend client implementation to each managed server that hosts the extend client. 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 server.

Note:

Extend tier managed servers must include a remote cache service definition in the cache configuration file. You can deploy the same GAR to each tier, and then override the cache configuration file of just the extend tier servers by using a cluster-level cache configuration file. See Overriding a Cache Configuration File in Administering Clusters for Oracle WebLogic Server.

Parent topic: Deploying Coherence Applications To a WebLogic Server Domain

Deploy the Data Tier GAR

To deploy a GAR on the data tier:

From the console home page's Your Deployed Resources section, click Deployments.
Click Install.
From the Install Application Assistant page, locate and select the GAR to be deployed. Click Next.
Select the data tier (WebLogic Server cluster or standalone managed Coherence servers) to which the GAR should be deployed. Click Next.
Edit the Source accessibility settings and select the option to have the module copied to each target. Click Finish. The Summary of Deployments page displays and the GAR is listed in the Deployments table.
From the list of deployments, select the check box for the GAR and click Start.

Parent topic: Deploying Coherence Applications To a WebLogic Server Domain

Deploy the Application Tier EAR

To deploy an EAR on the application tier:

From the console home page's Your Deployed Resources section, click Deployments.
Click Install.
From the Install Application Assistant page, locate and select the EAR to be deployed. Click Next.
Keep the default target style and click Next.
Select the application tier (WebLogic Server cluster or standalone managed Coherence servers) to which the EAR should be deployed. Click Next.
Edit the Source accessibility settings and select the option to have the module copied to each target. Click Finish. The Summary of Deployments page displays and the EAR is listed in the Deployments table.
From the list of deployments, select the check box for the EAR and click Start.

Parent topic: Deploying Coherence Applications To a WebLogic Server Domain

Deploy the Proxy Tier GAR

To deploy a GAR on the proxy tier

From the console home page's Your Deployed Resources section, click Deployments.
Click Install.
From the Install Application Assistant page, locate and select the GAR to be deployed. Click Next.
Select the proxy tier (WebLogic Server cluster or standalone managed Coherence servers) to which the GAR should be deployed. Click Next.
Edit the Source accessibility settings and select the option to have the module copied to each target. Click Finish. The Summary of Deployments page displays and the GAR is listed in the Deployments table.
From the list of deployments, select the check box for the GAR and click Start.

Parent topic: Deploying Coherence Applications To a WebLogic Server Domain

Performing Basic Coherence Administration Tasks

Administrators use WebLogic Server tools to manage a Coherence environment within a WebLogic domain. These tools simplify the tasks of administering a cluster and cluster members. This section provides an overview of using the Administration Console tool to perform basic administrative task. See Oracle WebLogic Server Administration Console Online Help. Many of the tasks can also be performed using the WebLogic Scripting Tool (WLST). See Using the WebLogic Scripting Tool in Understanding the WebLogic Scripting Tool.

Table 1-1 Basic Administration Task in the Administration Console

To...	Use the...
Create a Coherence cluster	Coherence Clusters page
Add or remove cluster members or WebLogic Server clusters from a Coherence Cluster	Members Tab located on a Coherence cluster's Settings page.
Configure unicast or multicast settings for a Coherence cluster	General Tab located on a Coherence cluster's Settings page. If unicast is selected, the default well known addresses configuration can be overridden using the Well Known Addresses tab.
Use a custom cluster configuration file to configure a Coherence cluster	General Tab located on a Coherence cluster's Settings page
Import a cache configuration file to a cluster member and override the cache configuration file deployed in a GAR	Cache Configurations Tab located on a Coherence cluster's Settings page
Configuring Logging	Logging Tab located on a Coherence cluster's Settings page
Assign a managed server to a Coherence Cluster	Coherence Tab located on a managed server's Settings page
Configure Coherence cluster member properties	Coherence Tab located on a managed server's Settings page
Associate a WebLogic Server cluster with a Coherence cluster and enable or disable storage for the managed Coherence servers of the cluster	Coherence Tab located on a WebLogic Server cluster's Settings page
Assign a managed server to WebLogic Server cluster that is associated with a Coherence cluster	General Tab located on a managed server's Settings page

Parent topic: Deploying Coherence Applications to WebLogic Server

Deploying Coherence Applications to an Application Server (Generic)

Java EE applications that are deployed to an application server, other than WebLogic Server, have two options for deploying Coherence: as an application server library or as part of a Java EE module.

Coherence cluster members are class loader scoped. Therefore, the option selected results in a different deployment scenario. All modules share a single cluster member if Coherence is deployed as an application server library. Whereas, a Java EE module is its own cluster member if Coherence is deployed as part of the module. Each option has its own benefits and assumptions and generally balances resource utilization with how isolated the cluster member is from other modules.

Note:

For Coherence*Web deployment, see Using Coherence*Web on Other Application Servers in Administering HTTP Session Management with Oracle Coherence*Web.

This section includes the following topics:

Parent topic: Deploying Coherence Applications

Deploying Coherence as an Application Server Library

Coherence can be deployed as an application server library. In this deployment scenario, an application server's startup classpath is modified to include the COHERENCE_HOME/lib/coherence.jar library. In addition, any objects that are being placed into the cache must also be available in the server's classpath. Consult your application server vendor's documentation for instructions on adding libraries to the server's classpath.

This scenario results in a single cluster member that is shared by all applications that are deployed in the server's containers. This scenario minimizes resource utilization because only one copy of the Coherence classes are loaded into the JVM. See Running Multiple Applications in a Single Cluster.

Parent topic: Deploying Coherence Applications to an Application Server (Generic)

Deploying Coherence in a Java EE Module

Coherence can be deployed within an EAR file or a WAR file. This style of deployment is generally preferred because modification to the application server run-time environment is not required and because cluster members are isolated to either the EAR or WAR.

This section includes the following topics:

Parent topic: Deploying Coherence Applications to an Application Server (Generic)

Deploying Coherence Within an EAR

Coherence can be deployed as part of an EAR. This deployment scenario results in a single cluster member that is shared by all Web applications in the EAR. Resource utilization is moderate because only one copy of the Coherence classes are loaded per EAR. However, all Web applications may be affected by any one module's use of the cluster member. See Running Multiple Applications in a Single Cluster.

To deploy Coherence within an enterprise application:

Copy the coherence.jar library to a location within the enterprise application directory structure.
Using a text editor, open the META-INF/application.xml deployment descriptor.
Add a <java> element that contains the path (relative to the top level of the application directory) and name of the coherence library. For example:
```
<application>
   <display-name>MyApp</display-name>
   <module>
      <java>coherence.jar</java>
   </module>
   ...
</application>
```
Make sure any objects that are to be placed in the cache are added to the application in the same manner as described above.
Save and close the descriptor.
package and deploy the application.

Parent topic: Deploying Coherence in a Java EE Module

Deploying Coherence Within a WAR

Coherence can be deployed as part of a Web application. This deployment scenario results in each Web application having its own cluster member, which is isolated from all other Web applications. This scenario uses the most amount of resources because there are as many copies of the Coherence classes loaded as there are deployed Web applications that include Coherence. This scenario is ideal when deploying only a few Web applications to an application server.

To deploy Coherence within a Web application:

Copy the coherence.jar library to the Web Application's WEB-INF/lib directory.
Make sure any objects that are to be placed in the cache are located in either the WEB-INF/lib or WEB-INF/classes directory.
Package and deploy the application.

Parent topic: Deploying Coherence in a Java EE Module

Running Multiple Applications in a Single Cluster

Coherence can be deployed in shared environments where multiple applications use the same cluster but define their own set of Coherence caches and services. For such scenarios, each application uses its own cache configuration file that includes a scope name that controls whether the caches and services are allowed to be shared among applications.

This section includes the following topics:

Parent topic: Deploying Coherence Applications

Specifying a Scope Name

The <scope-name> element is used to specify a service namespace that uniquely identifies the caches and services in a cache configuration file. If specified, all caches and services are isolated and cannot be used by other applications that run on the same cluster.

The following example configures a scope name called accounts and results in the use of accounts as a prefix to all services instantiated by the ConfigurableCacheFactory instance that is created based on the configuration. The scope name is an attribute of a cache factory instance and only affects that cache factory instance.

Note:

The prefix is only used for service names, not cache names.

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>accounts</scope-name>
      </defaults>
   <caching-scheme-mapping>
   ...

Parent topic: Running Multiple Applications in a Single Cluster

Scoping Applications in WebLogic Server

Multiple deployed Coherence applications (GARs) are isolated by a service namespace and by ClassLoader by default in WebLogic Server and do not require scope name configuration. However, a scope name may still be configured to share caches between GARs. Directly configuring the scope in the cache configuration file is typically performed for advanced use cases.

Note:

If you want to deploy multiple GARs with the same scope name, then the configuration files in all GARs must be identical; otherwise, the deployment fails.

The deployment name is used as the default scope name when deploying a GAR. If a deployment name is not specified during deployment, the artifact name is used as the deployment name. For example, for the MyApp.gar module, the default deployment name is MyApp. In the case of a GAR packaged in an EAR, the deployment name is the module name specified for the GAR in the weblogic-application.xml file.

Parent topic: Running Multiple Applications in a Single Cluster

Scoping Applications in a Java EE Environment (Generic)

Deploying Coherence as an application server library, or as part of an EAR, allows multiple applications to use the same cluster as a single cluster member (one JVM). In such deployment scenarios, multiple applications may choose to use a single set of Coherence caches and services that are configured in a single coherence-cache-config.xml file. This type of deployment is only suggested (and only practical) in controlled environments where application deployment is coordinated. The likelihood of collisions between caches, services and other configuration settings is high and may lead to unexpected results. Moreover, all applications may be affected by any one application's use of the Coherence node.

The alternative is to have each application include its own cache configuration file that defines the caches and services that are unique to the application. The configurations are then isolated by specifying a scope name using the <scope-name> element in the cache configuration file. Likewise, applications can explicitly allow other applications to share their caches and services if required. This scenario assumes that a single JVM contains multiple ConfigurableCacheFactory instances that each pertains to an application.

This section includes the following topics:

Parent topic: Running Multiple Applications in a Single Cluster

Isolating Applications in a JavaEE Environment

The following example demonstrates the steps that are required to isolate two Web applications (trade.war and accounts.war) from using each other's caches and services:

Create a cache configuration file for the trade application (for example, trade-cache-config.xml) that defines a scope name called trade and include any cache scheme definitions for the application:

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>trade</scope-name>
      </defaults>
   ...

Create a cache configuration file for the accounts application (for example, accounts-cache-config.xml) that defines a scope name called accounts and include any cache scheme definitions for the application:

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>accounts</scope-name>
      </defaults>
   ...

Ensure the cache configurations files are included in their respective WAR files (typically in the WEB-INF/classes directory) so that they can be loaded at run time and used by the application.

Parent topic: Scoping Applications in a Java EE Environment (Generic)

Sharing Application Data in a JavaEE Environment

Applications can share data by allowing access to their caches and services. The following example demonstrates allowing a Web application (trade.war) to access the caches and services of another Web application (accounts.war):

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>trade</scope-name>
      </defaults>
   ...

Create a cache configuration file (for example, accounts-cache-config.xml) for the accounts application that defines a scope name called accounts and include any cache scheme definitions for the application:

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>accounts</scope-name>
      </defaults>
   ...

Ensure the cache configurations files are included in their respective WAR files (typically in the WEB-INF/classes directory) so that they can be loaded at run time and used by the application.
The trade application must also include the accounts-cache-config.xml file to access the caches and services of the accounts application.

The trade application can then use the following pattern to create cache factories for the accounts application:

ClassLoader loader = ...
CacheFactoryBuilder builder = CacheFactory.getCacheFactoryBuilder();
ConfigurableCacheFactory tradesCcf =
   builder.getConfigurableCacheFactory(tradesUri, loader);
ConfigurableCacheFactory accountsCcf =
   builder.getConfigurableCacheFactory(accountsUri, loader);

Parent topic: Scoping Applications in a Java EE Environment (Generic)

Scoping Applications in a Standalone Environment

Standalone applications that use a single Coherence cluster can each include their own cache configuration files; however, these configurations are coalesced into a single ConfigurableCacheFactory. Since there is a 1 to 1 relationship between ConfigurableCacheFactory and DefaultCacheServer, application scoping is not feasible within a single cluster node. Instead, one or more instances of DefaultCacheServer must be started for each cache configuration, and each cache configuration must include a scope name.

The following example isolates two applications (trade and accounts) from using each other's caches and services:

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>trade</scope-name>
      </defaults>
   ...

Start a DefaultCacheServer instance that loads the trade-cache-config.xml cache configuration file.

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
      <defaults>
         <scope-name>accounts</scope-name>
      </defaults>
   ...

Start a DefaultCacheServer instance that loads the accounts-cache-config.xml cache configuration file.

Note:

To share data between applications, the applications must use the same cache configuration file. Coherence does not support using multiple cache configurations which specify the same scope name.

Parent topic: Running Multiple Applications in a Single Cluster

Providing a Custom Scope Resolver

The com.tangosol.net.ScopeResolver interface allows containers and applications to modify the scope name for a given ConfigurableCacheFactory at run time to enforce (or disable) isolation between applications. Implement the ScopeResolver interface and add any custom functionality as required.

To enable a custom scope resolver, the fully qualified name of the implementation class must be defined in the operational override file using the <scope-resolver> element within the <cache-factory-builder-config> node. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cache-factory-builder-config>
      <scope-resolver>
         <class-name>package.MyScopeResolver</class-name>
      </scope-resolver>
   </cache-factory-builder-config>
<coherence>

As an alternative, the <instance> element supports the use of a <class-factory-name> element to specify a factory class that is responsible for creating ScopeResolver instances, and a <method-name> element to specify the static factory method on the factory class that performs object instantiation. The following example gets a custom scope resolver instance using the getResolver method on the MyScopeResolverFactory class.

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cache-factory-builder-config>
      <scope-resolver>
         <class-factory-name>package.MyScopeReolverFactory</class-factory-name>
         <method-name>getResolver</method-name>
      </scope-resolver>
   </cache-factory-builder-config>
<coherence>

Any initialization parameters that are required for an implementation can be specified using the <init-params> element. The following example sets an isDeployed parameter to true.

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cache-factory-builder-config>
      <scope-resolver>
         <class-name>package.MyScopeResolver</class-name>
         <init-params>
            <init-param>
               <param-name>isDeployed</param-name>
               <param-value>true</param-value>
            </init-param>
         </init-params>
      </scope-resolver>
   </cache-factory-builder-config>
<coherence>

Parent topic: Running Multiple Applications in a Single Cluster