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   - This document highlights the details as to how to use the SDK.
   6
   7   - The Java SDK is used as a maven project. Hence, you would need a working
   8       maven environment to be able to build the source code.
   9
  10       If you do not have maven setup, you may find the following link useful.
  11
  12       http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html
  13
  14   - In this document <ARVADOS_HOME> is used to refer to the directory where
  15       arvados code is cloned in your system.
  16       For ex: <ARVADOS_HOME> = $HOME/arvados
  17
  18
  19 == Setting up the environment
  20
  21   - The SDK requires a running Arvados API server. The information about the
  22           API server needs to be passed to the SDK using environment variables.
  23
  24   - The following two environment variables are required by the SDK
  25
  26       ARVADOS_API_TOKEN, ARVADOS_API_HOST
  27
  28       Below are examples using a .bashrc file:
  29
  30         export ARVADOS_API_TOKEN=z40gplmla6i58rsg96jhg5u41ewdl5rj4g1py2xg6s6e2lsc3
  31                 export ARVADOS_API_HOST=localhost:3001
  32
  33   - You can also set ARVADOS_API_HOST_INSECURE to true if you are using
  34           self-signed certificates and want to bypass certificate validations.
  35
  36       Below is an example using a .bashrc file:
  37
  38         export ARVADOS_API_HOST_INSECURE=true
  39
  40
  41 == Building the Arvados SDK
  42
  43   - cd <ARVADOS_HOME/sdk/java
  44
  45   - mvn clean package
  46
  47       This will generate arvados sdk jar file the target directory
  48
  49
  50 == Using Arvados SDK at command line
  51
  52   - This section helps understand how to use the SDK from command line
  53
  54   - cd <ARVADOS_HOME/sdk/java
  55
  56   - Getting help
  57
  58       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados help
  59
  60       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados help call
  61
  62       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados help discover
  63
  64
  65   - Getting the discovery document
  66
  67       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados discover arvados v1
  68
  69
  70   - Making a "call" to the API server
  71
  72       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 users.list
  73
  74       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 users.get <uuid>
  75
  76       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 users.create <filename>
  77
  78       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 pipeline_templates.list
  79
  80       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 pipeline_templates.get <uuid>
  81
  82       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 pipeline_templates.create <filename>
  83
  84
  85 == Implementing your code to use SDK
  86
  87   - <ARVADOS_HOME>/sdk/java/ArvadosSDKJavaExample.java serves as an example
  88       implementation using the java SDK. Please use this file to see how
  89       you would want use the SDK from your java program.
  90       The steps below use this java class name.
  91
  92   - ArvadosSDKJavaExample.java creates an instance of Arvados SDK class and
  93       uses it to make various "call" requests.
  94
  95   - To compile ArvadosSDKJavaExample.java
  96
  97       javac -cp <ARVADOS_HOME>/sdk/java/target/java-1.0-SNAPSHOT-jar-with-dependencies.jar ArvadosSDKJavaExample.java
  98
  99       This results in the generation of the ArvadosSDKJavaExample.class file
 100         in the same dir as the java file
 101
 102   - To run the class file
 103
 104       java -cp .:<ARVADOS_HOME>/sdk/java/target/java-1.0-SNAPSHOT-jar-with-dependencies.jar ArvadosSDKJavaExample
 105
 106
 107 == Viewing and managing SDK logging
 108
 109   - SDK uses log4j logging
 110
 111   - The default location of the log file is
 112       <ARVADOS_HOME>/sdk/java/log/arvados_sdk_java.log
 113
 114   - Update log4j.properties file to change name and location of the log file.
 115
 116       Modify the "log4j.appender.fileAppender.File" property in log4j.properties
 117         file located at <ARVADOS_HOME>/sdk/java/src/main/resources
 118
 119       Rebuild by running "mvn clean package"
 120
 121
 122 == Using the SDK in eclipse
 123
 124   - To develop in eclipse, you can use the SDK eclipse project.
 125
 126   - Install "m2eclipse" plugin in your eclipse
 127
 128   - Open the SDK project.
 129
 130       File -> Import -> Existing Projects into Workspace -> Next -> Browse
 131           and select <ARVADOS_HOME>/sdk/java