---
layout: default
navsection: sdk
navmenu: Java
title: "Installation"
...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

The Java SDK provides a generic set of wrappers so you can make API calls in java.

h3. 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":http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html 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


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

<notextile>
<pre>
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.
</pre>
</notextile>

* Please see "api-tokens":{{site.baseurl}}/user/reference/api-tokens.html for full details.


h3. Building the Arvados SDK

<notextile>
<pre>
$ <code class="userinput">cd $ARVADOS_HOME/sdk/java</code>

$ <code class="userinput">mvn -Dmaven.test.skip=true clean package</code>
  This will generate arvados sdk jar file in the target directory
</pre>
</notextile>


h3. Implementing your code to use SDK

* The following two sample programs serve as sample implementations using the SDK.
<code class="userinput">$ARVADOS_HOME/sdk/java/ArvadosSDKJavaExample.java</code> is a simple program
        that makes a few calls to API server.
<code class="userinput">$ARVADOS_HOME/sdk/java/ArvadosSDKJavaExampleWithPrompt.java</code> 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 <code class="userinput">$ARVADOS_HOME/arvados/sdk/java/src/test/java/org/arvados/sdk/java/ArvadosTest.java</code>
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 <code class="userinput">call</code> requests.

* To compile the examples
<notextile>
<pre>
$ <code class="userinput">javac -cp $ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
ArvadosSDKJavaExample*.java</code>
This results in the generation of the ArvadosSDKJavaExample*.class files
in the same directory as the java files
</pre>
</notextile>

* To run the samples
<notextile>
<pre>
$ <code class="userinput">java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
ArvadosSDKJavaExample</code>
$ <code class="userinput">java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
ArvadosSDKJavaExampleWithPrompt</code>
</pre>
</notextile>


h3. Viewing and Managing SDK logging

* SDK uses log4j logging

* The default location of the log file is
  <code class="userinput">$ARVADOS_HOME/sdk/java/log/arvados_sdk_java.log</code>

* Update <code class="userinput">log4j.properties</code> file to change name and location of the log file.

<notextile>
<pre>
$ <code class="userinput">nano $ARVADOS_HOME/sdk/java/src/main/resources/log4j.properties</code>
and modify the <code class="userinput">log4j.appender.fileAppender.File</code> property as needed.

Rebuild the SDK:
$ <code class="userinput">mvn -Dmaven.test.skip=true clean package</code>
</pre>
</notextile>


h3. Using the SDK in eclipse

* To develop in eclipse, you can use the provided <code class="userinput">eclipse project</code>

* Install "m2eclipse":https://www.eclipse.org/m2e/ plugin in your eclipse

* Set <code class="userinput">M2_REPO</code> classpath variable in eclipse to point to your local repository.
The local repository is usually located in your home directory at <code class="userinput">$HOME/.m2/repository</code>.

<notextile>
<pre>
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
</pre>
</notextile>


* Open the SDK project in eclipse
<notextile>
<pre>
In Eclipse IDE:
File -> Import -> Existing Projects into Workspace -> Next -> Browse
    and select $ARVADOS_HOME/sdk/java
</pre>
</notextile>