SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-The Java SDK v2 provides a high level API for working with Arvados resources and files in Keep.
-
-h2. Building the Arvados SDK
-
-* The Java SDK requires Java 8 or later
-
-* The Java SDK is implemented as a Gradle project. Gradle is included in the source tree.
-
-<notextile>
-<pre>
-$ <code class="userinput">git clone https://github.com/curoverse/arvados.git</code>
-$ <code class="userinput">cd arvados/sdk/java-v2</code>
-$ <code class="userinput">./gradlew jar</code>
- This will generate arvados sdk jar file in build/libs/arvados-java-2.0.0.jar
-</pre>
-</notextile>
+The Arvados Java SDK v2 provides a high level API for working with Arvados resources. It is packaged as a single JAR named
+arvados-java-<version>.jar, e.g. arvados-java-2.0.0.jar
+which can be included in your project using Gradle, Maven, or by hand.
h2. Using the SDK
+FIXME - Add intro text here
+
h3. Logging
-SLF4J is used for logging. Concrete logging framework and configuration must be provided by a client.
+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.
h3. Configuration
"TypeSafe Configuration":https://github.com/lightbend/config is used for configuring this library.
-Please, have a look at java/resources/reference.conf for default values provided with this library.
+Please review src/main/resources/reference.conf for default values provided with this library.
-* **keepweb-host** - change to host of your Keep-Web installation
-* **keepweb-port** - change to port of your Keep-Web installation
-* **host** - change to host of your Arvados installation
-* **port** - change to port of your Arvados installation
-* **token** - authenticates registered user, one must provide "token obtained from Arvados Workbench":https://doc.arvados.org/user/reference/api-tokens.html
-* **protocol** - don't change to unless really needed
-* **host-insecure** - insecure communication with Arvados (ignores SSL certificate verification), don't change to *true* unless really needed
-* **split-size** - size of chunk files in megabytes
+* **keepweb-host** - host of your Keep-Web server (default: localhost)
+* **keepweb-port** - port of your Keep-Web server (default: 8000)
+* **host** - host of your Arvados API server
+* **port** - port of your Arvados API server
+* **token** - Arvados token to authenticate registered user, one must provide "token obtained from Arvados Workbench":https://doc.arvados.org/user/reference/api-tokens.html
+* **protocol** - don't change to unless really needed (default: https)
+* **host-insecure** - ignores SSL certificate verification if true (default: false Don't change to *true* unless really needed)
+* **split-size** - size of chunk files in megabytes (default: 64)
* **temp-dir** - temporary chunk files storage
* **copies** - amount of chunk files duplicates per Keep server
-* **retries** - in case of chunk files send failure this should allow to repeat send
- (*NOTE*: this parameter is not used at the moment but was left for future improvements)
+* **retries** - UNIMPLEMENTED
-In order to override default settings one can create application.conf file in an application. Example: src/test/resources/application.conf.
+In order to override default settings one can create an application.conf file in an application. Example: src/test/resources/application.conf.
-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.
+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.
-ArvadosFacade has two constructors, one without arguments that uses values from reference.conf and second one taking ExternalConfigProvider as an argument.
+@ArvadosFacade@ has two constructors, one without arguments that uses values from application.conf and second one taking @ExternalConfigProvider@ as an argument.
h3. API clients
-All API clients inherit from BaseStandardApiClient. This class contains implementation of all common methods as described in http://doc.arvados.org/api/methods.html.
+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.
Parameters provided to common or specific methods are String UUID or fields wrapped in Java objects. For example:
h3. Business logic
-More advanced API data handling could be implemented as *Facade* classes. In current version functionalities provided by SDK are handled by *ArvadosFacade*. They include:
+More advanced API data handling could be implemented as *Facade* classes. In current version functionalities provided by SDK are handled by @ArvadosFacade@. They include:
* **downloading single file from collection** - using Keep-Web
* **downloading whole collection** - using Keep-Web or Keep Server API
h3. Note regarding Keep-Web
-Current version requires both Keep Web and standard Keep Server API configured in order to use Keep-Web functionalities.
+The Java SDK requires Keep Web (which is part of the standard configuration) as well as the API server and Keep server(s).
h3. Integration tests
-In order to run integration tests all fields within following configuration file must be provided:
+In order to run the integration tests, all fields within following configuration file must be provided: @src/test/resources/integration-test-appliation.conf@
-<code>
-src/test/resources/integration-test-appliation.conf
-</code>
-Parameter **integration-tests.project-uuid** should contain UUID of one project available to user, whose token was provided within configuration file.
+The parameter @integration-tests.project-uuid@ should contain UUID of one project available to user who's token was provided within configuration file.
-Integration tests require connection to real Arvados server.
+Integration tests require connection to a real Arvados server.
h3. Note regarding file naming
-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.
+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.
h3. Javadoc
See "Javadoc":javadoc.html
+
+h2. Building the Arvados SDK
+
+Dependencies:
+* JDK for Java 8 or later https://www.oracle.com/technetwork/java/javase/downloads/index.html
+* Gradle https://gradle.org/install/
+
+
+<notextile>
+<pre>
+$ <code class="userinput">git clone https://github.com/curoverse/arvados.git</code>
+$ <code class="userinput">cd arvados/sdk/java-v2</code>
+$ <code class="userinput">./gradlew test</code>
+$ <code class="userinput">./gradlew jar</code>
+</pre>
+This will build the SDK and run all unit tests, then generate an Arvados Java sdk jar file in build/libs/arvados-java-2.0.0.jar
+</notextile>
+
projects / arvados.git / commitdiff