This chapter describes how to install and set up your environment for running Oracle Coherence 12c (12.1.3) (Coherence).
Note:
This tutorial uses the Eclipse Kepler 4.3.1 release with Oracle Enterprise Pack for Eclipse (OEPE) 12.1.3.0.0. For information about configuring Eclipse and OEPE for Coherence-based projects, see Chapter 2, "Installing and Configuring Eclipse and OEPE with Coherence".
This chapter contains the following sections:
You must have the privileges to install software and set system environment variables as the oracle user, an understanding of how to use a terminal window, including setting environment variables, and creating and moving between directories.
You must have a working installation of the Oracle JDK or JRE (version 7 or higher). This tutorial uses the Oracle JDK 1.7.0_25.
You must also be running one of the following Microsoft Windows operating systems: XP, Vista, 2000, 2003, 2008 or Windows 7.
For information on installing Oracle Coherence, see "Installing Oracle Coherence for Java" in Oracle Fusion Middleware Developing Applications with Oracle Coherence. This chapter provides instructions for installing Oracle Coherence by using the Oracle Universal Installer. The installer supports both a graphical mode and a silent mode. You can also choose to use the Coherence Quick Installer to perform a silent installation with no options.
Note:
This tutorial assumes that you have used the Oracle Universal Installer graphical interface to install Oracle Coherence at C:\Oracle\Middleware\Oracle_Home.
The coherence folder which appears under Oracle_Home contains these subfolders:
bin, which contains command scripts
doc, which contains the product documentation
examples, which contains code examples for the Java, .NET, and C++ platforms
lib, which contains the required library files
plugins, which contains Maven plugins that are used to integrate Coherence as part of a Maven build process
In this exercise, you test whether your Coherence installation can cluster Java processes. This ensures that Coherence-based applications that ship with Coherence will run as expected. If Coherence is not capable of clustering on a single machine, then you must reconfigure your network and firewall settings.
To complete this exercise, you must have Coherence (Java Edition) 12c (12.1.3) installed. See "Installing Coherence" for more information.
Coherence uses a variety of network addresses and ports to enable communication between clustered processes. If these addresses and ports are unavailable due to other applications using them, or because of a firewall, then Coherence may be unreliable, may fail to cluster, or may not work at all. By default, Coherence assumes that the network addresses and ports listed in Table 1-1 are available:
Table 1-1 Network Addresses and Ports Used by Coherence
| Address / Port / Type | Purpose |
|---|---|
|
|
Cluster member discovery and broadcast. The variable version represents the release version of Coherence. For example, the multicast address for the 12.1.3 release is |
|
|
Interprocess communication between cluster members. ( |
|
|
An additional port that is used for unicast communication. By default, the port is assigned as the next available port after the first unicast port. |
|
|
The default port of the IpMonitor component that is used for detecting hardware failure of cluster members is "7". |
Coherence ships with two simple command-line (shell-based) applications that can be used to determine whether Coherence operates correctly.
The cache server is a simple application that hosts and manages data on behalf of other applications in a cluster.
The cache client is a simple application that enables a developer to access, process, and update cached data within a cluster. It also provides information about the cluster. By executing these applications either on a single host or on several hosts, you can determine whether Coherence is operating correctly locally or across a network.
When an application uses Coherence as shipped, objects placed into Coherence caches are typically stored and managed in-process within the application. However, to increase object availability, Coherence can manage objects in memory but out of the application process. This enables objects to survive possible application outages (either deliberate or accidental). To manage objects in this way, Coherence uses cache servers. The purpose of a Coherence cache server is to manage the application state in a cluster outside the application process. It is similar to a database server, but without the requirement for storage.
Follow these steps to test a Coherence Installation. The steps are described in detail in the following sections.
To set up and run the sample cache server application:
Open a terminal window and verify that the PATH environment variable is set to include the Java JDK or JRE (for example, C:\Oracle\Middleware\Oracle_Home\jdk1.7.0_25\bin). If the PATH environment variable does not include the JDK or JRE \bin folder, then set it as follows:
Set the JAVA_HOME environment variable to the base of the JDK or JRE installation.
set JAVA_HOME=\Oracle\Middleware\Oracle_Home\jdk1.7.0_25
Include JAVA_HOME\bin in the PATH environment variable.
set PATH=%JAVA_HOME%\bin;%PATH%
Navigate to the folder where Coherence is installed.
cd C:\oracle\Middleware\Oracle_Home\coherence\bin
Edit the cache-server.cmd file to set the COHERENCE_HOME environment variable to point to the Coherence installation folder:
coherence_home=C:\oracle\Middleware\Oracle_Home\coherence
Example 1-1 illustrates the cache-server.cmd file with the edited value of the COHERENCE_HOME environment variable.
Example 1-1 cache-server.cmd File with an Edited COHERENCE_HOME
@echo off
@
@rem This will start a cache server
@
setlocal
:config
@rem specify the Coherence installation directory
set coherence_home=c:\oracle\product\coherence
@rem specify the JVM heap size
set memory=512m
:start
if not exist "%coherence_home%\lib\coherence.jar" goto instructions
if "%java_home%"=="" (set java_exec=java) else (set java_exec=%java_home%\bin\java)
:launch
if "%1"=="-jmx" (
set jmxproperties=-Dtangosol.coherence.management=all -Dtangosol.coherence.management.remote=true
shift
)
set java_opts=-Xms%memory% -Xmx%memory% %jmxproperties%
%java_exec% -server -showversion %java_opts% -cp "%coherence_home%\lib\coherence.jar" -Dtangosol.coherence.clusterport=3155 com.tangosol.net.DefaultCacheServer %1
goto exit
:instructions
echo Usage:
echo ^<coherence_home^>\bin\cache-server.cmd
goto exit
:exit
endlocal
@echo on
Execute the cache server application that is located in the coherence\bin folder.
C:\oracle\product\coherence\bin>cache-server.cmd
When you start the first cache server, there is a slight delay because the cache server looks for an existing cluster. When the cache server determines that there are no clusters to join, it starts one. On start-up, the cache server produces output similar to the text in Example 1-2.
Several important features are highlighted in the example:
The Java JDK version number.
Information about how configuration files are loaded. The default is to load from the coherence.jar file:
Loaded operational configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/tangosol-coherence.xml"
The Coherence release number: Oracle Coherence 12.1.3.0.0...
The Coherence edition: Grid Edition: Development mode
The multicast address. This address changes with each major Coherence version. Note the 12.1.0 in the address for Coherence 12c (12.1.3): Group{Address=224.12.1.0, Port=12100, TTL=4}
The Member ID indicates the number of members in your cluster. For the purpose of this exercise, the value should be 1. ThisMember=Member(Id=1...
Example 1-2 Output from Starting a Coherence Cache Server
C:\Oracle\Middleware\Oracle_Home\coherence\bin>cache-server.cmd java version "1.7.0_25" Java(TM) SE Runtime Environment (build 1.7.0_25-b17) Java HotSpot(TM) 64-Bit Server VM (build 23.25-b01, mixed mode) 2013-11-13 13:34:39.298/1.062 Oracle Coherence 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded operational configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/tangosol-coherence.xml" 2013-11-13 13:34:39.398/1.162 Oracle Coherence 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded operational overrides from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/tangosol-coherence-override-dev.xml" 2013-11-13 13:34:39.398/1.162 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "/tangosol-coherence-override.xml" is not specified 2013-11-13 13:34:39.408/1.172 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "cache-factory-config.xml" is not specified 2013-11-13 13:34:39.408/1.172 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "cache-factory-builder-config.xml" is not specified 2013-11-13 13:34:39.408/1.172 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "/custom-mbeans.xml" is not specified Oracle Coherence Version 12.1.3.0.0 Build 48392 Grid Edition: Development mode Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 2013-11-13 13:34:39.738/1.502 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded cache configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/coherence-cache-config.xml" 2013-11-13 13:34:40.155/1.919 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded cache configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/internal-txn-cache-config.xml" 2013-11-13 13:34:40.900/2.664 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Created cache factory com.tangosol.net.ExtensibleConfigurableCacheFactory 2013-11-13 13:34:42.310/4.074 Oracle Coherence GE 12.1.3.0.0 <D4> (thread=main, member=n/a): TCMP bound to /130.35.99.13:8088 using SystemDatagramSocketProvider 2013-11-13 13:34:46.310/8.074 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=Cluster, member=n/a): Created a new cluster"cluster:0x47DB" with Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer, Edition=Grid Edition, Mode=Development, CpuCount=4, SocketCount=4) 2013-11-13 13:34:46.310/8.074 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Started cluster Name=cluster:0x47DB Group{Address=224.12.1.0, Port=12100, TTL=4} MasterMemberSet( ThisMember=Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer) OldestMember=Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer) ActualMemberSet=MemberSet(Size=1 Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer) ) MemberId|ServiceVersion|ServiceJoined|MemberState 1|12.1.3|2013-11-13 13:34:42.73|JOINED RecycleMillis=1200000 RecycleSet=MemberSet(Size=0 ) ) TcpRing{Connections=[]} IpMonitor{Addresses=0} 2013-11-13 13:34:46.420/8.184 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Invocation:Management, member=1): Service Management joined the cluster with senior service member 1 2013-11-13 13:34:46.520/8.284 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=1): Loaded Reporter configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/reports/report-group.xml" 2013-11-13 13:34:47.052/8.816 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=NameService:TcpAcceptor, member=1): TcpAcceptor now listening for connections on 130.35.99.13:8088.3 2013-11-13 13:34:47.572/9.336 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=DistributedCache, member=1): Service DistributedCache joined the cluster with senior service member 1 2013-11-13 13:34:47.612/9.376 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=DistributedCache, member=1): This member has become the distribution coordinator for MemberSet(Size=1 Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer) ) 2013-11-13 13:34:47.652/9.416 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=ReplicatedCache, member=1): Service ReplicatedCache joined the cluster with senior service member 1 2013-11-13 13:34:47.662/9.426 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=OptimisticCache, member=1): Service OptimisticCache joined the cluster with senior service member 1 2013-11-13 13:34:47.672/9.436 Oracle Coherence GE 12.1.3.0.0 <D5>(thread=Invocation:InvocationService, member=1): Service InvocationService joined the cluster with senior service member 1 2013-11-13 13:34:47.672/9.436 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=1): Services ( ClusterService{Name=Cluster, State=(SERVICE_STARTED, STATE_JOINED), Id=0, Version=12.1.3, OldestMemberId=1} InvocationService{Name=Management, State=(SERVICE_STARTED), Id=2, Version=12.1.3, OldestMemberId=1} PartitionedCache{Name=DistributedCache, State=(SERVICE_STARTED), LocalStorage=enabled, PartitionCount=257, BackupCount=1, AssignedPartitions=257, BackupPartitions=0} ReplicatedCache{Name=ReplicatedCache, State=(SERVICE_STARTED), Id=4, Version=12.1.3, OldestMemberId=1} Optimistic{Name=OptimisticCache, State=(SERVICE_STARTED), Id=5, Version=12.1.3, OldestMemberId=1} InvocationService{Name=InvocationService, State=(SERVICE_STARTED), Id=6, Version=12.1.3, OldestMemberId=1} ) Started DefaultCacheServer...
Note:
By default, Coherence is configured to use multicast to join a cluster and to distribute cluster events. Multicast can also be used to distribute a message efficiently to multiple nodes in the cluster. You can configure Coherence to disable multicast.
The output of the cache-server.cmd file indicates whether you have one or more members in your cluster. The value of Member Id should be equal to 1:
...
In MasterMemberSet
ThisMember=Member(Id should be equal to 1)
...
If ThisMember has an Id greater than one, it means that your cache server has joined a pre-existing cluster in your network. For the purposes of these exercises, the cluster should contain only one member. Follow the steps in "Restricting Coherence to Your Own Host" to restrict Coherence to your own host.
To set up and run the sample cache client application:
Open another terminal window to start the cache client.
Verify that the PATH environment variable is set to include the %JAVA_HOME%\bin folder. If the PATH environment variable does not include the %JAVA_HOME%\bin folder, then set the variable as described in "Configure and Run the Sample Cache Server Application".
Navigate to the \Oracle\Middleware\Oracle_Home\coherence\bin folder. Edit the query.cmd file to set the COHERENCE_HOME variable to point to the Coherence installation folder.
The query.cmd file includes a reference to the JLine JAR file (jline.jar). JLine is a Java library that simplifies working with console commands. The jline.jar file is included in the coherence\lib folder.
Example 1-3 illustrates the query.cmd file, with COHERENCE_HOME=\oracle\product\coherence. JLINE_HOME is set to %jline_home%\lib.
Example 1-3 query.cmd File with an Edited COHERENCE_HOME
@echo off @ @rem This will start a console application @rem demonstrating the functionality of the Coherence(tm) API @ setlocal :config @rem specify the Coherence installation directory set coherence_home=C:\oracle\Middleware\Oracle_Home\coherence @rem specify the jline installation directory set jline_home=%coherence_home%\lib @rem specify if the console will also act as a server set storage_enabled=false @rem specify the JVM heap size set memory=64m :start if not exist "%coherence_home%\lib\coherence.jar" goto instructions if "%java_home%"=="" (set java_exec=java) else (set java_exec=%java_home%\bin\java) :launch if "%storage_enabled%"=="true" (echo ** Starting storage enabled console **) else (echo ** Starting storage disabled console **) set java_opts="-Xms%memory% -Xmx%memory% -Dtangosol.coherence.distributed.localstorage=%storage_enabled%" "%java_exec%" -server -showversion "%java_opts%" -cp "%coherence_home%\lib\coherence.jar;%jline_home%\jline.jar" com.tangosol.coherence.dslquery.QueryPlus %* goto exit :instructions echo Usage: echo ^<coherence_home^>\bin\query.cmd goto exit :exit endlocal @echo on
Execute the query.cmd file to start the cache client.
query.cmd
The output of starting the cache client, illustrated in Example 1-4, displays the basic distributed cache functionality that is built into Coherence. At the end of the output, the CohQL> prompt is displayed.
Example 1-4 Output from Starting the Coherence Cache Client
C:\Oracle\Middleware\Oracle_Home\coherence\bin>query.cmd
** Starting storage disabled console **
java version "1.7.0_25"
Java(TM) SE Runtime Environment (build 1.7.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 23.25-b01, mixed mode)
Coherence Command Line Tool
CohQL>
Exercise the cache client application by entering various commands and examining the output.
Execute the following Coherence commands in the cache client:
Enter help to see the list of commands that are available.
Enter create cache "products" to create a cache named products.
The cache products implements the com.tangosol.net.NamedCache interface. A cluster can have many named caches.
Example 1-5 illustrates that by using the default configuration file (coherence-cache-config.xml) within the supplied coherence.jar file, a NamedCache called products is created using the distributed scheme.
Example 1-5 Output from Starting a Coherence Cache Client
CohQL> create cache "products"
2013-11-13 14:00:40.286/219.229 Oracle Coherence 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded operational configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/tangosol-coherence.xml"
2013-11-13 14:00:40.348/219.291 Oracle Coherence 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded operational overrides from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/tangosol-coherence-override-dev.xml"
2013-11-13 14:00:40.348/219.291 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "/tangosol-coherence-override.xml" is not specified
2013-11-13 14:00:40.364/219.307 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "cache-factory-config.xml" is not specified
2013-11-13 14:00:40.364/219.307 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "cache-factory-builder-config.xml" is not specified
2013-11-13 14:00:40.364/219.307 Oracle Coherence 12.1.3.0.0 <D5> (thread=main, member=n/a): Optional configuration override "/custom-mbeans.xml" is not specified
Oracle Coherence Version 12.1.3.0.0 Build 48392
Grid Edition: Development mode
Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
2013-11-13 14:00:40.723/219.666 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded cache configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/coherence-cache-config.xml"
2013-11-13 14:00:41.050/219.993 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Loaded cache configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/internal-txn-cache-config.xml"
2013-11-13 14:00:41.768/220.711 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Created cache factory com.tangosol.net.ExtensibleConfigurableCacheFactory
2013-11-13 14:00:43.063/222.006 Oracle Coherence GE 12.1.3.0.0 <D4> (thread=main, member=n/a): TCMP bound to /130.35.99.13:8090 using SystemDatagramSocketProvider
2013-11-13 14:00:43.671/222.614 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=Cluster, member=n/a): Failed to satisfy the variance: allowed=16, actual=31
2013-11-13 14:00:43.671/222.614 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=Cluster, member=n/a): Increasing allowable variance to 17
2013-11-13 14:00:44.014/222.957 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Cluster, member=n/a): Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer) joined Cluster with senior member 1
2013-11-13 14:00:44.030/222.989 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=Cluster, member=n/a): This Member(Id=2, Timestamp=2013-11-13 14:00:43.812, Address=130.35.99.13:8090, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3896, Role=TangosolCoherenceQueryPlus, Edition=Grid Edition, Mode=Development, CpuCount=4, SocketCount=4) joined cluster "cluster:0x47DB" with senior Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer, Edition=Grid Edition, Mode=Development, CpuCount=4, SocketCount=4)
2013-11-13 14:00:44.186/223.129 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=n/a): Started cluster Name=cluster:0x47DB
Group{Address=224.12.1.0, Port=3155, TTL=4}
MasterMemberSet(
ThisMember=Member(Id=2, Timestamp=2013-11-13 14:00:43.812, Address=130.35.99.13:8090, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3896, Role=TangosolCoherenceQueryPlus)
OldestMember=Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer)
ActualMemberSet=MemberSet(Size=2
Member(Id=1, Timestamp=2013-11-13 13:34:42.73, Address=130.35.99.13:8088, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3224, Role=CoherenceServer)
Member(Id=2, Timestamp=2013-11-13 14:00:43.812, Address=130.35.99.13:8090, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3896, Role=TangosolCoherenceQueryPlus)
)
MemberId|ServiceVersion|ServiceJoined|MemberState
1|12.1.3|2013-11-13 13:34:42.73|JOINED,
2|12.1.3|2013-11-13 14:00:43.812|JOINED
RecycleMillis=1200000
RecycleSet=MemberSet(Size=0
)
)
TcpRing{Connections=[1]}
IpMonitor{Addresses=0}
2013-11-13 14:00:44.248/223.191 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Invocation:Management, member=2): Service Management joined the cluster with senior service member 12013-11-13 14:00:44.264/223.207 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=2): Loaded Reporter configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/reports/report-group.xml"2013-11-13 14:00:44.685/223.628 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=NameService:TcpAcceptor, member=2): TcpAcceptor now listening for connections on 130.35.99.13:8090.32013-11-13 14:00:45.138/224.081 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=DistributedCache, member=2): Service DistributedCache joined the cluster with senior service member 1CohQL>
Execute the following commands at the CohQL> prompt in the cache client. For definitions of these commands, see "Using Coherence Query Language" in Oracle Fusion Middleware Developing Applications with Oracle Coherence.
Insert an entry (key-value pair) into the products cache:
insert into "products" key "television" value "ID-5070"
Change the value of the key:
update "products" set value() = "ID-5080" where key() like "television"
Retrieve the values in the cache:
select * from "products"
Retrieve the value of a key that does not exist. An empty result set will be returned:
select key(), value() from "products" where key() is "radio"
Delete an existing key in the cache. An empty result set will be returned:
delete from "products" where key() = "television"
Delete the contents of the products cache. An empty result set will be returned:
delete from "products"
Destroy the products cache:
drop cache "products"
Re-create the products cache:
create cache "products"
Insert more entries into the cache:
insert into "products" key "television" value "ID-5080" insert into "products" key "radio" value "ID-5090" insert into "products" key "MP3 Player" value "ID-5100" insert into "products" key "laptop" value "ID-5110"
Retrieve the keys and values in the products cache:
select key(), value() from "products"
Save a serialized representation of the cache in a file:
backup cache "products" to "products.bkup"
Delete a key from the cache:
delete from "products" where key() = "television"
Retrieve the cache contents again, notice that the deleted key and value will not be present:
select key(), value() from "products"
Delete the contents of the cache:
delete from "products"
Retrieve the contents of the cache. An empty result set will be returned:
select * from "products"
Restore the cache contents from the backup file:
restore cache "products" from file "products.bkup"
Retrieve the cache contents. Note that all of the entries will be restored and returned:
select key(), value() from "products"
Destroy the products cache:
drop cache "products"
Exit the command-line tool:
bye
Example 1-6 illustrates the output of each of these commands.
Example 1-6 Exercising Coherence Commands
CohQL> create cache "products" CohQL> insert into "products" key "television" value "ID-5070" CohQL> update "products" set value() = "ID-5080" where key() like "television Results television: true CohQL> select * from "products" Results ID-5080 CohQL> select key(), value() from "products" where key() is "radio" Results CohQL> delete from "products" where key() = "television" Results CohQL> delete from "products" Results CohQL> drop cache "products" CohQL> create cache "products" CohQL> insert into "products" key "television" value "ID-5080" CohQL> insert into "products" key "radio" value "ID-5090" CohQL> insert into "products" key "MP3 Player" value "ID-5100" CohQL> insert into "products" key "laptop" value "ID-5110" CohQL> select key(), value() from "products" Results "television", "ID-5080" "radio", "ID-5090" "MP3 Player", "ID-5100" "laptop", "ID-5110" CohQL> backup cache "products" to "products.bkup" WARNING: The backup command should not be used on active data set, as it makes no provisions that ensure data consistency during the backup. Please see the documentation for more detailed information. CohQL> delete from "products" where key() = "television" Results CohQL> select key(), value() from "products" Results "radio", "ID-5090" "MP3 Player", "ID-5100" "laptop", "ID-5110" CohQL> delete from "products" Results CohQL> select * from "products" Results CohQL> restore cache "products" from file "products.bkup" CohQL> select key(), value() from "products" Results "television", "ID-5080" "radio", "ID-5090" "MP3 Player", "ID-5100" "laptop", "ID-5110" CohQL> drop cache "products" CohQL> bye
In the cache server window, you should see a response similar to the following, indicating that the client (Member 2) has left the cluster:
... 2013-11-13 14:08:50.545/2052.309 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Cluster, member=1): TcpRing disconnected from Member(Id=2, Timestamp=2013-11-13 14:00:43.812, Address=130.35.99.13:8090, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3896, Role=TangosolCoherenceQueryPlus) due to a peer departure; removing the member. 2013-11-13 14:08:50.545/2052.309 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Cluster, member=1): Member(Id=2, Timestamp=2013-11-13 14:08:50.545, Address=130.35.99.13:8090, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:3896, Role=TangosolCoherenceQueryPlus) left Cluster with senior member 1 2013-11-13 14:08:50.545/2052.309 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Invocation:Management, member=1): Member 2 left service Management with senior member 1 2013-11-13 14:08:50.545/2052.309 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=DistributedCache, member=1): Member 2 left service DistributedCache with senior member 1
Open another terminal window and set the PATH environment variable to include %JAVA_HOME% and %JAVA_HOME%\bin. Enter the query.cmd command in the new terminal window to start an instance of the cache client.
Restart the first client with the query.cmd command. Enter the create cache "products" command. The cache server terminal window displays a message similar to the following that describes where the first client is running. member 1 is the cache server and member 3 is the restarted first client.
2013-11-13 14:15:24.217/27.307 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Invocation:Management, member=3): Service Management joined the cluster with senior service member 1 2013-11-13 14:15:24.248/27.338 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=main, member=3): Loaded Reporter configuration from "jar:file:/C:/Oracle/Middleware/Oracle_Home/coherence/lib/coherence.jar!/reports/report-group.xml" 2013-11-13 14:15:24.654/27.744 Oracle Coherence GE 12.1.3.0.0 <Info> (thread=NameService:TcpAcceptor, member=3): TcpAcceptor now listening for connections on 130.35.99.13:8090.3 2013-11-13 14:15:25.106/28.196 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=DistributedCache, member=3): Service DistributedCache joined the cluster with senior service member 1 CohQL>
Enter the create cache "products" command in the new terminal window to connect to the products cache. It enters the cluster as Member 4. Try to get and put values in different sessions. Notice that each client can observe changes made by the other client.
Terminate one of the query.cmd client shells (bye). Note that the other shell displays a message indicating that the member has left the cluster, for example:
2013-11-13 14:23:54.085/537.175 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Cluster, member=3): TcpRing disconnected from Member(Id=4, Timestamp=2013-11-13 14:22:39.583, Address=130.35.99.13:8092, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:5540, Role=TangosolCoherenceQueryPlus) due to a peer departure; removing the member. 2013-11-13 14:23:54.085/537.175 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Cluster, member=3): Member(Id=4, Timestamp=2013-11-13 14:23:54.085, Address=130.35.99.13:8092, MachineId=47251, Location=site:,machine:TPFAEFFL-LAP,process:5540, Role=TangosolCoherenceQueryPlus) left Cluster with senior member 1 2013-11-13 14:23:54.085/537.175 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=Invocation:Management, member=3): Member 4 left service Management with senior member 1 2013-11-13 14:23:54.085/537.175 Oracle Coherence GE 12.1.3.0.0 <D5> (thread=DistributedCache, member=3): Member 4 left service DistributedCache with senior member 1
If you terminate each of the cache clients (bye), and then restart them, note that data from the previous session is still available. This is because the data is held in the cache server.
If you start another Coherence cache server, and then terminate the initial one that was started (using Ctrl+C or by closing the command window), note that the data is still available.
Terminate both the query.cmd shells and cache-server.cmd shell. Restart query.cmd. Create a cache called test using the command create cache "test". Try to put a value into the cache, as before. Because the cache client is configured to start in storage-disabled mode, you will receive a response similar to the following:
com.tangosol.net.RequestPolicyException: No storage-enabled nodes exist for service DistributedCache
Start a cache server by running the cache-server.cmd file. Try to insert a value again. This time, the value will be accepted.
Terminate all cache servers.
If the value of Member ID in the cache-server.cmd output is anything other than 1, then this indicates that the cache server has clustered with one or more other cache servers or processes running Coherence. These servers or processes can be running on the network or running locally on your host. Though this is the default behavior for Coherence—to cluster with other processes running Coherence locally or on a network—it is strongly advised that while you perform this tutorial, you restrict Coherence to your own host.
Note:
To restrict Coherence to a single host, the cache server and cache client executable files used in this tutorial use the tangosol.coherence.clusterport command line property set to 3155.
The value of the Member ID in the output of the cache-server.cmd cache server command indicates whether you have one or more members in your cluster. For the purpose of this tutorial, the value of Member ID must be equal to 1:
...
In MasterMemberSet
ThisMember=Member(Id should be equal to 1)
...
If the value of Member ID is greater than 1, it means that multiple clusters are being formed in your subnet.
There are several ways to restrict Coherence to your own host. The easiest way is to use the tangosol.coherence.clusterport system property to declare a unique cluster port value in your cache server startup file. For example, add the following Java option to your cache-server.cmd file. The value assigned to the system property can be any unique value, such as the last four digits of your telephone number.
-Dtangosol.coherence.clusterport=3155
If you follow the steps in "Restricting Coherence to Your Own Host" and the cache-server.cmd command still fails to return a Member Id value of 1, then there might be additional problems to resolve.
Disconnect from the network or disable networking on your host. If errors or exceptions occur when starting the cache server, your network settings might need to be modified. Try each of the following one at a time, restarting the cache server after each attempt:
If connected to a Virtual Private Network (VPN), then disconnect from it. By default, most VPN are not configured to permit multicast and some unicast traffic. In this environment, Coherence might not work, if left in the configuration in which it was shipped. Coherence can be configured to run across a VPN, but this requires some advanced settings.
If you run a firewall, configure it to enable the specified addresses and ports.
If you still experience problems, disconnect from all networks. This includes wireless and wired networks.
If all the preceding options fail, set up Coherence to run on a single host.
The Coherence distribution provides an examples.zip file that contains many of the examples found in this tutorial. They demonstrate many of the cache access, processing, and security features in Coherence. The examples are designed to be built and run from the command line. The output of the examples is directed to standard output (stdout).
Appendix A, "Coherence Examples in the examples.zip File" provides information on building and running the examples. It also provides minimal documentation on the code in the examples.zip file. More detailed information about the code is embedded as comments in the individual code files.
There are a number of differences between the examples in the examples.zip file and the examples in this tutorial:
The examples in the examples.zip must be built and run from the command line. This tutorial uses an IDE to compile and run the code.
The examples in the examples.zip file demonstrate how to use basic Coherence functionality and security features in all supported languages (Java, .NET, and C++). The tutorial covers only Java implementations.
The Java examples in the examples.zip file are only a subset of the Java examples presented in the tutorial.
The Java files in the examples.zip file are similar to the files used in this tutorial. In many instances, the code in the tutorial has been simplified for demonstration purposes.
You can obtain the examples.zip file by performing a full Coherence installation with the coherence_version.jar or wls_version.jar file.
If you have already installed Coherence but without the examples, you can obtain the examples.zip file by running the coherence_quick_supp_version.jar supplemental installer file. The supplemental installer contains only API documentation and examples.
Note that the coherence_quick_version.jar quick installer does not install the examples.