sdk/java/README

   1 == Arvados Java SDK
   2
   3   - Using the Arvados Java SDK, you can access API server from a java program.
   4
   5   - Please refer to http://doc.arvados.org/api/index.html for a complete list
   6     of supported resources and methods.
   7
   8   - This document highlights the details as to how to use the SDK.
   9
  10   - The Java SDK requires Java 6 or later
  11
  12   - The Java SDK is used as a maven project. Hence, you would need a working
  13       maven environment to be able to build the source code.
  14
  15       If you do not have maven setup, you may find the following link useful.
  16
  17       http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html
  18
  19   - In this document <ARVADOS_HOME> is used to refer to the directory where
  20       arvados code is cloned in your system.
  21       For ex: <ARVADOS_HOME> = $HOME/arvados
  22
  23
  24 == Setting up the environment
  25
  26   - The SDK requires a running Arvados API server. The information about the
  27           API server needs to be passed to the SDK using environment variables or
  28           during the construction of the Arvados instance.
  29
  30   - Below are the details about the environment variables and example setup
  31           statements for a .bashrc file.
  32
  33       1. ARVADOS_API_TOKEN
  34
  35         API client token to be used to authorize with API server.
  36
  37         export ARVADOS_API_TOKEN=z40gplmla6i58rsg96jhg5u41ewdl5rj4g1py2s6e2lsc3
  38
  39           2. ARVADOS_API_HOST
  40
  41             Host name of the API server.
  42
  43                 export ARVADOS_API_HOST=localhost:3001
  44
  45       3. ARVADOS_API_HOST_INSECURE
  46
  47         Set this to true if you are using self-signed certificates and
  48         would like to bypass certificate validations.
  49
  50         export ARVADOS_API_HOST_INSECURE=true
  51
  52
  53 == Building the Arvados SDK
  54
  55   - cd <ARVADOS_HOME/sdk/java
  56
  57   - mvn clean package
  58
  59       This will generate arvados sdk jar file in the target directory
  60
  61
  62 == Implementing your code to use SDK
  63
  64   - <ARVADOS_HOME>/sdk/java/ArvadosSDKJavaExample.java serves as an example
  65       implementation using the java SDK. Please use this file to see how
  66       you would want use the SDK from your java program.
  67       The steps below use this java class name.
  68
  69   - ArvadosSDKJavaExample.java creates an instance of Arvados SDK class and
  70       uses it to make various "call" requests.
  71
  72   - To compile ArvadosSDKJavaExample.java
  73
  74       javac -cp <ARVADOS_HOME>/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar ArvadosSDKJavaExample.java
  75
  76       This results in the generation of the ArvadosSDKJavaExample.class file
  77         in the same directory as the java file
  78
  79   - To run the class file
  80
  81       java -cp .:<ARVADOS_HOME>/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar ArvadosSDKJavaExample
  82
  83
  84 == Viewing and managing SDK logging
  85
  86   - SDK uses log4j logging
  87
  88   - The default location of the log file is
  89       <ARVADOS_HOME>/sdk/java/log/arvados_sdk_java.log
  90
  91   - Update log4j.properties file to change name and location of the log file.
  92
  93       Modify the "log4j.appender.fileAppender.File" property in log4j.properties
  94         file located at <ARVADOS_HOME>/sdk/java/src/main/resources
  95
  96       Rebuild by running "mvn clean package"
  97
  98
  99 == Using the SDK in eclipse
 100
 101   - To develop in eclipse, you can use the SDK eclipse project.
 102
 103   - Install "m2eclipse" plugin in your eclipse
 104
 105   - Set M2_REPO to your .m2/repository directory
 106
 107   - Open the SDK project.
 108
 109       File -> Import -> Existing Projects into Workspace -> Next -> Browse
 110           and select <ARVADOS_HOME>/sdk/java