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
Network adapter
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/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 COHERENCE_HOME:
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 (.sh) formats.
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 COHERENCE_HOME/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 INSTALL_DIR/coherence directory.
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.
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 COHERENCE_HOME/bin/cache-server script.
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.
Save and close the cache-server script.
Repeat steps 1 to 3 for the COHERENCE_HOME/bin/coherence script.
Run 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 cache command:
cache Test
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.
Switch to the other cache factory instance and from the command prompt create the Test cache using the cache command:
cache Test
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 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.