[ARVADOS] created: 1.3.0-460-g773dc6a9b
Git user
git at public.curoverse.com
Fri Mar 8 14:20:48 EST 2019
at 773dc6a9b2a8126fd854725bc6c822ebb910b9f3 (commit)
commit 773dc6a9b2a8126fd854725bc6c822ebb910b9f3
Author: Peter Amstutz <pamstutz at veritasgenetics.com>
Date: Fri Mar 8 14:20:32 2019 -0500
14670: Add java sdk v2 to docs
Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <pamstutz at veritasgenetics.com>
diff --git a/.gitignore b/.gitignore
index db3020ae8..877ccdf4d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@ docker/config.yml
doc/.site
doc/sdk/python/arvados
doc/sdk/R/arvados
+doc/sdk/java-v2/javadoc
sdk/perl/MYMETA.*
sdk/perl/Makefile
sdk/perl/blib
diff --git a/doc/Rakefile b/doc/Rakefile
index 9deca3a28..9ebd894b4 100644
--- a/doc/Rakefile
+++ b/doc/Rakefile
@@ -6,7 +6,7 @@
require "rubygems"
require "colorize"
-task :generate => [ :realclean, 'sdk/python/arvados/index.html', 'sdk/R/arvados/index.html' ] do
+task :generate => [ :realclean, 'sdk/python/arvados/index.html', 'sdk/R/arvados/index.html', 'sdk/java-v2/javadoc/index.html' ] do
vars = ['baseurl', 'arvados_cluster_uuid', 'arvados_api_host', 'arvados_workbench_host']
vars.each do |v|
if ENV[v]
@@ -87,6 +87,22 @@ EOF
end
end
+file "sdk/java-v2/javadoc/index.html" do |t|
+ `which java`
+ if $? == 0
+ tgt = Dir.pwd
+ puts "ZZZ ${tgt}"
+ docfiles = []
+ Dir.chdir("../../arvados-sdk-java") do
+ STDERR.puts `./gradlew javadoc 2>&1`
+ end
+ cp_r("../../arvados-sdk-java/build/docs/javadoc", "sdk/java-v2")
+ raise if $? != 0
+ else
+ puts "Warning: java not found, java sdk documentation will not be generated".colorize(:light_red)
+ end
+end
+
task :linkchecker => [ :generate ] do
Dir.chdir(".site") do
`which linkchecker`
@@ -101,6 +117,7 @@ end
task :clean do
rm_rf "sdk/python/arvados"
rm_rf "sdk/R"
+ rm_rf "sdk/java-v2/javadoc"
end
require "zenweb/tasks"
diff --git a/doc/_config.yml b/doc/_config.yml
index 1e17d0470..837e2a868 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -104,7 +104,10 @@ navbar:
- Ruby:
- sdk/ruby/index.html.textile.liquid
- sdk/ruby/example.html.textile.liquid
- - Java:
+ - Java v2:
+ - sdk/java-v2/index.html.textile.liquid
+ - sdk/java-v2/javadoc.html.textile.liquid
+ - Java v1:
- sdk/java/index.html.textile.liquid
- sdk/java/example.html.textile.liquid
api:
diff --git a/doc/sdk/java-v2/index.html.textile.liquid b/doc/sdk/java-v2/index.html.textile.liquid
new file mode 100644
index 000000000..2be3970c7
--- /dev/null
+++ b/doc/sdk/java-v2/index.html.textile.liquid
@@ -0,0 +1,126 @@
+---
+layout: default
+navsection: sdk
+navmenu: Java SDK v2
+title: "Installation"
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+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-sdk-java.git</code>
+
+$ <code class="userinput">cd arvados-sdk-java</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>
+
+h2. Using the SDK
+
+h3. Logging
+
+SLF4J is used for logging. Concrete logging framework and configuration must be provided by a client.
+
+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.
+
+* **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
+* **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)
+
+In order to override default settings one can create 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.
+
+ArvadosFacade has two constructors, one without arguments that uses values from reference.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.
+
+Parameters provided to common or specific methods are String UUID or fields wrapped in Java objects. For example:
+
+{% codeblock as java %}
+String uuid = "ardev-4zz18-rxcql7qwyakg1r1";
+
+Collection actual = client.get(uuid);
+{% endcodeblock %}
+
+{% codeblock as java %}
+ListArgument listArgument = ListArgument.builder()
+ .filters(Arrays.asList(
+ Filter.of("owner_uuid", Operator.LIKE, "ardev%"),
+ Filter.of("name", Operator.LIKE, "Super%"),
+ Filter.of("portable_data_hash", Operator.IN, Lists.newArrayList("54f6d9f59065d3c009d4306660989379+65")
+ )))
+ .build();
+
+CollectionList actual = client.list(listArgument);
+{% endcodeblock %}
+
+Non-standard API clients must inherit from BaseApiClient. For example: KeepServerApiClient communicates directly with Keep servers using exclusively non-common methods.
+
+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:
+
+* **downloading single file from collection** - using Keep-Web
+* **downloading whole collection** - using Keep-Web or Keep Server API
+* **listing file info from certain collection** - information is returned as list of *FileTokens* providing file details
+* **uploading single file** - to either new or existing collection
+* **uploading list of files** - to either new or existing collection
+* **creating an empty collection**
+* **getting current user info**
+* **listing current user's collections**
+* **creating new project**
+* **deleting certain collection**
+
+h3. Note regarding Keep-Web
+
+Current version requires both Keep Web and standard Keep Server API configured in order to use Keep-Web functionalities.
+
+h3. Integration tests
+
+In order to run integration tests all fields within following configuration file must be provided:
+
+<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.
+
+Integration tests require connection to 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.
+
+h3. Javadoc
+
+See "Javadoc":javadoc.html
diff --git a/doc/sdk/java-v2/javadoc.html.textile.liquid b/doc/sdk/java-v2/javadoc.html.textile.liquid
new file mode 100644
index 000000000..872150f62
--- /dev/null
+++ b/doc/sdk/java-v2/javadoc.html.textile.liquid
@@ -0,0 +1,15 @@
+---
+layout: default
+navsection: sdk
+navmenu: Java v2
+title: "Javadoc Reference"
+
+no_nav_left: true
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+notextile. <iframe src="javadoc/index.html" style="width:100%; height:100%; border:none" />
diff --git a/doc/sdk/java/index.html.textile.liquid b/doc/sdk/java/index.html.textile.liquid
index 6099d7f86..111c0631d 100644
--- a/doc/sdk/java/index.html.textile.liquid
+++ b/doc/sdk/java/index.html.textile.liquid
@@ -1,7 +1,7 @@
---
layout: default
navsection: sdk
-navmenu: Java
+navmenu: Java SDK v1
title: "Installation"
...
{% comment %}
@@ -10,7 +10,7 @@ Copyright (C) The Arvados Authors. All rights reserved.
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-The Java SDK provides a generic set of wrappers so you can make API calls in java.
+The Java SDK v1 provides a low level API to call Arvados from Java.
h3. Introdution
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list