doc/sdk/java/index.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: Java
   5 title: "Java SDK"
   6
   7 ...
   8
   9 The Java SDK provides a generic set of wrappers so you can make API calls in java.
  10
  11 h3. Introdution
  12
  13 * The Java SDK requires Java 6 or later
  14
  15 * The Java SDK is implemented as a maven project. Hence, you would need a working
  16 maven environment to be able to build the source code. If you do not have maven setup,
  17 you may find the "Maven in 5 Minutes":http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html link useful.
  18
  19 * In this document $ARVADOS_HOME is used to refer to the directory where
  20 arvados code is cloned in your system. For ex: $ARVADOS_HOME = $HOME/arvados
  21
  22
  23 h3. Setting up the environment
  24
  25 * The SDK requires a running Arvados API server. The following information
  26           about the API server needs to be passed to the SDK using environment
  27           variables or during the construction of the Arvados instance.
  28
  29 <notextile>
  30 <pre>
  31 ARVADOS_API_TOKEN: API client token to be used to authorize with API server.
  32
  33 ARVADOS_API_HOST: Host name of the API server.
  34
  35 ARVADOS_API_HOST_INSECURE: Set this to true if you are using self-signed
  36     certificates and would like to bypass certificate validations.
  37 </pre>
  38 </notextile>
  39
  40 * Please see "api-tokens":{{site.baseurl}}/user/reference/api-tokens.html for full details.
  41
  42
  43 h3. Building the Arvados SDK
  44
  45 <notextile>
  46 <pre>
  47 $ <code class="userinput">cd $ARVADOS_HOME/sdk/java</code>
  48
  49 $ <code class="userinput">mvn -Dmaven.test.skip=true clean package</code>
  50   This will generate arvados sdk jar file in the target directory
  51 </pre>
  52 </notextile>
  53
  54
  55 h3. Implementing your code to use SDK
  56
  57 <code class="userinput">$ARVADOS_HOME/sdk/java/ArvadosSDKJavaExample.java</code> serves as a sample
  58 implementation using the SDK.
  59
  60 Please use this file to see how you would want use the SDK from your java program.
  61
  62 Also, refer to <code class="userinput">$ARVADOS_HOME/arvados/sdk/java/src/test/java/org/arvados/sdk/java/ArvadosTest.java</code>
  63 for more sample API invocation examples.
  64
  65 Below are the steps to compile and run this java program.
  66
  67 * <code class="userinput">ArvadosSDKJavaExample.java</code> creates an instance of Arvados SDK class and uses it to
  68 make various <code class="userinput">call</code> requests.
  69
  70 * To compile ArvadosSDKJavaExample.java
  71 <notextile>
  72 <pre>
  73 $ <code class="userinput">javac -cp $ARVADOS_HOME/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar \
  74 ArvadosSDKJavaExample.java</code>
  75 This results in the generation of the ArvadosSDKJavaExample.class file
  76 in the same directory as the java file
  77 </pre>
  78 </notextile>
  79
  80 * To run the sample
  81 <notextile>
  82 <pre>
  83 $ <code class="userinput">java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.0-jar-with-dependencies.jar \
  84 ArvadosSDKJavaExample</code>
  85 </pre>
  86 </notextile>
  87
  88
  89 h3. Viewing and Managing SDK logging
  90
  91 * SDK uses log4j logging
  92
  93 * The default location of the log file is
  94   <code class="userinput">$ARVADOS_HOME/sdk/java/log/arvados_sdk_java.log</code>
  95
  96 * Update <code class="userinput">log4j.properties</code> file to change name and location of the log file.
  97
  98 <notextile>
  99 <pre>
 100 $ <code class="userinput">nano $ARVADOS_HOME/sdk/java/src/main/resources/log4j.properties</code>
 101 and modify the <code class="userinput">log4j.appender.fileAppender.File</code> property as needed.
 102
 103 Rebuild the SDK:
 104 $ <code class="userinput">mvn -Dmaven.test.skip=true clean package</code>
 105 </pre>
 106 </notextile>
 107
 108
 109 h3. Using the SDK in eclipse
 110
 111 * To develop in eclipse, you can use the provided <code class="userinput">eclipse project</code>
 112
 113 * Install "m2eclipse":https://www.eclipse.org/m2e/ plugin in your eclipse
 114
 115 * Set <code class="userinput">M2_REPO</code> classpath variable in eclipse to point to your local repository.
 116 The local repository is usually located in your home directory at <code class="userinput">$HOME/.m2/repository</code>.
 117
 118 <notextile>
 119 <pre>
 120 In Eclipse IDE:
 121 Window -> Preferences -> Java -> Build Path -> Classpath Variables
 122     Click on the "New..." button and add a new
 123     M2_REPO variable and set it to your local Maven repository
 124 </pre>
 125 </notextile>
 126
 127
 128 * Open the SDK project in eclipse
 129 <notextile>
 130 <pre>
 131 In Eclipse IDE:
 132 File -> Import -> Existing Projects into Workspace -> Next -> Browse
 133     and select $ARVADOS_HOME/sdk/java
 134 </pre>
 135 </notextile>