Skip Headers
Oracle® Coherence Developer's Guide
Release 3.6.1

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

Go to previous page
Go to next page
View PDF

2 Installing Oracle Coherence for Java

This chapter provides instructions for installing Oracle Coherence for Java (simply referred to as Coherence). The chapter does not include instructions for installing Coherence*Extend client distributions (C++ and .NET) or Coherence*Web. Refer to the Oracle Coherence Client Guide and the Oracle Coherence User's Guide for Oracle Coherence*Web, respectively, for instructions on installing these components.

The following sections are included in this chapter:

System Requirements

The following are suggested minimum system requirements for installing Coherence in a development environment:

Extracting the Distribution

Coherence is distributed as a ZIP file. Use a ZIP utility or the unzip command-line utility to extract the ZIP file to a location on the target computer. The extracted files are organized within a single directory called coherence. The complete path to the coherence directory is referred to as COHERENCE_HOME throughout this documentation. For example, C:\INSTALL_DIR\coherence.

The following example uses the unzip utility to extract the distribution to the /opt directory which is the suggested installation directory on UNIX-based operating systems. Use the ZIP utility provided with the target operating system if the unzip utility is not available.

unzip /path_to_zip/ -d /opt

The following example extracts the distribution using the unzip utility to the C:\ directory on the Windows operating system.

unzip C:\path_to_zip\ -d C:\

The following list describes the directories that are included in COHERENCE_HOME:

Setting Environment Variables

The following system environment variables can be set, but they are not required to run Coherence:

Running Coherence for the First Time

The COHERENCE_HOME/bin directory includes two scripts that are used during development and testing and are provided as a design-time convenience. The cache-server script starts a cache server using a default configuration. The coherence script starts a cache factory instance using a default configuration. The cache factory instance includes a command-line tool that is used to (among other things) create and interact with a cache.

In this scenario, a basic cluster is created and then the command-line tool is used to create and interact with a cache that is hosted in the cluster.

Create a Basic Cluster

In this step, a basic cluster is created that is comprised of three separate Java processes: a cache server and two cache factory instances. For simplicity, the three processes are collocated on a single machine. The cache server, by default, is configured to store backup data. The two cache factory instances, by default, are configured not to store backup data. As each process is started, they automatically join together and become cluster members (also referred to as cluster nodes).

For this example, the Coherence out-of-box default configuration is slightly modified to create a private cluster which ensures that these cluster members do not attempt to join an existing Coherence cluster that may be running on the network.


The Coherence default behavior is to use multicast to find cluster members. Coherence can be configured to use unicast if a network does not allow the use of multicast. See Part II, "Using Data Clusters" for information on configuring clusters to use unicast.

To create a basic cluster:

  1. Using a text editor, open the COHERENCE_HOME/bin/cache-server script.

  2. Modify the java_opts variable to include the tangosol.coherence.cluster and the tangosol.coherence.clusterport system properties as follows:

    set java_opts="-Xms%memory% -Xmx%memory% -Dtangosol.coherence.cluster=cluster_name -Dtangosol.coherence.clusterport=port"

    Replace cluster_name and port with values that are unique for this cluster. For example, use your name for the cluster name and the last four digits of your phone number for the port.

  3. Save and close the cache-server script.

  4. Repeat steps 1 to 3 for the COHERENCE_HOME/bin/coherence script.

  5. Run the cache-server script. The cache server starts and output is emitted that provides information about this cluster member.

  6. Run 2 instances of the coherence script. As each instance is started, output is emitted that provides information about the respective cluster members. Each instance returns a command prompt for the command-line tool.

Create a Cache

In this step, a cache is created and hosted on the basic cluster. A simple string is entered into the cache using the command-line tool of the first cache factory instance. The string is then retrieved from the cache using the command-line tool of the second cache factory instance. The example is simplistic and not very practical, but it does quickly demonstrate the distributed nature of Coherence caches. Moreover, these steps are typically performed directly using the Coherence API.

To create a cache:

  1. At the command prompt for either cache factory instance, create a cache named Test using the cache command:

    cache Test
  2. At the command prompt, use the put command to place a simple string in the new cache by entering a key/value pair (separated by a space):

    put key1 Hello

    The command returns and displays null. The put command always returns the previous value for a given key. The null value is returned because this is the first value entered for this key.

  3. Switch to the other cache factory instance and from the command prompt create the Test cache using the cache command:

    cache Test
  4. From this command prompt, retrieve the string in the cache using the get command and entering the key name:

    get key1

    The command returns and displays hello. Either cache factory process can be used to add or remove cache entries because the processes are part of the same cluster and because the Test cache is known to all cluster members. In addition, since the cache server is storing a backup of the cache data, either cache factory process (or both) can be shutdown and the cache data persists.