== Arvados Java SDK

  - Using the Arvados Java SDK, you can access API server from a java program.

  - Please refer to http://doc.arvados.org/api/index.html for a complete list
    of supported resources and methods.

  - This document highlights the details as to how to use the SDK.

  - 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 following link useful.

      http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

  - 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 information about the
  	  API server needs to be passed to the SDK using environment variables or
  	  during the construction of the Arvados instance.
  	  
  - Below are the details about the environment variables and example setup
  	  statements for a .bashrc file.
  	
      1. ARVADOS_API_TOKEN
      
        API client token to be used to authorize with API server.
      
      	export ARVADOS_API_TOKEN=z40gplmla6i58rsg96jhg5u41ewdl5rj4g1py2s6e2lsc3
	
	  2. ARVADOS_API_HOST
	  
	    Host name of the API server.
	  
		export ARVADOS_API_HOST=localhost:3001

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

      	export ARVADOS_API_HOST_INSECURE=true
      	

== Building the Arvados SDK

  - cd $ARVADOS_HOME/sdk/java

  - mvn clean package

      This will generate arvados sdk jar file in the target directory


== Implementing your code to use SDK

  - $ARVADOS_HOME/sdk/java/ArvadosSDKJavaExample.java serves as an example
      implementation using the java SDK. Please use this file to see how
      you would want 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 this java program.

  - ArvadosSDKJavaExample.java creates an instance of Arvados SDK class and
      uses it to make various "call" requests.

  - To compile ArvadosSDKJavaExample.java

      javac -cp $ARVADOS_HOME/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar ArvadosSDKJavaExample.java

      This results in the generation of the ArvadosSDKJavaExample.class file
        in the same directory as the java file

  - To run the class file

      java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar ArvadosSDKJavaExample


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

      Modify the "log4j.appender.fileAppender.File" property in log4j.properties
        file located at $ARVADOS_HOME/sdk/java/src/main/resources

      Rebuild by running "mvn 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 to your .m2/repository directory

  - Open the SDK project.

      File -> Import -> Existing Projects into Workspace -> Next -> Browse
          and select $ARVADOS_HOME/sdk/java