8 Copyright (C) The Arvados Authors. All rights reserved.
10 SPDX-License-Identifier: CC-BY-SA-3.0
13 The Java SDK v1 provides a low level API to call Arvados from Java.
15 This is a legacy SDK. It is no longer used or maintained regularly. The "Arvados Java SDK v2":../java-v2/index.html should be used.
19 * The Java SDK requires Java 6 or later
21 * The Java SDK is implemented as a maven project. Hence, you would need a working
22 maven environment to be able to build the source code. If you do not have maven setup,
23 you may find the "Maven in 5 Minutes":http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html link useful.
25 * In this document $ARVADOS_HOME is used to refer to the directory where
26 arvados code is cloned in your system. For ex: $ARVADOS_HOME = $HOME/arvados
29 h3. Setting up the environment
31 * The SDK requires a running Arvados API server. The following information
32 about the API server needs to be passed to the SDK using environment
33 variables or during the construction of the Arvados instance.
37 ARVADOS_API_TOKEN: API client token to be used to authorize with API server.
39 ARVADOS_API_HOST: Host name of the API server.
41 ARVADOS_API_HOST_INSECURE: Set this to true if you are using self-signed
42 certificates and would like to bypass certificate validations.
46 * Please see "api-tokens":{{site.baseurl}}/user/reference/api-tokens.html for full details.
49 h3. Building the Arvados SDK
53 $ <code class="userinput">cd $ARVADOS_HOME/sdk/java</code>
55 $ <code class="userinput">mvn -Dmaven.test.skip=true clean package</code>
56 This will generate arvados sdk jar file in the target directory
61 h3. Implementing your code to use SDK
63 * The following two sample programs serve as sample implementations using the SDK.
64 <code class="userinput">$ARVADOS_HOME/sdk/java/ArvadosSDKJavaExample.java</code> is a simple program
65 that makes a few calls to API server.
66 <code class="userinput">$ARVADOS_HOME/sdk/java/ArvadosSDKJavaExampleWithPrompt.java</code> can be
67 used to make calls to API server interactively.
69 Please use these implementations to see how you would use the SDK from your java program.
71 Also, refer to <code class="userinput">$ARVADOS_HOME/arvados/sdk/java/src/test/java/org/arvados/sdk/java/ArvadosTest.java</code>
72 for more sample API invocation examples.
74 Below are the steps to compile and run these java program.
76 * These programs create an instance of Arvados SDK class and use it to
77 make various <code class="userinput">call</code> requests.
79 * To compile the examples
82 $ <code class="userinput">javac -cp $ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
83 ArvadosSDKJavaExample*.java</code>
84 This results in the generation of the ArvadosSDKJavaExample*.class files
85 in the same directory as the java files
92 $ <code class="userinput">java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
93 ArvadosSDKJavaExample</code>
94 $ <code class="userinput">java -cp .:$ARVADOS_HOME/sdk/java/target/arvados-sdk-1.1-jar-with-dependencies.jar \
95 ArvadosSDKJavaExampleWithPrompt</code>
100 h3. Viewing and Managing SDK logging
102 * SDK uses log4j logging
104 * The default location of the log file is
105 <code class="userinput">$ARVADOS_HOME/sdk/java/log/arvados_sdk_java.log</code>
107 * Update <code class="userinput">log4j.properties</code> file to change name and location of the log file.
111 $ <code class="userinput">nano $ARVADOS_HOME/sdk/java/src/main/resources/log4j.properties</code>
112 and modify the <code class="userinput">log4j.appender.fileAppender.File</code> property as needed.
115 $ <code class="userinput">mvn -Dmaven.test.skip=true clean package</code>
120 h3. Using the SDK in eclipse
122 * To develop in eclipse, you can use the provided <code class="userinput">eclipse project</code>
124 * Install "m2eclipse":https://www.eclipse.org/m2e/ plugin in your eclipse
126 * Set <code class="userinput">M2_REPO</code> classpath variable in eclipse to point to your local repository.
127 The local repository is usually located in your home directory at <code class="userinput">$HOME/.m2/repository</code>.
132 Window -> Preferences -> Java -> Build Path -> Classpath Variables
133 Click on the "New..." button and add a new
134 M2_REPO variable and set it to your local Maven repository
139 * Open the SDK project in eclipse
143 File -> Import -> Existing Projects into Workspace -> Next -> Browse
144 and select $ARVADOS_HOME/sdk/java