Deprecation

This document is DEPRECATED.

Please consider any information here as out of date. DO NOT use this document.

Instead, refer to http://infinispan.org/documentation.

Please update your bookmarks accordingly.

Skip to end of metadata
Go to start of metadata

Documentation for ispncon version 0.8.1

What is ispncon ?

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:

Furthermore it creates an abstraction above the specifics of the client/server protocol you use to access the cache. The basic commands look the same whether you use Hot Rod, memcached or REST. The client/protocol specifics are handled via protocol-specific configuration options or command arguments.

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 https://github.com/infinispan/python-client
Memcached python-memcached https://launchpad.net/python-memcached
REST httplib (standard module for python) http://docs.python.org/library/httplib.html

The source code and issue reporting for ispncon can be found here: https://github.com/infinispan/ispncon

Installation

Ispncon requires

  • python 2.6
  • python modules: python-devel, setuptools, infinispan, python-memcached

Installation steps:

Make this part of your .bashrc or whatever so you have ispncon command on path

Basic usage

Format

Options

Option Meaning
-c --client Client to use, possible values: memcached, rest, hotrod (default)
Configuration key: ispncon.client_type
-h --host <host> Host/ip address to connect to. Default: localhost.
Configuration key: ispncon.host
-p --port <port> Port to connect to. Default: 11222 (hotrod default port)
Configuration key: ispncon.port
-C --cache-name <name> Named cache to use. Default: use default cache (no value)
Configuration key: ispncon.cache
-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 .

Configuration

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:

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
see section Interoperability with java clients for further info
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.
see section Interoperability with java clients for further info

Cache operations

put

Put data under a specified key.

Format

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:
HotRod: 64-bit integer version number
Memcached: 64-bit integer unique version id
REST: ETag string
Not yet implemented for REST client in infinispan, watch ISPN-1084 for more info.
-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

Get the data stored under the specified key.

Format

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:
HotRod: 64-bit integer version number
Memcached: 64-bit integer unique version id
REST: ETag string
-d --decode <codec>
Decode the value using the specified codec.

Return values

Exit code Output Result description
0 In case no filename was specified:
<data, possibly multi-line>
(NOTE: the data might contain binary content, that is not suitable for reading in terminal)
In case a filename was specified, nothing is printed on standard output.
In case -v was specified, the output is prepended with one line:
VERSION <version>
Entry was found and is returned.
1
ERROR <msg> General error occurred
2
NOT_FOUND Requested entry wasn't found in the cache

delete

Delete the entry with the specified key.

Format

Options

Option Meaning
-v --version <version> Deletes only if the specified version matches the version in the cache
NOTE: versioned delete is not supported with memcached client. attempt to delete with -v flag will end in ERROR message.
with REST client the situation is different, the protocol allows this, but it's not yet implemented in infinispan, watch ISPN-1084 for more info

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

Clear the cache

Format

Return values

Exit code Output Result description
0
DELETED Cache was sucessfully cleared
1
ERROR <msg> General error occurred

exists

Verify if the entry exists in the cache

Format

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.

version

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

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

Other commands

help

Print help about an operation

Format

NOTE: if no operation is supplied, prints list of supported operations

config

Change internal state/config of the client. This opeartion has only client-side effect.

Format

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

If no section is given, "ispncon" is implied.

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

include

Process cache commands from the specified batch file. The commands will be processed line by line.

Format

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.

Interoperability with java clients

HTTP clients

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.

Hot Rod Java Client

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.

SpyMemcached Java Client

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

Labels:
server server Delete
client client Delete
command-line command-line Delete
shell shell Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.