$ ispncon put keyA "Sample value under keyA" $ ispncon get keyA $ ispncon delete keyA
Documentation for ispncon version 0.8.1
Ispncon (Infinispan Command-Line Console) is a simple command-line interface to infinispan cache written in python. It accesses the cache in client/server fashion, whereby infinispan server modules (Hot Rod, Memcached, REST) have to be properly configured. Once you have a running instance of infinispan with one of the server modules, you can issue simple cache requests via command line, like:
$ ispncon put keyA "Sample value under keyA" $ ispncon get keyA $ ispncon delete keyA
Your shell scripts should look basically the same for all the client modes, if you don't use any protocol specific features.
Behind the scenes the console tool uses existing python clients to handle the communication with particular server modules. The implementations are listed in the following table:
|
Client |
Client implementation |
Web |
|
Hot Rod |
python-client for hotrod |
|
|
Memcached |
python-memcached |
|
|
REST |
httplib (standard module for python) |
The source code and issue reporting for ispncon can be found here: https://github.com/infinispan/ispncon
Ispncon requires
python 2.6
python modules: python-devel, setuptools, infinispan, python-memcached
Installation steps:
$ git clone <a class="jive-link-external-small" href="https://github.com/infinispan/ispncon.git" target="_blank">https://github.com/infinispan/ispncon.git</a> $ cd ispncon/src $ sudo python setup.py install
export ISPNCON_HOME=/path/to/ispncon export PATH=$ISPNCON_HOME/bin:$PATH
Format
ispncon [options] <operation> [operation_options] <op_arguments>
Options
|
Option |
Meaning |
|
-c --client |
Client to use, possible values: memcached, rest, hotrod (default) |
|
-h --host <host> |
Host/ip address to connect to. Default: localhost. |
|
-p --port <port> |
Port to connect to. Default: 11222 (hotrod default port) |
|
-C --cache-name <name> |
Named cache to use. Default: use default cache (no value) |
|
-v --version |
Print ispncon version and exit |
|
-e --exit-on-error |
If true and operation fails, then fail with an exit code. If false just print ERROR message and continue. This mostly makes sense for batch files. |
|
-P --config "<key> <value>" |
override configuration option <key> with value <value>. NOTE: the quotes are necessary, because getopt parser needs to get these as one string. |
The possible Operations are put, get, delete, clear, exists, help, config, include and each one is described in the sections Cache operations and Other commands .
On start-up ispncon reads the file ~/.ispncon to configure some of the default values to use, so that the user doesn't have to enter the options like host, port, client type and cache name everytime he types a cache command.
The format of the config file is like this:
[ispncon] host = localhost port = 8080 client_type = rest cache = exit_on_error = False default_codec = None [rest] server_url = /infinispan-server-rest/rest content_type = text/plain [hotrod] use_river_string_keys = True
The config parameters in the section ispncon are described in the_Basic usage_ section. The rest is described here:
|
Config key |
Meaning |
|
rest.server_url |
location of the REST server service, in the above example the HTTP requests would be sent tohttp://localhost:8080/infinispan-server-rest/rest |
|
rest.content_type |
default MIME content type for entries stored via REST interface |
|
default_codec |
Default codec to use to encode/decode values. Possible values: None, RiverString, RiverByteArray |
|
hotrod.use_river_string_keys |
If set to True, hotrod client will encode keys with RiverString codec - this is necessary to be able to access the same data as via Java HotRod Client using the same string keys. |
Put data under a specified key.
Format
put [options] <key> <value>
Options
|
Option |
Meaning |
|
-i --input-filename <filename> |
Don't specify the value, instead put the contents of the specified file. |
|
-v --version <version> |
Put only if version equals version given. Version format differs between protocols: |
|
-l --lifespan <seconds> |
Specifies lifespan of the entry. Integer, number of seconds. |
|
-I --max-idle <seconds> |
Specifies max idle time for the entry. Integer, number of seconds. |
|
-a --put-if-absent |
Return CONFLICT if value already exists and don't put anything in that case |
|
-e --encode <codec> |
Encode value using the specified codec |
Return values
|
Exit code |
Output |
Result description |
|
0 |
STORED |
Entry was stored sucessfully |
|
1 |
ERROR <msg> |
General error occurred |
|
2 |
NOT_FOUND |
-v option was used and entry doesn't exist |
|
3 |
CONFLICT |
-a option was used and the entry already exists, or -v was used and versions don't match |
NOTE: memcached client won't distinguish between states NOT_FOUND, CONFLICT and ERROR and always will return ERROR if operation wasn't successfull. this is a limitation of python-memcached client.
see issues:
https://bugs.launchpad.net/python-memcached/+bug/684689
https://bugs.launchpad.net/python-memcached/+bug/684690
for discussion.
In later ispncon versions python-memcached client might get replaced by a customized version.
Get the data stored under the specified key.
Format
get [options] <key>
Options
|
Option |
Meaning |
|
-o --output-filename <filename> |
Stores the output of the get operation into the file specified. |
|
-v --version |
Get version along with the data. Version format differs between protocols: |
|
-d --decode <codec> |
Decode the value using the specified codec. |
Return values
|
Exit code |
Output |
Result description |
|
0 |
In case no filename was specified: |
Entry was found and is returned. |
|
1 |
ERROR <msg> |
General error occurred |
|
2 |
NOT_FOUND |
Requested entry wasn't found in the cache |
Delete the entry with the specified key.
Format
delete [options] <key>
Options
|
Option |
Meaning |
|
-v --version <version> |
Deletes only if the specified version matches the version in the cache |
Return values
|
Exit code |
Output |
Result description |
|
0 |
DELETED |
Entry was successfully deleted |
|
1 |
ERROR <msg> |
General error occurred |
|
2 |
NOT_FOUND |
Entry wasn't found in the cache. |
|
3 |
CONFLICT |
Option -v was used and versions don't match |
Clear the cache
Format
clear
Return values
|
Exit code |
Output |
Result description |
|
0 |
DELETED |
Cache was sucessfully cleared |
|
1 |
ERROR <msg> |
General error occurred |
Verify if the entry exists in the cache
Format
exists <key>
Return values
|
Exit code |
Output |
Result description |
|
0 |
EXISTS |
Entry with the given key exists |
|
1 |
ERROR <msg> |
General error occurred |
|
2 |
NOT_FOUND |
Entry with the given key wasn't found in the cache |
NOTE: memcached protocol doesn't support querying for existence of an entry in the cache so exists operation is implemented (inefficiently) by get opeartion, that gets the whole entry with all the data from the server.
Get version of the entry. Version format differs between protocols:
HotRod: 64-bit integer version number
Memcached: 64-bit integer unique version id
REST: ETag string
NOTE: The purpose of this command is to facilitate the parsing of the version string. HotRod and Memcached client don't support efficient implementation of this operation. They transfer the whole entry from the server to determine the version, so if applicable you are encouraged to use "get -v" command to obtain version together with the data.
REST client implements this operation efficiently by executing HEAD method.
Format
version <key>
Return values
|
Exit code |
Output |
Result description |
|
0 |
<version> |
If the entry exists. |
|
1 |
ERROR <msg> |
General error occurred |
|
2 |
NOT_FOUND |
Requested entry wasn't found in the cache |
Print help about an operation
Format
help <operation>
Change internal state/config of the client. This opeartion has only client-side effect.
Format
config - to print current config config save - to save config to ~/.ispncon config <key> <value> - to change config for currently running session
Configuration values
see section Configuration for the meaning of different configuration options. Currently supported keys are:
cache
host
port
client_type
exit_on_error
rest.server_url
rest.content_type
These values directly correspond to the keys in the ~/.ispncon config file. The format of the key is
<section>.<config_key>
Return values
|
Exit code |
Output |
Result description |
|
0 |
STORED |
If configuration/client state was updated successfully. |
|
0 |
multi-line output with config values |
If config command with no parameters was entered. |
|
1 |
ERROR <msg> |
General error occurred |
Process cache commands from the specified batch file. The commands will be processed line by line.
Format
include <filename>
Return values
|
Exit code |
Output |
Result description |
|
exit code of the last command in the file. |
The output depends on the commands present in the input file |
depends on the commands in the batch file |
NOTE: The name of this command and it's behaviour is going to change in the next version.
when exchanging data via REST interface, the values are interpreted by any client as sequence of bytes. The meaning is given to this byte-sequence by using MIME type specified via "Content-Type" HTTP header. No special interoperability measures are needed here.
If we want to read in ispncon the entries that were put with Hot Rod Java client, we need to use a special option hotrod.use_river_string_keys = True. This will cause the string keys to be encoded the same way the Java client does it.
Using hotrod.use_river_string_keys = True we're able to access the data that has been writen by the java client, but we still see the raw binary values. To be able to see a value that has been put by Hot Rod java client in a readable form and vice versa - to be able to see in Hot Rod Java client what we've put via ispncon we need to use a codec. Currently there are two types of codecs: RiverString and RiverByteArray
RiverString - will decode a value that has been put as java.lang.String and vice versa - a value encoded with this codec will be returned as java.lang.String on the java side
RiverByteArray - analogous to RiverString but works with byte[] (java byte array)
Codecs can be used either by specifying a default_codec option in the ~/.ispncon config file (in section ispncon) or by specifying a codec on each put resp get using -e (--encode) resp -d (--decode) options.
Tested with spymemcached 2.7.
Value that is put by ispncon is interpreted as an UTF-8 string. meaning if we supply some bytes, on the java side it will be recreated as new java.lang.String(bytes, "UTF-8")
This also works reversely: values put by java side as java.lang.String will be returned as UTF-8 bytes in ispncon