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

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: Java SDK v2
   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 Arvados Java SDK v2 provides a high level API for working with Arvados resources.
  14
  15 h2. Using the SDK
  16
  17 The SDK is packaged as a JAR named @arvados-java-<version>.jar@, which is published to Maven Central and can be included using Maven, Gradle, or by hand.
  18
  19 Here is an example @build.gradle@ file that uses the Arvados java sdk:
  20
  21 <pre>
  22 apply plugin: 'application'
  23 apply plugin: 'java-library'
  24 apply plugin: 'maven'
  25
  26 repositories {
  27     mavenCentral()
  28 }
  29
  30 application {
  31     mainClassName = "org.arvados.example.CollectionExample"
  32 }
  33
  34 dependencies {
  35     api 'org.arvados:arvados-java-sdk:0.1.1'
  36 }
  37 </pre>
  38
  39 See "Java SDK Examples":example.html to get started using the SDK.
  40
  41 h3. Logging
  42
  43 The SDK uses the SLF4J facade library for logging. A concrete logging "binding":https://www.slf4j.org/manual.html#swapping (and configuration, if required) must be provided by a client. For small applications, you can use the Simple implementation by adding slf4j-simple-1.8.0-beta4.jar to your classpath.
  44
  45 h3. Configuration
  46
  47 "TypeSafe Configuration":https://github.com/lightbend/config is used for configuring this library.
  48
  49 Please review src/main/resources/reference.conf for default values provided with this library.
  50
  51 * **keepweb-host** - host of your Keep-Web server (default: localhost)
  52 * **keepweb-port** - port of your Keep-Web server (default: 8000)
  53 * **host** - host of your Arvados API server
  54 * **port** - port of your Arvados API server
  55 * **token** - Arvados token to authenticate registered user, one must provide "token obtained from Arvados Workbench":https://doc.arvados.org/user/reference/api-tokens.html
  56 * **protocol** - don't change to unless really needed (default: https)
  57 * **host-insecure** - ignores SSL certificate verification if true (default: false Don't change to *true* unless really needed)
  58 * **split-size** - size of chunk files in megabytes (default: 64)
  59 * **temp-dir** - temporary chunk files storage
  60 * **copies** - amount of chunk files duplicates per Keep server
  61 * **retries** - UNIMPLEMENTED
  62
  63 In order to override default settings one can create an application.conf file in an application.  Example: src/test/resources/application.conf.
  64
  65 Alternatively @ExternalConfigProvider@ class can be used to pass configuration via code.  @ExternalConfigProvider@ comes with a builder and all of the above values must be provided in order for it to work properly.
  66
  67 @ArvadosFacade@ has two constructors, one without arguments that uses values from application.conf and second one taking @ExternalConfigProvider@ as an argument.
  68
  69 h3. API clients
  70
  71 All API clients inherit from @BaseStandardApiClient@. This class contains implementation of all common methods as described in "Arvados Common Resource Methods":http://doc.arvados.org/api/methods.html.
  72
  73 Parameters provided to common or specific methods are String UUID or fields wrapped in Java objects. For example:
  74
  75 {% codeblock as java %}
  76 String uuid = "ardev-4zz18-rxcql7qwyakg1r1";
  77
  78 Collection actual = client.get(uuid);
  79 {% endcodeblock %}
  80
  81 {% codeblock as java %}
  82 ListArgument listArgument = ListArgument.builder()
  83         .filters(Arrays.asList(
  84                 Filter.of("owner_uuid", Operator.LIKE, "ardev%"),
  85                 Filter.of("name", Operator.LIKE, "Super%"),
  86                 Filter.of("portable_data_hash", Operator.IN, Lists.newArrayList("54f6d9f59065d3c009d4306660989379+65")
  87             )))
  88         .build();
  89
  90 CollectionList actual = client.list(listArgument);
  91 {% endcodeblock %}
  92
  93 Non-standard API clients must inherit from BaseApiClient. For example: KeepServerApiClient communicates directly with Keep servers using exclusively non-common methods.
  94
  95 h3. Business logic
  96
  97 More advanced API data handling could be implemented as *Facade* classes. In current version functionalities provided by SDK are handled by @ArvadosFacade@. They include:
  98
  99 * **downloading single file from collection** - using Keep-Web
 100 * **downloading whole collection** - using Keep-Web or Keep Server API
 101 * **listing file info from certain collection** - information is returned as list of *FileTokens* providing file details
 102 * **uploading single file** - to either new or existing collection
 103 * **uploading list of files** - to either new or existing collection
 104 * **creating an empty collection**
 105 * **getting current user info**
 106 * **listing current user's collections**
 107 * **creating new project**
 108 * **deleting certain collection**
 109
 110 h3. Note regarding Keep-Web
 111
 112 The Java SDK requires Keep Web (which is part of the standard configuration) as well as the API server and Keep server(s).
 113
 114 h3. Integration tests
 115
 116 In order to run the integration tests, all fields within following configuration file must be provided: @src/test/resources/integration-test-appliation.conf@
 117
 118
 119 The parameter @integration-tests.project-uuid@ should contain UUID of one project available to user who's token was provided within configuration file.
 120
 121 Integration tests require connection to a real Arvados server.
 122
 123 h3. Note regarding file naming
 124
 125 When uploading via the current implementation of the Java SDK all uploaded files within single collection must have different names. This applies also to uploading files to already existing collection. Renaming files with duplicate names is not currently implemented.
 126
 127 h3. Javadoc
 128
 129 See "Javadoc":javadoc.html
 130
 131 h2. Building the Arvados SDK
 132
 133 Dependencies:
 134 * JDK for Java 8 or later "https://www.oracle.com/technetwork/java/javase/downloads/index.html":https://www.oracle.com/technetwork/java/javase/downloads/index.html
 135 * Gradle "https://gradle.org/install/":https://gradle.org/install/
 136
 137
 138 <notextile>
 139 <pre>
 140 $ <code class="userinput">git clone https://github.com/arvados/arvados.git</code>
 141 $ <code class="userinput">cd arvados/sdk/java-v2</code>
 142 $ <code class="userinput">gradle test</code>
 143 $ <code class="userinput">gradle jar -Pversion=0.1.1</code>
 144 </pre>
 145 This will build the SDK and run all unit tests, then generate an Arvados Java sdk jar file in build/libs/arvados-java-0.1.1.jar
 146 </notextile>