SAGA Shell Tutorial
SAGA provides a high-level programming interface to various grid systems. SAGA stands for the Simple API for Grid Applications. The API is available for C++, Python, and Java.
In this tutorial, we will use Java SAGA to create a simple shell program. Our shell will mimic a very basic UNIX prompt in which we can issue commands to browse file systems and execute jobs.
For this tutorial, you will need:
Installing Java SAGA
Getting the Shell Tutorial Code
Unzip the file, resulting in a directory saga-shell
Running the Framework
The 'saga-shell.sh' script sets the correct classpath, configures the logging system and starts the main class 'org.ogf.saga.apps.shell.SagaShell'.
Each command in the shell has an associated object in the 'org.ogf.saga.apps.shell.command' package that implements the interface 'org.ogf.saga.apps.shell.command.Command'. The main class creates a map of command names (e.g. 'ls') and the corresponding Command object (e.g. 'org.ogf.saga.apps.shell.command.ListDirectory'). The shell then repeatedly reads a command line, looks up the associated command object, and invokes its 'execute()' method.
Three commands are not implemented yet: 'ls', 'kill', and 'cat'. You task in this tutorial is to implement the 'execute()' methods of their command objects.
Enabling logging output
A great help during debugging are the log messages of the SAGA shell and (possibly) SAGA Java. Both use SLF4J plus log4j for logging statements. You can configure the logging output of the SAGA shell reference implementation and the tutorial code by editing, the configuration file 'log4j.properties'.
Example: to make the SAGA shell more verbose, edit log4j.properties and uncomment this line:
Task 1: implement 'ls'
Your first task is to implement the 'ls' command using SAGA. You will have to edit the 'execute()' method of the class 'org.ogf.saga.apps.shell.command.ListDirectory'. Currently, this method only prints the message "You will have to implement 'ls'!".
Invoking 'ls' should print a list of entries in the current working directory. Java experts may try to print the entries in alphabetical order. Note that for simplicity, the 'ls' command does not take any parameters.
Before you begin: trying to implement a full-fledged “ls -l”, including file sizes, owner, group, and permissions is rather tricky, due to limitations of the Java language. It is fine if you list just the file names. If you want it fancy, you can show whether an entry is a directory or the size of a file.
Task 2: implement 'kill'
Your second task is to implement the 'kill' command, which terminates a background job. The 'kill' code must be added to the method org.ogf.saga.apps.shell.command.KillJob.execute().
Background jobs can be started in the SAGA shell with a 'run' command that ends with a '&'. Example:
[local://localhost+file://localhost/home/you] run /bin/sleep 200 &
All background jobs are added to the task container in the Environment object of the SAGA shell. The 'jobs' command lists all background jobs:
The first string between square brackets is the 'cookie' of the job: a string that identifies the job in the task container of background jobs. The remainder of the line contains more information about the background job, e.g. the job adaptor used (in this case, 'JavaGAT') and the job's startup command. The 'cookie' of the job is the single argument that should be given to a 'kill' command. In this example, we could kill the background job with:
[local://localhost+file://localhost/home/you] kill 7615bb11-3bf5-4f3a-a9f5-c9ae177fe58c
Jobs are run with the current resource manager (in this case 'local://localhost'). The resource manager can be changed with the command 'crm' command. Note that running remote jobs (e.g. via ssh) may require an extra security context. The 'addc' command can be used to add a context, and 'lsc' lists all contexts. Example of running a remote job via ssh:
[local://localhost+file://localhost/home/you] addc ssh UserID=john UserPass=ask
Now implement and test the 'kill' command yourself!
Task 3: implement 'cat'
Your third task is to implement the 'cat' command in the method org.ogf.saga.apps.shell.command.PrintFile.execute().
The 'cat' command prints the contents of a (possibly remote) file. Its argument consists of a single URL that denotes to file to print. The URL can either be relative to the current working directory (e.g. "cat foo.txt"), absolute in the same filesystem (e.g. "cat /etc/passwd") or absolute in a different filesystem (e.g. "cat ssh://example.com/etc/passwd").