General FAQ

How to use JSAGA ?

JSAGA is an implementation of the SAGA specification, so it is supposed to be used as any other implementation of this specification.

Please refer to the Open Grid Forum documentation to learn more about SAGA specification and how to use it.

You can also see sample code here.


How to develop my first grid application ?

See the following example (list entries under specified URL):

import org.ogf.saga.file.FileFactory;
import org.ogf.saga.url.URL;
import org.ogf.saga.url.URLFactory;

public class List {
    public static void main(String[] args) throws Exception {
        System.setProperty("saga.factory", "fr.in2p3.jsaga.impl.SagaFactoryImpl");
        if (args.length != 1) {
            throw new Exception("usage: List <URL>");
        for (URL url : FileFactory.createDirectory(URLFactory.createURL(args[0])).list()) {


How to compile your grid application with javac ?

Download and install JSAGA.

Set the JSAGA_HOME environment variable to your JSAGA installation path.

Compile your grid application:

javac -d . -classpath $JSAGA_HOME/lib/saga-api-1.1.1-rm.jar

Run your grid application:

java -cp .:$JSAGA_HOME/lib/'*' -DJSAGA_HOME=$JSAGA_HOME List file:///


How to compile your grid application with maven ?

Add to your profiles, settings or project file the CC-IN2P3 maven repository:

            <id>CC-IN2P3 maven repository</id>

Add to your project file the dependencies needed for build:


Add to your project file the dependencies needed for runtime or for testing:

        <!-- add all the adaptors that you expect to use (for example, add jsaga-adaptor-classic for file://) -->

where ${version} is the version of JSAGA you want to compile with.


Configuration FAQ

Why does JSAGA need configuration ?

Rather than trying to connect to grid resource with several security contexts, in JSAGA we prefer to rely on configuration in order to have more predictible behaviors.

This choice allows to prevent from:

  • efficiency problems (e.g. wasting time while trying bad contexts, long running jobs failing to save result because of unexpected VO/role...),
  • failures (e.g. creating entries unaccessible to partners, locking account because of too many failed attempts...),
  • and security issues (i.e. sending authentication information to the wrong service).


Is it always required to configure JSAGA ?

If your SAGA session contains several security contexts, then you must provide to JSAGA the information needed to select the right context for each service. You can do this:

  • either by configuring JSAGA default contexts and/or default sessions,
  • or by prefixing your URL with the identifier of the context to use (e.g. MyCtx-protocol://hostname).
In order to improve portability of your code with other SAGA implementations, the recommended way is to configure JSAGA, and to use URL prefix (or scheme aliases) only when configuration is not enough to disambiguate context selection.

If your SAGA session contains only one security context, then neither configuration, nor URL prefix (or scheme aliases), are required.


How to configure JSAGA ?

The configuration can be done:

  • either by editing the jsaga-default-contexts.xml configuration file. This is the recommended way to go in order to keep the code of your application portable to other SAGA implementations.
  • or programmatically (through the SAGA API). This enables:
    • dynamic configuration (e.g. configuration depending on runtime decisions),
    • per-session configuration (e.g. if you need one different configuration for each session).


How to configure JSAGA with configuration file ?

The jsaga-default-contexts.xml configuration file is composed of two parts:

  • <contexts>: configures the default attribute values of security contexts. Must not contain several contexts with the same type.
  • <session>: configures the default session [SessionFactory.createSession(true)]. Can contain several contexts with the same type, but must not contain several contexts with the same identifier.
Both parts may contain several occurences of element <context>.

A <context> element may contains several occurences of each of the following elements:

  • <attribute>: configures the context itself.
  • <data>/<job>/<resource>:
    • <attribute>: configures the data/job adaptor.
    • <alias>: replace default scheme with specified alias. Possible use-cases for this feature include improving compatibility with other SAGA implementations, selecting different contexts with the same adaptor (like with UrlPrefix), using the same scheme with different adaptors.
    • <include>/<exclude>: configures URL patterns that will respectively select or ignore current context when matched. These patterns will apply to current protocol scheme only.
  • <include>/<exclude>: configures URL patterns that will respectively select or ignore current context when matched. These patterns will apply to all protocol schemes associated to current context.

A <include>/<exclude> element contains optional attributes:

  • domain: the full domain (e.g. '') or country code (e.g. 'fr').
  • host: the host name or part of it (use character '*' to ignore beginning and/or end of name).
  • port: the port number
  • isPortOptional: if true, then URL without port number will also match.
  • basepath: the base path (use character '*' to ignore the name of a directory in the path).


How to configure JSAGA programmatically ?

In order to enable configuring sessions through the SAGA API, JSAGA adds non-standard attribute names to the context objects:

  • UrlPrefix: the identifier of the context within the session. When added at the beginning of the URL (e.g. MyCtx-protocol://hostname), it tells to JSAGA ot use this context for this URL.
  • BaseUrlIncludes: the URL patterns that will select this context when matched.
  • BaseUrlExcludes: the URL patterns that will exclude this context from selection when matched.
  • ServiceAttributes: the configuration of data and execution services associated with this context.

Tips: you can generate the SAGA attribute values from the XML configuration file with command line

jsaga-help --config


Other information useful for configuring JSAGA

You can see an example configuration file for each adaptor: see item "Example" in each adaptor menu.

Some command line interfaces provide information useful to solve configuration problems:

  • The jsaga-help command line interface (see usage with option --help).
  • The jsaga-context-info command line interface (for problems related to security contexts).