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:
The following are suggested minimum system requirements for installing Coherence in a development environment:
65 MB disk space for installation
1 GB of RAM (assuming a maximum Java heap size of 512MB) – This amount of RAM can ideally support a maximum cache size of 150MB on a single node that is configured to store a backup of all data (150MB x 2) and leaves more than a 1/3 of the heap available for scratch and JVM tasks. See Oracle Coherence Administrator's Guide for recommendations on calculating cache size.
1.6 update 23 JVM or later
Windows or UNIX-based system that supports the required Java Version
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,
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/coherence-version_number.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\coherence-version_number.zip -d C:\
The following list describes the directories that are included in
bin – This directory includes a set of common scripts for performing different tasks, such as: starting a cache server, starting development tools, and performing network tests. The scripts are provided in both Windows (
.cmd) and UNIX-based (
doc – This directory contains a link to the Coherence documentation.
lib – This directory includes all delivered libraries. The
coherence.jar is the main development and run-time library and is discussed in detail throughout this documentation.
The following system environment variables can be set, but they are not required to run Coherence:
JAVA_HOME – This variable is used when running the scripts that are included in the
/bin directory. The value of this variable is the full path to the Java installation directory. If
JAVA_HOME is not set, the scripts use the computer's default Java installation. Set this variable to ensure that the scripts use a specific Java version.
COHERENCE_HOME – This variable is typically set as a convenience. The value of this variable is the full path to the
/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.
In this step, a basic cluster is created that contains three separate Java processes: a cache server and two cache factory instances. For simplicity, the three processes are collocated on a single computer. 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 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 unique cluster which ensures that these cluster members do not attempt to join an existing Coherence cluster that may be running on the network.
Note: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 "Using Well Known Addresses" for details.
To create a basic cluster:
Using a text editor, open 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"
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.
Save and close the
Repeat steps 1 to 3 for the
cache-server script. The cache server starts and output is emitted that provides information about this cluster member.
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.
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:
At the command prompt for either cache factory instance, create a cache named
Test using the
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
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.
Switch to the other cache factory instance and from the command prompt create the
Test cache using the
From this command prompt, retrieve the string in the cache using the
get command and entering the key name:
The command returns and displays
hello. Either cache factory process can 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.