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 batch

You can script Coherence from the command line by creating a separate file with command-line commands. For example, you can create a file called batchfile.txt which contains commands to change the current cache to testcache, clear it, and then exit:

cache testcache

You can invoke this script on the UNIX platform by running the Coherence command line application:

bin/coherence.sh "@batch batchfile.txt"

On the Windows platform, substitute bin/coherence.sh with bin/coherence.cmd.

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

Clears the current NamedCache by calling clear.

A.5 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.6 get <key>

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

A.7 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.8 help

Prints the list of commands available to you.

A.9 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.10 kill

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

A.11 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.12 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 partitioned caches, the local listener can only be used on storage-enabled nodes. For example, with the partitioned 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.13 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. The value is the number of milliseconds, expressed as a long integer (that is, the value should be suffixed with an “l”). For example, this command attempts to lock the counter key for up to 10 seconds:

lock counter 10000l

A.14 maps

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

A.15 memory

Lists the "total" used, total "free", and maximum memory values for this JVM. For example:

Map (testcache): memory
total=64356K (64356352)
free =55658K (55658976)
max =64356K (64356352)

A.16 put <key> <value>

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

A.17 release

Releases the reference to the current NamedCache on this cluster member by calling the release method. This does not affect other cluster nodes. After calling release, the name of the inactive cache is still shown, because the command line tool still holds the reference to the cache. This is expected behavior. If subsequent commands are issued on this cluster node against the current NamedCache, an IllegalStateException will occur.

Map (testcache): release
Map (testcache): 

A.18 remove <key>

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

A.19 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.20 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.21 size

Shows the count of objects in the current NamedCache.

A.22 unlock <key>

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

A.23 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.24 who | cluster

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

A.25 whoami | service

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

A.26 worker <command>

Performs the specified command on a new temporary thread.

A.27 #<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.28 @<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.29 &<functionName> [paramValue]*

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