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 following three environment variables are required by the SDK
  22
  23       ARVADOS_API_TOKEN, ARVADOS_API_HOST, ARVADOS_API_HOST_INSECURE
  24
  25
  26 == Building the Arvados SDK
  27
  28   - cd <ARVADOS_HOME/sdk/java
  29
  30   - mvn clean package
  31
  32       This will generate arvados sdk jar file the target directory
  33
  34
  35 == Using Arvados SDK at command line
  36
  37   - This section helps understand how to use the SDK from command line
  38
  39   - cd <ARVADOS_HOME/sdk/java
  40
  41   - Getting help
  42
  43       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados help
  44
  45       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados help call
  46
  47       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados help discover
  48
  49
  50   - Getting the discovery document
  51
  52       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados discover arvados v1
  53
  54
  55   - Making a "call" to the API server
  56
  57       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 users.list
  58
  59       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 users.get <uuid>
  60
  61       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 users.create <filename>
  62
  63       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 pipeline_templates.list
  64
  65       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 pipeline_templates.get <uuid>
  66
  67       java -cp target/java-1.0-SNAPSHOT-jar-with-dependencies.jar org.arvados.sdk.java.Arvados call arvados v1 pipeline_templates.create <filename>
  68
  69
  70 == Implementing your code to use SDK
  71
  72   - <ARVADOS_HOME>/sdk/java/ArvadosSDKJavaUser.java serves as an example
  73       implementation using the java SDK. Please use this file to see how
  74       you would want use the SDK from your java program.
  75       The steps below use this java class name.
  76
  77   - ArvadosSDKJavaUser.java creates an instance of Arvados SDK class and
  78       uses it to make various "call" requests.
  79
  80   - To compile ArvadosSDKJavaUser.java
  81
  82       javac -cp <ARVADOS_HOME>/sdk/java/target/java-1.0-SNAPSHOT-jar-with-dependencies.jar ArvadosSDKJavaUser.java
  83
  84       This results in the generation of the ArvadosSDKJavaUser.class file
  85         in the same dir as the java file
  86
  87   - To run the class file
  88
  89       java -cp .:<ARVADOS_HOME>/sdk/java/target/java-1.0-SNAPSHOT-jar-with-dependencies.jar ArvadosSDKJavaUser
  90
  91
  92 == Viewing and managing SDK logging
  93
  94   - SDK uses log4j logging
  95
  96   - The default location of the log file is
  97       <ARVADOS_HOME>/sdk/java/log/arvados_sdk_java.log
  98
  99   - Update log4j.properties file to change name and location of the log file.
 100
 101       Modify the "log4j.appender.fileAppender.File" property in log4j.properties
 102         file located at <ARVADOS_HOME>/sdk/java/src/main/resources
 103
 104       Rebuild by running "mvn clean package"
 105
 106
 107 == Using the SDK in eclipse
 108
 109   - To develop in eclipse, you can use the SDK eclipse project.
 110
 111   - Install "m2eclipse" plugin in your eclipse
 112
 113   - Open the SDK project.
 114
 115       File -> Import -> Existing Projects into Workspace -> Next -> Browse
 116           and select <ARVADOS_HOME>/sdk/java