sara-nl / perltopos

A Topos client library in Perl

Topos Perl Client

The Topos Perl Client provides an object-oriented interface to Perl scripts for accessing Token pools and storing and retrieving pool tokens.

Typical Topos client usage

A client will typically open an existing pool, download tokens until there are no more tokens, and process each token. This is done with the following scriptlet:

...

# open the exisiting pool with name $name
my $pool = new TokenPool ($pool_name);

# download tokens, processing each token;
# set the lock timeout to 100s
while (my $token = $pool -> next_token(100)) {

  # check if the token is a file to be processed, otherwise skip
  next unless $token -> is_file;

  # get the file name
  my $filename = $token -> filename;

  # execute the command to process this file
  system("./process_file $filename");

  # commands to store the results somewhere
  ... 

  # remove the file from the file system
  unlink ($filename);

  # delete the token
  $token -> delete;
}

Creating a ToposPool object

There are two ways to create a ToposPool object:

• by creating a new token pool on the token server;

• by opening an existing token pool.

Creating a new token pool

A new token pool with no tokens can be created and opened with:

my $pool = new TokenPool;

The returned object is a TokenPool object.

Saving the name of a pool to a file

To store the token pool name to a file, for example after creating a new pool and filling it with tokens, use the "save" member function. The "save" member function has an optional file name, which is "pool_id.txt" by default.

$pool -> save;

or

$pool -> save("pool1.txt");

Opening an existing pool

Existing pools can be opened either by specifying the pool name, or by reading the pool name from a file.

Opening the pool by specifying the name uses the new method:

my $pool = new TokenPool ("12ab45cd.....");

Loading the pool from a file:

my $pool = load TokenPool;  # loads from pool_id.txt

or

my $pool = load TokenPool ("pool1.txt");

Creating a text token

Text tokens can be created into the pool with the "create_token" member function:

$pool -> create_token ($text);

Creating a file token

File tokens can be created using the "upload_file_as_token" member function:

$pool -> upload_file_as_token ($filename);

The file name can indicate a relative or absolute path. The path itself is never stored in the token, only the file name.

Getting the next token

my $token = $pool -> next_token;

The member function next_token returns a ToposToken object, which can contain text or a file. See below how to determine the type and to get the contents of the token.

If there are no more available tokens, the next_token function returns undef. This makes this function suitable for while-constructs:

while (my $token = $pool -> next_token) {
  ...
}

The type of the token can be determined with the is_file function of the token:

if ($token -> is_file) {
  ...
}

Getting a text token

If the file is a text token, the content of the token can be retrieved with the token member function "content".

my $content = $token -> content;

If the token contains a file, content returns the file contents (not the file name).

Getting a file token

If a token contains a file, the contents of the file are saved to a file with the original file name.

As a security measure, the save member function always stores the file in the current directory, regardless of the path used when uploading the file.

The token member function 'filename' returns the file name.

my $filename = $token -> filename

Getting the next token with a lock timeout

The next_token member function has one optional parameter, the lock timeout in seconds.

my $token = $pool -> next_token (180); # timeout of 3 minutes

If the lock timeout is omitted, the token is not locked.

Renewing locks on tokens

Locks can be renewed using the token 'renew_lock' member function:

my $token = $pool -> next_token(180); # 3 minutes

while (...) {
  # still running?
  $token -> renew_lock(240); # 4 minutes
}

The renew_lock function has one optional parameter, the new lock timeout value. If no lock timeout value is specified, renew_lock uses the same timeout value as the last lock.

Deleting tokens

Tokens are deleted using the token method "delete":

my $token = $pool -> next_token;
...
$token -> delete;

Deleting the pool

Pools can be deleted using the pool method "delete", deleting all tokens in that pool:

my $pool = load TokenPool();
...
$pool -> delete;

VERSION 1.0