A Coherence Client Application Commands

This appendix describes the commands that can be issued to the Coherence command line application coherence.cmd (or coherence.sh on UNIX).

A.1 bye

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.

A.2 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 (10 MB 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.)

A.3 clear

Clears the current NamedCache by calling clear().

A.4 destroy

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.

A.5 get <key>

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

A.6 hash

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.

A.7 help

Prints the list of commands available to you.

A.8 inc <key> [<count>]

Increments the specified key the specified number of times, using locking to ensure that no "missing updates" occur. For example:

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 100,000 (assuming it started at 0 or did not exist previously).

A.9 kill

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

A.10 list [<map name>]

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


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

  • Java implements the toString method for byte[] values as [ (that is, array) + B (that is, byte) + hashcode. For example:


A.11 listen [('start' | 'stop') [('cluster' | '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, this command will show all cache changes that this member manages:

listen start local

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

listen start cluster

A.12 lock <key> [<timeout>l]

Locks the specified key. If the lock cannot be obtained immediately, it returns false, unless a time-out has been specified. For example, this command attempts to lock the counter key for up to 10 seconds:

lock counter 10000l

A.13 log (<size> | <message>) [<iterations> [<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.

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

Creates (if it does not already exist) the specified NamedCache and makes it the "current" cache. 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). For example, the following command creates a Replicated Cache of the name Test and makes it the current (that is, active) NamedCache for subsequent commands:

map Replicated:Test

A.15 maps

Lists all the NamedCache(s) for the current service, com.tangosol.net.CacheService, regardless of whether they were created by this member.

A.16 memory

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

A.17 put <key> <value>

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

A.18 release

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.

A.19 remove <key>

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

A.20 scan <start key> <stop key>

This method is used to check for missing keys in a sequence. For example, the following command 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:

scan 1 1000

A.21 services

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

A.22 size

Shows the count of objects in the current NamedCache.

A.23 unlock <key>

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

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

For example, if you run these commands on the first JVM:

waitkey 1 1000

Then run this command on the second JVM:

bulkput 1000 100 1

The first JVM will display the total replication time for 1000 entries with values of 100 bytes.

A.25 who

Lists information about each Member (com.tangosol.net.Member) in the cluster.

A.26 whoami

Lists the current Service (com.tangosol.net.Service) information.

A.27 worker <command>

Performs the specified command on a new temporary thread.

A.28 #<repeat count> <command>

Repeats the following <command> the specified number of times. Multiple commands can be delimited with a semicolon. For example, in a loop of ten iterations, this command increments the Counter key, then lists the current NamedCache values:

#10 inc Counter; list

A.29 @<command>

Silent mode. Suppresses output from the command. This can be used in conjunction with '#' (repeat mode). For example, in a loop of ten iterations, this command increments the Counter key, then lists the current NamedCache values. The output from the inc command is suppressed:

#10 @inc Counter; list

A.30 &<functionName> [paramValue]*

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