This chapter provides instructions for installing and running 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 Developing Remote Clients for Oracle Coherence and the Administering HTTP Session Management with Oracle Coherence*Web, respectively, for instructions on installing these components.
This chapter includes the following sections:
The following are the minimum requirements for running the Coherence installer:
300 MHz CPU
512 MB swap space
256 color monitor (required for GUI-based installation only)
Java Development Kit (JDK) 1.6.0_4 or later
The following are the suggested minimum system requirements for running Coherence in a development environment:
100 MB disk space for complete installation (includes API documentation and examples)
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 Administering Oracle Coherence for recommendations on calculating cache size.
JVM (JRE or JDK) 1.7 or later for Cache servers and clients; 1.6 or later for Coherence*Extend clients. A JDK is often used during development and offers tools for monitoring and troubleshooting Java applications, but a JDK is not required to run Coherence.
Windows or UNIX-based system that supports the required Java Version
Network adapter
Coherence is installed using the Oracle Universal Installer. The installer provides both installation and patching services for Oracle products. The following installers are available for Coherence and detailed in this section.
fmw_version_coherence.jar – A full Coherence installation that can be run in either graphical mode or silent mode. See Running the Coherence Installer.
fmw_version_coherence_quick.jar – A minimum Coherence installation that is always run in silent mode. The quick installer provides a smaller footprint and does not include API documentation or examples. See Running the Coherence Quick Installer.
fmw_version_coherence_quick_supplemental.jar – A supplemental installation that is always run in silent mode. The supplemental installer contains only API documentation and examples. See Running the Coherence Supplemental Installer.
fmw_version_wls.jar – A full WebLogic Server installation that includes Coherence. See Installing Coherence with WebLogic Server.
Coherence is always installed to an ORACLE_HOME/coherence directory. The complete path to the coherence directory is referred to as COHERENCE_HOME throughout the Coherence documentation.
The Coherence installer is distributed as an executable Java ARchive (JAR) file called fmw_version_coherence.jar. Use the java command to run the installer on the target computer. The installer supports both a graphical mode and a silent mode. For detailed help on the installer's options, use the -help argument when running the installer.
This section includes the following topics:
To perform a Coherence installation in graphical mode:
Copy the fmw_version_coherence.jar file to the target computer.
From a command prompt, change directories to the location of the coherence_version.jar file and execute the following command (assuming that JAVA_HOME/bin is located on the computer's PATH):
java -jar fmw_version_coherence.jar
The Oracle Coherence installer starts and the Welcome screen displays. On UNIX-based platforms, you are first prompted (prior to the Welcome screen) to select an inventory directory where Oracle product inventory data is written. Follow the on-screen instructions to create an inventory directory.
Click Next. The Installation Location screen displays. Use the drop-down list to select an existing ORACLE_HOME directory to which Coherence will be installed, or enter an absolute path to create a new Coherence ORACLE_HOME directory. Click Browse to search for a directory if required. The directory cannot contain an existing Coherence installation.
Click Next. The Installation Type screen displays. Select which options to install.
Click Next. The Installation Summary screens displays. Verify the installation. Click Save Response File if you intend to duplicate this installation on additional computers. A response file is created that can be used to perform a silent install with the exact same installation settings. For details on performing a silent install, see "Performing a Coherence Installation In Silent Mode".
Click Install. The Installation Progress screen displays and shows all tasks that have succeeded and failed.
Click Next. The Installation Complete screen displays and shows a summary of the installation.
Click Finish to close the Oracle Coherence installer.
Silent mode allows Coherence to be installed without using a graphical interface and is ideal for remote installations or when incorporating the installation as part of a script. Silent mode typically uses a response file (.rsp) that contains the installation parameters as name=value pairs. Create a response file by running the installer in graphical mode and then saving the installation parameters to a response file at the Installation Summary screen. Use the saved file to replicate the installation on other computers or modify the file to change the installation as required.
To perform a Coherence installation in silent mode:
Copy the fmw_version_coherence.jar file and a response file to the target computer.
From a command prompt, change directories to the location of the coherence_version.jar file and execute the following command (assuming that JAVA_HOME/bin is located on the computer's PATH):
java -jar fmw_version_coherence.jar -silent -responseFile full_path_to_response_file -waitForCompletion
On UNIX-based platforms, the installer requires the location of the oraInst.loc inventory directory pointer file if it is not found in the default location (/etc). If this is the first time that an Oracle product has been installed on this computer, you can use the createCentralInventory.sh script to set up an inventory directory pointer file in the /etc directory. The script requires root permissions.
If you want to use a custom location for the oraInst.loc file, use the -invPtrLoc installer option to specify the location. For example:
java -jar fmw_version_coherence.jar -silent -responseFile full_path_to_response_file -waitForCompletion -invPtrLoc /MyDirectory/oraInst.loc
The contents of the oraInst.loc file contains the location and the ownership group for the inventory directory. For example:
inventory_loc=/MyDirectory/oraInventory
inst_group=group
The quick install is distributed as an executable JAR file called fmw_version_coherence_quick.jar. Use the java command to run the installer on the target computer. For detailed help on the installer's options, use the -help argument when running the installer.
The quick install performs a silent install with no options. The distribution includes less lifecycle tools but does register the Coherence components as part of the Oracle inventory, which allows future lifecycle operations to work. In addition, the installation does not include API documentation or code examples. The result is a faster installation process and a smaller installation footprint than the regular Coherence installer and is an ideal method for installing Coherence as part of a script without user interaction.
To perform a Coherence quick installation:
Copy the fmw_version_coherence_quick.jar file to a directory on the target computer.
From a command prompt, change directories to the location of the fmw_version_coherence_quick.jar file and execute the following command (assuming that JAVA_HOME/bin is located on the computer's PATH):
java -jar fmw_version_coherence_quick.jar ORACLE_HOME=/oracle
The value of the ORACLE_HOME variable specifies the ORACLE_HOME directory to which Coherence will be installed. The value must be an absolute path. If the directory already exists, it must be empty or it must be an existing valid ORACLE_HOME. The directory cannot contain an existing Coherence installation. If the directory does not exist, the installer creates the directory. You can also start the installation from an empty current working directory and omit the ORACLE_HOME variable; the current working directory becomes the ORACLE_HOME directory. For example:
cd /oracle
java -jar /tmp/fmw_version_coherence_quick.jar
On UNIX-based platforms, the quick installer attempts to find the oraInst.loc inventory directory pointer file in the /etc directory. If the file is not found, the /tmp directory is used as the inventory directory. If this is the first time that an Oracle product has been installed on this computer, you can use the createCentralInventory.sh script to set up an inventory directory pointer file in the /etc directory. The script requires root permissions.
If you want to use a custom location for the oraInst.loc file, use the -invPtrLoc installer option to specify the location. For example:
java -jar fmw_version_coherence_quick.jar -invPtrLoc /MyDirectory/oraInst.loc
The contents of the oraInst.loc file contains the location and the ownership group for the inventory directory. For example:
inventory_loc=/MyDirectory/oraInventory
inst_group=group
The supplemental install is distributed as an executable JAR file called fmw_version_coherence_quick_supplemental.jar. The distribution is used to install the API documentation and code examples to an existing Coherence installation. The supplemental installer performs a silent install with no options. It is typically used together with the quick installer to perform an installation as part of a script without user interaction. If you do not require the API documentation or code examples, then you can skip the supplemental installation.
Copy the fmw_version_coherence_quick_supplemental.jar file to the ORACLE_HOME directory where Coherence is installed.
From a command prompt, change directories to the location of the fmw_version_coherence_quick_supplemental.jar file and execute the following command (assuming that JAVA_HOME/bin is located on the computer's PATH):
java -jar fmw_version_coherence_quick_supplemental.jar
The installation starts and status messages are emitted.
The WebLogic Server installer includes the Coherence distribution and installs Coherence in the same ORACLE_HOME directory as WebLogic Server. WebLogic Server includes a Coherence integration that standardizes how Coherence is managed and deployed within a WebLogic Server domain. The integration makes Coherence a subsystem of WebLogic Server and allows Coherence environments to be administered using WebLogic Server tools and infrastructure, such as Java EE-styled packaging and deployment, remote server management, server clusters, WebLogic Scripting Tool (WLST) automation, and configuration through the Administration Console. For details about installing Coherence with WebLogic Server, see Installing and Configuring Oracle WebLogic Server and Coherence.
The following directories 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 the Coherence Java API Reference and a link to the Coherence documentation on the Oracle Technology Network (OTN). The Coherence Java API Reference is distributed as a JAR file and must be extracted. The JAR can also be imported into an IDE for easy access during development.
To extract the Coherence Java API Reference, execute the following command from the /api directory (assuming that JAVA_HOME/bin is located on the computer's PATH):
jar -xvf CoherenceJavaDoc-version.jar
example – This directory contains a set of examples that demonstrate many Coherence features and how to use the Coherence API. For detailed instructions on building and running the examples, see Tutorial for Oracle Coherence.
lib – This directory includes all delivered libraries. The coherence.jar library is the main development and run-time library and is discussed in detail throughout this documentation.
plugins – This directory contains plug-ins for common integrations. Coherence provides a plug-in for Maven and Java VisualVM. The Maven plug-ins are used to integrate Coherence as part of a Maven build process. For details about the Coherence Maven plugins, see "Integration with Maven". The Java VisualVM plug-in used to provide Coherence monitoring. For details about the Java VisualVM plug-in, see Managing Oracle Coherence.
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 ORACLE_HOME/coherence directory.
The COHERENCE_HOME/bin directory includes 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.
Maven is a build and dependency system that allows the configuration of project dependencies, 3rd party dependencies and definition of a build lifecycle. Software projects often use Maven to simplify and standardize their build process. For details about Maven, see http://maven.apache.org/.
Oracle Middleware provides a plug-in that synchronizes an Oracle home directory with a Maven repository and standardizes Maven usage and naming conventions. The plug-in allows Coherence artifacts to be uploaded to a Maven repository, which simplifies how the artifacts are consumed in development projects. For details about setting up Maven and using the synchronization plug-in, see Developing Applications Using Continuous Integration.
In addition, the Maven integration includes an archetype and packaging plug-in for a Coherence Grid Archive (GAR). A Coherence GAR is a module type that is typically used to deploy Coherence applications within a WLS domain. The Maven archetype plug-in generates a GAR structure and provides example configuration files. The packaging plug-in generates a GAR based on a project's contents and dependencies and ensures that the dependencies, source, and configuration files are copied into the GAR.
The Maven plug-in and configuration files for Coherence are located in the COHERENCE_HOME/plugins directory. The Maven GAR plug-in and archetype are installed in the enterprise repository as part of the synchronization plug-in. For instructions on using the plug-in to incorporate Coherence into a build process, see Developing Applications Using Continuous Integration.
Coherence is deinstalled using the Oracle Fusion Middleware deinstaller. The deinstaller allows you to select which components in a Coherence ORACLE_HOME directory to deinstall and can also be used to completely remove a Coherence ORACLE_HOME directory.
To deinstall Coherence using the deinstallation wizard:
Start the deinstaller using the Coherence ORACLE_HOME/oui/bin/deinstall.sh script on UNIX-based platforms or the Coherence ORACLE_HOME\oui\bin\deinstall.cmd script on Windows. A shortcut to the script is available on Windows and is located in the Oracle program group on the start menu. The Oracle Fusion Middleware Deinstaller starts and the Welcome screen displays.
Click Next. The Deinstallation Summary screen displays and lists the features that will be deinstalled.
Click Deinstall. The Deinstallation Progress screen displays and shows all tasks that have succeeded and failed.
Click Next. The Deinstallation Complete screen displays and shows a summary of the Deinstallation.
Click Finish to close the Oracle Fusion Middleware Deinstaller.
Note:
Additional files in theORACLE_HOME directory must be manually deleted. On Windows, you must also manually delete the Oracle program group on the Start menu.