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

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