Installation

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

Introdution

• 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.

• Please see api-tokens for full details.

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/ArvadosSDKJavaExample.java is a simple program
  that makes a few calls to API server.
  $ARVADOS_HOME/sdk/java/ArvadosSDKJavaExampleWithPrompt.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/ArvadosTest.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 \
  ArvadosSDKJavaExample*.java
  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 \
  ArvadosSDKJavaExample
  $ java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
  ArvadosSDKJavaExampleWithPrompt
  

Viewing and Managing SDK logging

• SDK uses log4j logging

• The default location of the log file is
  $ARVADOS_HOME/sdk/java/log/arvados_sdk_java.log

• Update log4j.properties file to change name and location of the log file.

$ nano $ARVADOS_HOME/sdk/java/src/main/resources/log4j.properties
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

• Install m2eclipse plugin in your eclipse

• 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