Skip Headers
Oracle® Coherence Administrator's Guide
Release 3.7

Part Number E18679-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

1 Deploying Coherence-Based Applications

This chapter provides instructions for deploying Coherence into a run-time environment.

The following sections are included in this chapter:

1.1 Deploying Coherence with a Standalone Application

Standalone applications that leverage Coherence must include the COHERENCE_HOME/lib/coherence.jar library on the application's classpath. Any Coherence configuration files must also be included in the classpath and must appear before the Coherence library. For more information on configuration, see Oracle Coherence Developer's Guide.

The following example starts an application called MyApp. The classpath includes the coherence.jar library and the location (COHERENCE_HOME) that contains the tangosol-coherence-override.xml and coherence-cache-config.xml configuration files.

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

1.2 Deploying Coherence to an Application Server

Java EE applications that leverage Coherence 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:

This section does not include instructions for deploying Coherence*Web. See the Oracle Coherence*Web User's Guide for instructions on deploying Coherence*Web and clustering HTTP session data.

1.2.1 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" for detailed instructions on isolating Coherence applications from each other when choosing this deployment style.

1.2.2 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.

1.2.2.1 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" for detailed instructions for isolating Coherence applications from each other.

To deploy Coherence within an enterprise application:

  1. Copy the coherence.jar library to a location within the enterprise application directory structure.

  2. Using a text editor, open the META-INF/application.xml deployment descriptor.

  3. 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>
    
  4. Make sure any objects that are to be placed in the cache are added to the application in the same manner as described above.

  5. Save and close the descriptor.

  6. package and deploy the application.

1.2.2.2 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:

  1. Copy the coherence.jar library to the Web Application's WEB-INF/lib directory.

  2. 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.

  3. Package and deploy the application.

1.3 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.

The following topics are included in this section:

1.3.1 Specifying a Scope Name

The <scope-name> element is used to specify a name that uniquely identifies the caches and services in a cache configuration file. If specified, all caches and service 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 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. In addition, applications that do not explicitly configure a scope name are able to join each other and share 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">
   <scope-name>accounts</scope-name>
   <caching-scheme-mapping>
   ...

1.3.2 Scoping Applications in a JavaEE Environment

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.

Note:

This scenario assumes that a single JVM contains multiple instances of ConfigurableCacheFactory that each pertain to an application. WebLogic server is an example of this kind of environment.

1.3.2.1 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:

  1. 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">
       <scope-name>trade</scope-name>
       ...
    
  2. 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">
       <scope-name>accounts</scope-name>
       ...
    
  3. 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.

1.3.2.2 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):

  1. 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">
       <scope-name>trade</scope-name>
       ...
    
  2. 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">
       <scope-name>accounts</scope-name>
       ...
    
  3. 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.

  4. The trade application must also include the accounts-cache-config.xml file to access the caches and services of the accounts application.

  5. 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);
    

1.3.3 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:

  1. 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">
       <scope-name>trade</scope-name>
       ...
    
  2. Start a DefaultCacheServer instance that loads the trade-cache-config.xml cache configuration file.

  3. 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">
       <scope-name>accounts</scope-name>
       ...
    
  4. 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.

1.3.4 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>