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 Java SDK v2 provides a high level API for working with Arvados resources and files in Keep.
  14
  15 h2. Building the Arvados SDK
  16
  17 * The Java SDK requires Java 8 or later
  18
  19 * The Java SDK is implemented as a Gradle project. Gradle is included in the source tree.
  20
  21 <notextile>
  22 <pre>
  23 $ <code class="userinput">git clone https://github.com/curoverse/arvados-sdk-java.git</code>
  24
  25 $ <code class="userinput">cd arvados-sdk-java</code>
  26
  27 $ <code class="userinput">./gradlew jar</code>
  28   This will generate arvados sdk jar file in build/libs/arvados-java-2.0.0.jar
  29 </pre>
  30 </notextile>
  31
  32 h2. Using the SDK
  33
  34 h3. Logging
  35
  36 SLF4J is used for logging. Concrete logging framework and configuration must be provided by a client.
  37
  38 h3. Configuration
  39
  40 "TypeSafe Configuration":https://github.com/lightbend/config is used for configuring this library.
  41
  42 Please, have a look at java/resources/reference.conf for default values provided with this library.
  43
  44 * **keepweb-host** - change to host of your Keep-Web installation
  45 * **keepweb-port** - change to port of your Keep-Web installation
  46 * **host** - change to host of your Arvados installation
  47 * **port** - change to port of your Arvados installation
  48 * **token** - authenticates registered user, one must provide "token obtained from Arvados Workbench":https://doc.arvados.org/user/reference/api-tokens.html
  49 * **protocol** - don't change to unless really needed
  50 * **host-insecure** - insecure communication with Arvados (ignores SSL certificate verification), don't change to *true* unless really needed
  51 * **split-size** - size of chunk files in megabytes
  52 * **temp-dir** - temporary chunk files storage
  53 * **copies** - amount of chunk files duplicates per Keep server
  54 * **retries** - in case of chunk files send failure this should allow to repeat send
  55   (*NOTE*: this parameter is not used at the moment but was left for future improvements)
  56
  57 In order to override default settings one can create application.conf file in an application.  Example: src/test/resources/application.conf.
  58
  59 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.
  60
  61 ArvadosFacade has two constructors, one without arguments that uses values from reference.conf and second one taking ExternalConfigProvider as an argument.
  62
  63 h3. API clients
  64
  65 All API clients inherit from BaseStandardApiClient. This class contains implementation of all common methods as described in http://doc.arvados.org/api/methods.html.
  66
  67 Parameters provided to common or specific methods are String UUID or fields wrapped in Java objects. For example:
  68
  69 {% codeblock as java %}
  70 String uuid = "ardev-4zz18-rxcql7qwyakg1r1";
  71
  72 Collection actual = client.get(uuid);
  73 {% endcodeblock %}
  74
  75 {% codeblock as java %}
  76 ListArgument listArgument = ListArgument.builder()
  77         .filters(Arrays.asList(
  78                 Filter.of("owner_uuid", Operator.LIKE, "ardev%"),
  79                 Filter.of("name", Operator.LIKE, "Super%"),
  80                 Filter.of("portable_data_hash", Operator.IN, Lists.newArrayList("54f6d9f59065d3c009d4306660989379+65")
  81             )))
  82         .build();
  83
  84 CollectionList actual = client.list(listArgument);
  85 {% endcodeblock %}
  86
  87 Non-standard API clients must inherit from BaseApiClient. For example: KeepServerApiClient communicates directly with Keep servers using exclusively non-common methods.
  88
  89 h3. Business logic
  90
  91 More advanced API data handling could be implemented as *Facade* classes. In current version functionalities provided by SDK are handled by *ArvadosFacade*. They include:
  92
  93 * **downloading single file from collection** - using Keep-Web
  94 * **downloading whole collection** - using Keep-Web or Keep Server API
  95 * **listing file info from certain collection** - information is returned as list of *FileTokens* providing file details
  96 * **uploading single file** - to either new or existing collection
  97 * **uploading list of files** - to either new or existing collection
  98 * **creating an empty collection**
  99 * **getting current user info**
 100 * **listing current user's collections**
 101 * **creating new project**
 102 * **deleting certain collection**
 103
 104 h3. Note regarding Keep-Web
 105
 106 Current version requires both Keep Web and standard Keep Server API configured in order to use Keep-Web functionalities.
 107
 108 h3. Integration tests
 109
 110 In order to run integration tests all fields within following configuration file must be provided:
 111
 112 <code>
 113 src/test/resources/integration-test-appliation.conf
 114 </code>
 115
 116 Parameter **integration-tests.project-uuid** should contain UUID of one project available to user, whose token was provided within configuration file.
 117
 118 Integration tests require connection to real Arvados server.
 119
 120 h3. Note regarding file naming
 121
 122 While uploading via this 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 implemented in current version.
 123
 124 h3. Javadoc
 125
 126 See "Javadoc":javadoc.html