1. Installing Oracle Coherence
  2. Installing Oracle Coherence for Java

2 Installing Oracle Coherence for Java

Several installers are available for installing Oracle Coherence for Java (simply referred to as Coherence). The installers are delivered as executable JAR files and facilitate the installation process. After you have installed Coherence, run the quick example to verify that Coherence is successfully installed.

Note:

For instructions about installing a Coherence*Extend client distribution, see Installing a Client Distribution. For instructions about installing Coherence*Web to an application server, see Installing Coherence*Web to an Application Server.

This chapter includes the following sections:

System Requirements

Coherence has different requirements for installation and runtime.

Runtime Requirements

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. This recommendation is considered a basic starting point and should not be considered a rule. See JVM Tuning in Administering Oracle Coherence.

  • JVM (JRE or JDK) 1.8 or later. 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.

    Note:

    Customers that want to integrate with applications that are running older JVM versions can use older Coherence clients; however, the client is constrained to the platform and client features that are supported for that Coherence version.

  • Windows or UNIX-based system that supports the required Java Version

  • Network adapter

Installation Requirements

The following are the minimum requirements for using the Coherence installer:

Note:

The requirements for running the installer are not the same as the requirements for running Coherence.

  • 300 MHz CPU

  • 512 MB swap space

  • 256 color monitor (required for GUI-based installation only)

  • Java Development Kit (JDK) 1.8.0_211 or later

Parent topic: Installing Oracle Coherence for Java

Performing a Coherence Installation

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.

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.

This section includes the following topics:

Parent topic: Installing Oracle Coherence for Java

Performing a Coherence Installation In Graphical Mode

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. For detailed help on the installer's options, use the -help argument when running the installer.

For information about the directories created by the installer, see Understanding the Oracle Coherence Directory Structure.

This section includes the following topics:

Parent topic: Performing a Coherence Installation

Starting the Installation Program

To perform a Coherence installation in graphical mode:

  1. Copy the fmw_version_coherence.jar file to the target computer.
  2. 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 installation program displays.

Navigating the Installation Screens

Table 2-1 lists the screens in the order that the installation program displays.

If you need additional help with any of the installation screens, click the screen name.

Table 2-1 Oracle Coherence Installation Screens

Screen Description

Inventory Setup

On UNIX operating systems, this screen will appear if this is the first time you are installing any Oracle product on this host. Specify the location where you want to create your central inventory. Make sure that the operating system group name selected on this screen has write permissions to the central inventory location.

For more information about the central inventory, see Understanding the Oracle Central Inventory in Installing Software with the Oracle Universal Installer.

This screen will not appear on Windows operating systems.

Welcome

This screen introduces you to the product installer.

Installation Location

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.

Installation Type

Select which Coherence options to install.

Prerequisite Checks

This screen displays a list of system checks that are performed to ensure that Coherence is certified on the system.

Installation Summary

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. See Performing a Coherence Installation In Silent Mode.

Installation Progress

This screen allows you to see the progress of the installation.

Installation Complete

This screen appears when the installation is complete. Review the information on this screen, then click Finish to dismiss the installer.

Performing a Coherence Installation In Silent Mode

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:

  1. Copy the fmw_version_coherence.jar file and a response file to the target computer.
  2. 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

Parent topic: Performing a Coherence Installation

Running the Coherence Quick Installer

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:

  1. Copy the fmw_version_coherence_quick.jar file to a directory on the target computer.
  2. 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

Parent topic: Performing a Coherence Installation

Running the Coherence Supplemental Installer

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.

  1. Copy the fmw_version_coherence_quick_supplemental.jar file to the ORACLE_HOME directory where Coherence is installed.
  2. 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.

Parent topic: Performing a Coherence Installation

Installing Coherence with WebLogic Server

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 Planning the Oracle WebLogic Server Installation in Installing and Configuring Oracle WebLogic Server and Coherence.

Parent topic: Performing a Coherence Installation

Setting Environment Variables

You can set the JAVA_HOME and COHERENCE_HOME environment variables. However, 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.

Parent topic: Installing Oracle Coherence for Java

Running Coherence for the First Time

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.

This section includes the following topics:

Parent topic: Installing Oracle Coherence for Java

Create a Basic 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 in Developing Applications with Oracle Coherence.

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 coherence.cluster system properties as follows:
    set java_opts="-Xms%memory% -Xmx%memory% -Dcoherence.cluster=cluster_name"

    Replace cluster_name with a value that is unique for this cluster. For example, use your name for the cluster name.

  3. Save and close the cache-server script.
  4. Repeat steps 1 to 3 for the COHERENCE_HOME/bin/coherence script and specify the same value for cluster_name.
  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.

Parent topic: Running Coherence for the First Time

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 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.

Parent topic: Running Coherence for the First Time

Integration with Maven

Software projects that use Maven can incorporate Coherence into their build process. 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. If you are new to Maven, see the Maven project page.

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. See Installing and Configuring Maven for Build Automation and Dependency Management in 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. See Building Oracle Coherence Projects with Maven in Developing Applications Using Continuous Integration.

Parent topic: Installing Oracle Coherence for Java

Installing a Coherence Patch

Coherence periodically releases patches to the Oracle Support Website. See My Oracle Support. Patches are installed using the standard Oracle patching mechanism. See Patching Your Environment Using OPatch in Patching with OPatch.

Parent topic: Installing Oracle Coherence for Java

Uninstalling Coherence

Coherence is uninstalled by using the Oracle Fusion Middleware deinstaller. The deinstaller allows you to select which components in a Coherence ORACLE_HOME directory to uninstall and can also be used to completely remove a Coherence ORACLE_HOME directory.

To uninstall Coherence using the Deinstallation wizard, start the deinstaller. Use either 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.

Note:

If Coherence is installed as part of a WebLogic Server installation, it is not possible to uninstall Coherence separately from WebLogic Server.

Table 2-2 lists the screens in the order that the Deinstallation program displays.

Table 2-2 Oracle Coherence Deinstallation Screens

Screen Description

Welcome

This screen introduces you to the product deinstaller.

Deinstallation Summary

This screen lists the features that will be deinstalled. Click Deinstall to proceed.

Deinstallation Progress

This screen displays and shows all tasks that have succeeded and failed.

Deinstallation Complete

This screen displays and shows a summary of the Deinstallation process. Click Finish to close the Deinstallation program.

Note:

Additional files in the ORACLE_HOME directory must be manually deleted. On Windows, you must also manually delete the Oracle program group on the Start menu.

Parent topic: Installing Oracle Coherence for Java