The Java SDK v1 provides a low level API to call Arvados from Java.


  • The Java SDK requires Java 6 or later
  • The Java SDK is implemented as a maven project. Hence, you would need a working
    maven environment to be able to build the source code. If you do not have maven setup,
    you may find the Maven in 5 Minutes link useful.
  • In this document $ARVADOS_HOME is used to refer to the directory where
    arvados code is cloned in your system. For ex: $ARVADOS_HOME = $HOME/arvados

Setting up the environment

  • The SDK requires a running Arvados API server. The following information
    about the API server needs to be passed to the SDK using environment
    variables or during the construction of the Arvados instance.
ARVADOS_API_TOKEN: API client token to be used to authorize with API server.

ARVADOS_API_HOST: Host name of the API server.

ARVADOS_API_HOST_INSECURE: Set this to true if you are using self-signed
    certificates and would like to bypass certificate validations.

Building the Arvados SDK

$ cd $ARVADOS_HOME/sdk/java

$ mvn -Dmaven.test.skip=true clean package
  This will generate arvados sdk jar file in the target directory

Implementing your code to use SDK

  • The following two sample programs serve as sample implementations using the SDK.
    $ARVADOS_HOME/sdk/java/ is a simple program
    that makes a few calls to API server.
    $ARVADOS_HOME/sdk/java/ can be
    used to make calls to API server interactively.

Please use these implementations to see how you would use the SDK from your java program.

Also, refer to $ARVADOS_HOME/arvados/sdk/java/src/test/java/org/arvados/sdk/java/
for more sample API invocation examples.

Below are the steps to compile and run these java program.

  • These programs create an instance of Arvados SDK class and use it to
    make various call requests.
  • To compile the examples
    $ javac -cp $ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
    This results in the generation of the ArvadosSDKJavaExample*.class files
    in the same directory as the java files
  • To run the samples
    $ java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
    $ java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \

Viewing and Managing SDK logging

  • SDK uses log4j logging
  • The default location of the log file is
  • Update file to change name and location of the log file.
$ nano $ARVADOS_HOME/sdk/java/src/main/resources/
and modify the log4j.appender.fileAppender.File property as needed.

Rebuild the SDK:
$ mvn -Dmaven.test.skip=true clean package

Using the SDK in eclipse

  • To develop in eclipse, you can use the provided eclipse project
  • Set M2_REPO classpath variable in eclipse to point to your local repository.
    The local repository is usually located in your home directory at $HOME/.m2/repository.
In Eclipse IDE:
Window -> Preferences -> Java -> Build Path -> Classpath Variables
    Click on the "New..." button and add a new
    M2_REPO variable and set it to your local Maven repository
  • Open the SDK project in eclipse
    In Eclipse IDE:
    File -> Import -> Existing Projects into Workspace -> Next -> Browse
        and select $ARVADOS_HOME/sdk/java

Previous: Javadoc Reference Next: Examples

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.