Skip Headers
Oracle® Coherence Developer's Guide
Release 3.7

Part Number E18677-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

7 Starting and Stopping Cluster Members

This chapter provides basic instructions for starting and stopping cache servers and cache clients. If you are having difficulties establishing a cluster when using multicast, see Oracle Coherence Administrator's Guide for instructions on performing a multicast connectivity test.

The following sections are included in this chapter:

7.1 Starting Cache Servers

Cache servers are cluster members that are responsible for storing cached data. A cluster may be comprised of many cache servers. Each cache server runs in its own JVM.

The following topics are included in this section:

7.1.1 Starting Cache Servers From the Command Line

The com.tangosol.net.DefaultCacheServer class is used to start a cache server instance from the command line. Use the Java -cp option to indicate the location of the coherence.jar file and the location where the tangosol-coherence-override.xml and coherence-cache-config.xml files are located. The location of the configuration files must precede the cohernce.jar file on the classpath; otherwise, the default configuration files that are located in the coherence.jar file are used to start the cache server instance. See Chapter 3, "Understanding Configuration," for detailed information on configuration files.

The following example starts a cache server member and uses any configuration files that are placed in COHERENCE_HOME\config:

java -server -Xms512m -Xmx512m -cp COHERENCE_HOME\config;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

The COHERENCE_HOME\bin\cache-server script is provided as a convenience and can startup a cache server instance. The script sets up a basic environment and then runs the DefaultCacheServer class. There is a script for both the Windows and UNIX-based platforms. The scripts are typically modified as required for a particular cluster.

Tip:

During testing, it is sometimes useful to create multiple scripts with different names that uniquely identify each cache server. For example: cahe-server-a, cache-server-b, and so on.

7.1.2 Starting Cache Servers Programmatically

An application can use or extend the DefaultCacheServer class as required when starting a cache server. For example, an application may want to do some application-specific setup or processing before starting a cache server and its services.

For basic use cases, the main method can be called and requires two arguments: the name of a cache configuration file that is found on the classpath, and the number of seconds between checks for stopped services. Stopped services are started if they are set to be automatically started (as configured by an <autostart> element in the cache configuration file). The following example starts a cache server using the main method:

String[] args = new String[]{"my-cache-config.xml", "5"};
DefaultCacheServer.main(args);

The DefaultCacheServer(DefaultConfigurableCacheFactory) constructor uses a factory class to create a cache server instance that uses a specified cache configuration file. The following example creates a DefaultCacheServer instance and uses the startAndMonitor(long) method to start a cache server as in the previous example:

DefaultConfigurableCacheFactory factory;
factory = new DefaultConfigurableCacheFactory("my-cache-config.xml");

DefaultCacheServer dcs = new DefaultCacheServer(factory);
dcs.startAndMonitor(5000);

Two static start methods (start() and start(ConfigurableCacheFactory)) are also available to start a cache server and return control. However, the CacheFactory class is typically used instead of these methods which remain for backward compatibility.

Applications that require even more fine-grained control can subclass the DefaultCacheServer class and override its methods to perform any custom processing as required. See Oracle Coherence Java API Reference for detailed information on the DefaultCacheServer class.

7.2 Starting Cache Clients

Cache clients are cluster members that join the cluster to interact with the cluster's services. Cache clients can be as simple as an application that gets and puts data in a cache or can be as complex as a data grid compute application that processes data that is in a cache. The main difference between a cache client and a cache server is that cache clients are generally not responsible for cluster storage.

The following topics are included in this section:

7.2.1 Disabling Local Storage

Cache clients that use the partition cache service (distributed caches) should not maintain any partitioned data. Cache clients that join the cluster in this perform better and use less resources. Partitioned data should only be distributed among cache server instances.

Local storage is disabled on a per-process basis using the tangosol.coherence.distributed.localstorage system property. This allows cache clients and servers to use the same configuration descriptors. For example:

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

7.2.2 Using the CacheFactory Class to Start a Cache Client

Any application that uses the com.tangosol.net.CacheFactory class to get an instance of a cache becomes a cluster member and is considered a cache client. The following example demonstrates the most common way of starting a cache client:

CacheFactory.ensureCluster();
NamedCache cache = CacheFactory.getCache("cache_name");

When starting an application that is a cache client, use the Java -cp option to indicate the location of the coherence.jar file and the location where the tangosol-coherence-override.xml and coherence-cache-config.xml files are located. The location of the configuration files must precede the cohernce.jar file on the classpath; otherwise, the default configuration files that are located in the coherence.jar file are used to start the cache server instance. See Chapter 3, "Understanding Configuration," for detailed information on configuration files. For example:

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

7.3 Stopping Cluster Members

The following topics are included in this section:

7.3.1 Stopping Cluster Members From the Command Line

Cluster members are most often shutdown using the kill command when on the UNIX platform and Ctrl+c when on the Windows platform. These commands initiate the standard JVM shutdown hook which is invoked upon normal JVM termination.

Note:

Issuing the kill -9 command triggers an abnormal JVM termination and the shutdown hook does not run. However, a graceful shutdown is generally not required if a service is known to be node-safe (as seen using JMX management) before termination.

The action a cluster member takes when receiving a shutdown command is configured in the operational override file within the <shutdown-listener> element. The following options are available:

  • none — perform no explicit shutdown actions. This is the suggested value for production unless testing has verified that the behavior on external shutdown is exactly what is desired.

  • force — (default) perform a hard-stop on the node by calling Cluster.stop(). This is the default out-of-box action.

  • graceful — perform a normal shutdown by calling Cluster.shutdown()

  • true — same as force

  • false — same as none

The following example sets the shutdown hook to none.

<?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">
   <cluster-config>
      <shutdown-listener>
         <enabled system-property="tangosol.coherence.shutdownhook">none</enabled>
      </shutdown-listener>
   </cluster-config>
</coherence>

The tangosol.coherence.shutdownhook system property is used to specify the shutdown hook behavior instead of using the operational override file. For example:

-Dtangosol.coherence.shutdownhook=none

7.3.2 Stopping Cache Servers Programmatically

The DefaultCacheServer class provides two methods that are used to shutdown a cache server:

Note:

Shutdown is supposed to be called in a standalone application where it shuts down the instance which the DefaultCacheServer class itself maintains as a static member.
  • shutdown() – This is a static method that is used to shut down a cache server that was started on a different thread using the DefaultCacheServer.main() or DefaultCacheServer.start() methods.

  • shutdownServer() – This method is called on a DefaultCacheServer instance which an application keeps hold of.