sdk/java-v2/README.md

   1 ```
   2 Copyright (C) The Arvados Authors. All rights reserved.
   3
   4 SPDX-License-Identifier: CC-BY-SA-3.0
   5 ```
   6
   7 # Arvados Java SDK
   8
   9 ##### About
  10 Arvados Java Client allows to access Arvados servers and uses two APIs:
  11 * lower level [Keep Server API](https://doc.arvados.org/api/index.html)
  12 * higher level [Keep-Web API](https://godoc.org/github.com/arvados/arvados/services/keep-web) (when needed)
  13
  14 ##### Required Java version
  15 This SDK requires Java 8+
  16
  17 ##### Logging
  18
  19 SLF4J is used for logging. Concrete logging framework and configuration must be provided by a client.
  20
  21 ##### Configuration
  22
  23 [TypeSafe Configuration](https://github.com/lightbend/config) is used for configuring this library.
  24
  25 Please, have a look at java/resources/reference.conf for default values provided with this library.
  26
  27 * **keepweb-host** - change to host of your Keep-Web installation
  28 * **keepweb-port** - change to port of your Keep-Web installation
  29 * **host** - change to host of your Arvados installation
  30 * **port** - change to port of your Arvados installation
  31 * **token** - authenticates registered user, one must provide
  32   [token obtained from Arvados Workbench](https://doc.arvados.org/user/reference/api-tokens.html)
  33 * **protocol** - don't change to unless really needed
  34 * **host-insecure** - insecure communication with Arvados (ignores SSL certificate verification),
  35   don't change to *true* unless really needed
  36 * **split-size** - size of chunk files in megabytes
  37 * **temp-dir** - temporary chunk files storage
  38 * **copies** - amount of chunk files duplicates per Keep server
  39 * **retries** - in case of chunk files send failure this should allow to repeat send
  40   (*NOTE*: this parameter is not used at the moment but was left for future improvements)
  41
  42 In order to override default settings one can create application.conf file in an application.
  43 Example: src/test/resources/application.conf.
  44
  45 Alternatively ExternalConfigProvider class can be used to pass configuration via code.
  46 ExternalConfigProvider comes with a builder and all of the above values must be provided in order for it to work properly.
  47
  48 ArvadosFacade has two constructors, one without arguments that uses values from reference.conf and second one
  49 taking ExternalConfigProvider as an argument.
  50
  51 ##### API clients
  52
  53 All API clients inherit from BaseStandardApiClient. This class contains implementation of all
  54 common methods as described in http://doc.arvados.org/api/methods.html.
  55
  56 Parameters provided to common or specific methods are String UUID or fields wrapped in Java objects. For example:
  57
  58 ```java
  59 String uuid = "ardev-4zz18-rxcql7qwyakg1r1";
  60
  61 Collection actual = client.get(uuid);
  62 ```
  63
  64 ```java
  65 ListArgument listArgument = ListArgument.builder()
  66         .filters(Arrays.asList(
  67                 Filter.of("owner_uuid", Operator.LIKE, "ardev%"),
  68                 Filter.of("name", Operator.LIKE, "Super%"),
  69                 Filter.of("portable_data_hash", Operator.IN, Lists.newArrayList("54f6d9f59065d3c009d4306660989379+65")
  70             )))
  71         .build();
  72
  73 CollectionList actual = client.list(listArgument);
  74 ```
  75
  76 Non-standard API clients must inherit from BaseApiClient.
  77 For example: KeepServerApiClient communicates directly with Keep servers using exclusively non-common methods.
  78
  79 ##### Business logic
  80
  81 More advanced API data handling could be implemented as *Facade* classes.
  82 In current version functionalities provided by SDK are handled by *ArvadosFacade*.
  83 They include:
  84 * **downloading single file from collection** - using Keep-Web
  85 * **downloading whole collection** - using Keep-Web or Keep Server API
  86 * **listing file info from certain collection** - information is returned as list of *FileTokens* providing file details
  87 * **uploading single file** - to either new or existing collection
  88 * **uploading list of files** - to either new or existing collection
  89 * **creating an empty collection**
  90 * **getting current user info**
  91 * **listing current user's collections**
  92 * **creating new project**
  93 * **deleting certain collection**
  94
  95 ##### Note regarding Keep-Web
  96
  97 Current version requires both Keep Web and standard Keep Server API configured in order to use Keep-Web functionalities.
  98
  99 ##### Integration tests
 100
 101 In order to run integration tests all fields within following configuration file must be provided:
 102 ```java
 103 src/test/resources/integration-test-appliation.conf
 104 ```
 105 Parameter **integration-tests.project-uuid** should contain UUID of one project available to user,
 106 whose token was provided within configuration file.
 107
 108 Integration tests require connection to real Arvados server.
 109
 110 ##### Note regarding file naming
 111
 112 While uploading via this SDK all uploaded files within single collection must have different names.
 113 This applies also to uploading files to already existing collection.
 114 Renaming files with duplicate names is not implemented in current version.
 115