How do I use the command-line Coherence application?

When you start the application, your should see a license message, then there may be a pause while the cluster is joined (or started), then a command prompt:

** Starting storage disabled console **
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b02)
Java HotSpot(TM) Server VM (build 1.5.0_16-b02, mixed mode)

2008-09-15 16:41:36.771 Oracle Coherence 3.4/405  (thread=main, member=n/a): Loaded operational configuration from 
resource "jar:file:/D:/coherence/lib/coherence.jar!/tangosol-coherence.xml"
2008-09-15 16:41:36.781 Oracle Coherence 3.4/405  (thread=main, member=n/a): Loaded operational overrides from 
resource "jar:file:/D:/coherence/lib/coherence.jar!/tangosol-coherence-override-dev.xml"
2008-09-15 16:41:36.781 Oracle Coherence 3.4/405  (thread=main, member=n/a): Optional configuration override 
"/tangosol-coherence-override.xml" is not specified
2008-09-15 16:41:36.791 Oracle Coherence 3.4/405  (thread=main, member=n/a): Optional configuration override 
"/custom-mbeans.xml" is not specified

Oracle Coherence Version 3.4/405
 Grid Edition: Development mode
Copyright (c) 2000-2008 Oracle. All rights reserved.

2008-09-15 16:41:38.033 Oracle Coherence GE 3.4/405  (thread=Cluster, member=n/a): Service Cluster joined the
cluster with senior service member n/a
2008-09-15 16:41:41.237 Oracle Coherence GE 3.4/405  (thread=Cluster, member=n/a): Created a new cluster 
"cluster:0x19DB" with Member(Id=1, Timestamp=2008-09-15 16:41:37.682,, MachineId=27405,,machine:mycomputer,process:3864, Role=CoherenceConsole, Edition=Grid Edition, Mode=Development, 
CpuCount=1, SocketCount=1) UID=0x8D90760D0000011BE1D9E2926B0D1F98
SafeCluster: Name=cluster:0x19DB

Group{Address=, Port=34405, TTL=4}

  ThisMember=Member(Id=1, Timestamp=2008-09-15 16:41:37.682,, MachineId=27405,,machine:mycomputer,process:3864, Role=CoherenceConsole)
  OldestMember=Member(Id=1, Timestamp=2008-09-15 16:41:37.682,, MachineId=27405,,machine:mycomputer,process:3864, Role=CoherenceConsole)
  ActualMemberSet=MemberSet(Size=1, BitSetCount=2
    Member(Id=1, Timestamp=2008-09-15 16:41:37.682,, MachineId=27405,,machine:mycomputer,process:3864, Role=CoherenceConsole)
  RecycleSet=MemberSet(Size=0, BitSetCount=0

  TcpRing{TcpSocketAccepter{State=STATE_OPEN,}, Connections=[]}
  ClusterService{Name=Cluster, State=(SERVICE_STARTED, STATE_JOINED), Id=0, Version=3.4, OldestMemberId=1}

Map (?):

There is a concept of a "current" NamedCache object ( being active in the command-line application. Almost all of the following commands work against that current instance, the only exceptions being the lifecycle commands such as bye, kill and map. The name of the active NamedCache is shown in the prompt; for example 'Map (Default):' shows that the active NamedCache is named 'Default'.

Below are short descriptions of each of the available commands:


Gracefully shuts down the cluster member and closes the Coherence command-line application. To test "ungraceful" shutdown, use Ctrl-C (Windows or UNIX) or kill -9 <pid> on UNIX.

bulkput <# of iterations> <block size> <start key>

Populates the current NamedCache with the specified number of objects. This is best described with an example:

bulkput 1000 10000 1

This will put 1000 objects of size 10000 bytes (10MB total) starting with key 1 into the cache. The type of the key will be java.lang.Integer and the type of the value is byte[]. (The one exception is for the size zero, the value is of type Coherence$DebugCacheItem, which is used to test custom serialization and ClassLoader issues.)


Clears the current NamedCache by calling clear().


Calls destroy() on the current NamedCache. This will remove the NamedCache completely from the cluster, causing other cluster members to receive an IllegalStateException if they are holding on to a reference to the same cache and try to do any operation on that cache.

get <key>

Returns the value associated with this <key> from the cache by calling get(key).


Returns a hash value of the NamedCache . This is similar to a checksum and is mainly used for verifying the equivalency of the replicated caches.


Prints the list of commands available to you.

inc <key> [COH33UG:<count>]

Increments the specified key the specified number of times, using locking to ensure that no "missing updates" occur. (See the sequential key counter FAQ item.)

inc counter 10000

This will increment the 'counter' key 10000 times. If you run this command simultaneously on 10 machines, the value of the 'counter' key will be 100000 (assuming it started at 0 or did not exist previously).


Shuts down the current in an orderly(graceful) manner. This does not affect other service members.

list [COH33UG:<map name>]

Lists the contents of the specified NamedCache, or the current one if none is specified.

Note: If there are more than 50 items in the NamedCache only the first 50 items will be displayed through the list command.

Note: Java implements the ((toString}} method for byte[] values as '[' (i.e. array) + 'B' (i.e. byte) + hashcode; for example:


listen [('start' | 'stop') [('cluster' | COH33UG:'local')]]

Registers ('start') or unregisters ('stop') a debug implementation of com.tangosol.util.MapListener with the current NamedCache ('cluster') or with the "backing-store" com.tangosol.util.ObservableMap ('local'). (The backing store is the java.util.Map object obtained by the cache service from the LocalCacheFactory interface.)

For example, with the distributed cache service:
listen start local

This will show all cache changes that this member manages.

listen start cluster

This will show all cache changes, even if they are managed by a different member, and even if this member has local-storage-enabled set to false.

lock <key> [COH33UG:<timeout>L]

Locks the specified key. If the lock cannot be obtained immediately, it returns false, unless a time-out has been specified.

lock counter 10000L

Attempts to lock the counter key for up to 10 seconds.

log (<size> | <message> ) [<iterations> [COH33UG:<level>]]

Prints a message of specified <size> or specified <message> a specified number of times (<iterations>) at a given <level> where 'level=1' is ERROR, 'level=2' is WARNING and 'level=3' is INFO. This command is used mainly for batch testing, or to verify the format of messages when changes are made to the message format options in the tangosol-coherence.xml file.

map [[('Optimistic' | 'Replicated' | 'Distributed') ':'] <map name> [COH33UG:<limit>]]

Creates (if not already created) the specified NamedCache and makes it the "current" one. The <limit> parameter is only used in conjunction with the Optimistic Cache and specifies the maximum number of items in a Local Cache (size-limited com.tangosol.util.Cache).


map Replicated:Test

This will create a Replicated Cache of the name 'Test' and make it current" (active) NamedCache for subsequent commands.


Lists all the NamedCache(s) for the current service, whether or not they were created by this member.


Lists the "total" used and "free" memory values for this JVM.

put <key> <value>

Puts the specified key/value pair into the current NamedCache using the put(key, value) method.


Releases the reference to the current NamedCache on this cluster member by calling the release() method. This does not affect other cluster nodes. If subsequent commands are issued on this cluster node against the current NamedCache, an IllegalStateException will occur.

remove <key>

Removes the specified key from the current NamedCache using the remove(key) method.

scan <start key> <stop key>

This method is used to check for missing keys in a sequence.


scan 1 1000

Checks the java.lang.Integer keys from 1 to 1000 inclusive, and prints out any keys in that range that are not present in the current NamedCache .


Lists all the services ( known to this cluster. Some of these services may not be currently running on this cluster node.


Shows the count of objects in the current NamedCache .

unlock <key>

Unlocks the specified key in the current NamedCache using the unlock(key) method.

waitkey <start key> <stop key>

This method is used in conjunction with multiple Coherence command line processes and the bulkput command to time cache replication. Before one machine starts its bulkput command, a second machine is told to wait for the range of keys that will be placed into the cache.

Example (on the first JVM):

waitkey 1 1000

Example (on the second JVM):

bulkput 1000 100 1

On the first JVM, this will show the total replication time for 1000 entries with values of 100 bytes.


Lists information about each Member ( in the cluster.


Lists the current Service ( information.

worker <command>

Performs the specified command on a new temporary thread.

#<repeat count> <command>

Repeats the following <command> the specified number of times. Multiple commands can be delimited with a semicolon.


#10 inc Counter; list

In a loop of ten iterations, this increments the "Counter" key then lists the current NamedCache values.


Silent mode. Suppresses output from the command. This can be used in conjunction with '#' (repeat mode).


#10 @inc Counter; list

In a loop of ten iterations, this increments the "Counter" key then lists the current NamedCache values. The output from the inc command is suppressed.

&<functionName> [paramValue]*

Uses reflection to call the specified function on the current NamedCache instance. This is intended primarily for internal testing use.