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