Merge branch 'master' into 2525-java-sdk
[arvados.git] / 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