Tools

Tools for TransiStore

Assuming you have Installed TransiStore code base (usually just git cloned this project; mvn clean installed -- but can also d/l from Maven, you should have client jar at location like:

ts-commands/target/transistore-commands-0.9.6-SNAPSHOT.jar

as well as tstore.sh wrapper script at project main directory (NOTE: for Windows you need to adapt this as appropriate; or simply invoke jar directly), and can invoke it simply with:

./tstore.sh

which should display something like:

usage: tstore [(-v | --verbose)]
  ...
The most commonly used tstore commands are:
  cat        GET file(s) from TStore into local file system
  delete     DELETE entries from TStore
  generate   Generate and upload test data in TStore
  get        GET entries from TStore into local file system
  help       Display help information
  list       Lists files stored in TStore, under specified partition
  put        PUT file(s) from local file system to TStore

which shows available commands. Let's start with simplest one.

Notes on configuration

The default wrapper tstore.sh refers to sample configuration file sample/single-node-9090.yml. This defines a single node to use for bootstrapping, running on local host and listening to port 9090. While it may work -- and does, if your cluster has a local instance running on port 9090, even if it also has other nodes -- you need to use alternate configuration file for other kinds of clusters.

To use different configuration, you can either copy and modify wrapper script; or override config file (see parameter -c / --config-file below).

Shared options

All commands share some commonly used options. Options have two forms: a short, hyphen-and-letter, and longer, two-hyphens-and-words. Some options take an argument.

Current shared options include:

• -t (or --text): Output results as text (default)
• -j (or --json): Output results as JSON (alternative to text)
• -v (or --verbose): Output more information about execution of command
• -c (or --config-file) : Used for specifying alternate configuration file to use.

Commmands

Command: list

To list entries within given partition, you use:

./tstore list tstore://PARTITION@PATH-PREFIX

where partition is an arbitrary partition string (you can choose whatever you want; for example "test"), and PATH-PREFIX is used to specify set of entries to list. While system does not mandate any specific naming convention, it makes to use one: for example, use file-system like notation. So we could use:

./tstore list store://test@/user/Foobar/

if we wanted to store, say, temporary files for set of users; and this would be for use "Foobar".

Command: put

Command to copy one or more local files into specified TransiStore location. Last arguments need to be the server-side prefix to use (which is assumed to use directory-like naming convention -- that is, if prefix does not end with '/', one is appended); other arguments references to local files.

Example usage:

./tstore.sh put pom.xml tstore://test@/tmp/

to store a copy of local file "pom.xml", with server-side path of tstore://test@/tmp/pom.xml

Command: get

This command is reverse of put and can be used for retrieving zero or more server-stored entries into specified local directory.

Example usage:

./tstore.sh get tstore://test@/tmp/ local-copy/

would copy all entries in partition "test", whose names start with "/tmp/", into local directory "local-copy".

Command: Cat

This command is similar to get', but instead of retrieving and storing a copy, it will instead simply print out entry or entries into stdout`. This is useful for having a look at a store resource.

For example:

./tstore.sh cat tstore://test@/tmp/pom.xml

would show contents of the file you stored earlier.

Command: delete

Delete can be used to delete one or more entries that are stored on server.

Note that by default entry reference is assumed to be exact match: if you want to use prefix (to be able to delete multiple entries) you MUST specify option '-r' (see below).

So this:

./tstore.sh delete tstore://test@/tmp/pom.xml

would try to remove a single specific stored entry; whereas this:

./tstore.sh delete -r tstore://test@/tmp/

would try to delete

Additional options:

• -r / --recursive: Specifies that given entry definition is to be used as a prefix for set of entries to delete.
• -m / --max: Specifies maximum number of entries to delete, when doing recursive deletion. Default value is 500.

NOTE: TransiStore implements deletion by using so-called "tombstones" -- zero-length specifically marker entries on server. These are needed to ensure that deletions are propagated to other servers, even if there are transient accessibility problems. Tombstones get deleted at a later point. Because of this, it may be possible to see traces of deleted entries when using a client library (or in future tools may be added to expose existing tombstones). During normal operation you should not see these tombstones; but it is good to be aware of their existence.

Command: help

This is the command for learning more details about specific command (such as options), like so:

./tstore.sh help list

Command: generate

This is a test command -- for more details, check help with tstore help generate