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 implemented as a maven project. Hence, you would need a
  13       working 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
  68     Also, refer to $ARVADOS_HOME/arvados/sdk/java/src/test/java/org/arvados/sdk/java/ArvadosTest.java
  69      for more sample API invocation examples.
  70
  71       Below are the steps to compile and run this java program.
  72
  73   - ArvadosSDKJavaExample.java creates an instance of Arvados SDK class and
  74       uses it to make various "call" requests.
  75
  76   - To compile ArvadosSDKJavaExample.java
  77
  78       javac -cp $ARVADOS_HOME/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar ArvadosSDKJavaExample.java
  79
  80       This results in the generation of the ArvadosSDKJavaExample.class file
  81         in the same directory as the java file
  82
  83   - To run the class file
  84
  85       java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar ArvadosSDKJavaExample
  86
  87
  88 == Viewing and managing SDK logging
  89
  90   - SDK uses log4j logging
  91
  92   - The default location of the log file is
  93       $ARVADOS_HOME/sdk/java/log/arvados_sdk_java.log
  94
  95   - Update log4j.properties file to change name and location of the log file.
  96
  97       Modify the "log4j.appender.fileAppender.File" property in log4j.properties
  98         file located at $ARVADOS_HOME/sdk/java/src/main/resources
  99
 100       Rebuild by running "mvn clean package"
 101
 102
 103 == Using the SDK in eclipse
 104
 105   - To develop in eclipse, you can use the provided eclipse project.
 106
 107   - Install "m2eclipse" plugin in your eclipse
 108
 109   - Set M2_REPO to your .m2/repository directory
 110
 111   - Open the SDK project.
 112
 113       File -> Import -> Existing Projects into Workspace -> Next -> Browse
 114           and select $ARVADOS_HOME/sdk/java