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