1 Deploying Coherence Applications
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
This section includes the following topics:
- Deploying a Data Tier
- Deploying an Application Tier
- Deploying a Proxy Tier for Extend Clients
- Deploying Extend Clients
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
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 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 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.
To build custom Coherence Docker images, see the coherence-docker readme document on the Coherence CE GitHub repository - coherence-docker.
Parent topic: Deploying Coherence Applications
Deploying Coherence Applications to WebLogic Server
This section includes the following topics:
- Overview of the WebLogic Server Coherence Integration
- Packaging Coherence Applications for WebLogic Server
- Setting Up a WebLogic Server Domain Topology for Coherence
- Deploying Coherence Applications To a WebLogic Server Domain
- Performing Basic Coherence Administration Tasks
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:
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:
Parent topic: Packaging Coherence Applications for WebLogic Server
Setting Up a WebLogic Server Domain Topology for Coherence
This section includes the following topics:
- Guidelines for Setting Up a Domain Topology
- Create a Coherence Cluster
- Create Coherence Deployment Tiers
- Create Managed Coherence Servers For a Coherence Deployment Tier
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.
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.
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.
Deploying Coherence Applications To a WebLogic Server Domain
This section includes the following topics:
- Overview of WebLogic Server Domain Deployment
- Deploy the Data Tier GAR
- Deploy the Application Tier EAR
- Deploy the Proxy Tier GAR
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.
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.
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.
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.
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)
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.
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:
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:
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'sWEB-INF/lib
directory. - Make sure any objects that are to be placed in the cache are located in either the
WEB-INF/lib
orWEB-INF/classes
directory. - Package and deploy the application.
Parent topic: Deploying Coherence in a Java EE Module
Running Multiple Applications in a Single Cluster
This section includes the following topics:
- Specifying a Scope Name
- Scoping Applications in WebLogic Server
- Scoping Applications in a Java EE Environment (Generic)
- Scoping Applications in a Standalone Environment
- Providing a Custom Scope Resolver
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:
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
):
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:
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