X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/22ae07f51e144baa27ddc56d56a8c6ac6f63ad58..479e9a2511d9b54f1631de33027f6cdb4c576128:/README.md diff --git a/README.md b/README.md index ca5aef91c1..5843bb84da 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,81 @@ -``` -Copyright (C) The Arvados Authors. All rights reserved. - -SPDX-License-Identifier: CC-BY-SA-3.0 -``` - -# Arvados Java SDK - -##### About -Arvados Java Client allows to access Arvados servers and uses two APIs: -* lower level [Keep Server API](https://doc.arvados.org/api/index.html) -* higher level [Keep-Web API](https://godoc.org/github.com/curoverse/arvados/services/keep-web) (when needed) - -##### Required Java version -This SDK requires Java 8+ - -##### Logging +[comment]: # (Copyright © The Arvados Authors. All rights reserved.) +[comment]: # () +[comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0) -SLF4J is used for logging. Concrete logging framework and configuration must be provided by a client. +[Arvados](https://arvados.org) is a free software distributed computing platform +for bioinformatics, data science, and high throughput analysis of massive data +sets. Arvados supports a variety of cloud, cluster and HPC environments. -##### Configuration +Arvados consists of: -[TypeSafe Configuration](https://github.com/lightbend/config) is used for configuring this library. +* *Keep*: a petabyte-scale content-addressed distributed storage system for managing and + storing collections of files, accessible via HTTP and FUSE mount. -Please, have a look at java/resources/reference.conf for default values provided with this library. +* *Crunch*: a Docker-based cluster and HPC workflow engine designed providing + strong versioning, reproducibilty, and provenance of computations. -* **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) +* Related services and components including a web workbench for managing files + and compute jobs, REST APIs, SDKs, and other tools. -In order to override default settings one can create application.conf file in an application. -Example: src/test/resources/application.conf. +## Quick start -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. +Veritas Genetics maintains a public installation of Arvados for evaluation and trial use, the [Arvados Playground](https://playground.arvados.org). A Google account is required to log in. -ArvadosFacade has two constructors, one without arguments that uses values from reference.conf and second one -taking ExternalConfigProvider as an argument. +To try out Arvados on your local workstation, you can use Arvbox, which +provides Arvados components pre-installed in a Docker container (requires +Docker 1.9+). After cloning the Arvados git repository: -##### API clients +``` +$ cd arvados/tools/arvbox/bin +$ ./arvbox start localdemo +``` -All API clients inherit from BaseStandardApiClient. This class contains implementation of all -common methods as described in http://doc.arvados.org/api/methods.html. +In this mode you will only be able to connect to Arvbox from the same host. To +configure Arvbox to be accessible over a network and for other options see +http://doc.arvados.org/install/arvbox.html for details. -Parameters provided to common or specific methods are String UUID or fields wrapped in Java objects. For example: +## Documentation -```java -String uuid = "ardev-4zz18-rxcql7qwyakg1r1"; +Complete documentation, including a User Guide, Installation documentation and +API documentation is available at http://doc.arvados.org/ -Collection actual = client.get(uuid); -``` +If you wish to build the Arvados documentation from a local git clone, see +doc/README.textile for instructions. -```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(); +## Community -CollectionList actual = client.list(listArgument); -``` +[![Join the chat at https://gitter.im/curoverse/arvados](https://badges.gitter.im/curoverse/arvados.svg)](https://gitter.im/curoverse/arvados?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -Non-standard API clients must inherit from BaseApiClient. -For example: KeepServerApiClient communicates directly with Keep servers using exclusively non-common methods. +The [curoverse/arvados channel](https://gitter.im/curoverse/arvados) +channel at [gitter.im](https://gitter.im) is available for live +discussion and support. -##### Business logic +The +[Arvados user mailing list](http://lists.arvados.org/mailman/listinfo/arvados) +is a forum for general discussion, questions, and news about Arvados +development. The +[Arvados developer mailing list](http://lists.arvados.org/mailman/listinfo/arvados-dev) +is a forum for more technical discussion, intended for developers and +contributors to Arvados. -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** +## Development -##### Note regarding Keep-Web +[![Build Status](https://ci.curoverse.com/buildStatus/icon?job=run-tests)](https://ci.curoverse.com/job/run-tests/) +[![Go Report Card](https://goreportcard.com/badge/github.com/curoverse/arvados)](https://goreportcard.com/report/github.com/curoverse/arvados) -Current version requires both Keep Web and standard Keep Server API configured in order to use Keep-Web functionalities. +The Arvados public bug tracker is located at https://dev.arvados.org/projects/arvados/issues -##### Integration tests +Continuous integration is hosted at https://ci.curoverse.com/ -In order to run integration tests all fields within following configuration file must be provided: -```java -src/test/resources/integration-test-appliation.conf -``` -Parameter **integration-tests.project-uuid** should contain UUID of one project available to user, -whose token was provided within configuration file. +Instructions for setting up a development environment and working on specific +components can be found on the +["Hacking Arvados" page of the Arvados wiki](https://dev.arvados.org/projects/arvados/wiki/Hacking). -Integration tests require connection to real Arvados server. +## Contributing -##### Note regarding file naming +When making a pull request, please ensure *every git commit message* includes a one-line [Developer Certificate of Origin](https://dev.arvados.org/projects/arvados/wiki/Developer_Certificate_Of_Origin). If you have already made commits without it, fix them with `git commit --amend` or `git rebase`. -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. +## Licensing +Arvados is Free Software. See COPYING for information about Arvados Free +Software licenses.