X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/22ae07f51e144baa27ddc56d56a8c6ac6f63ad58..f42ee7c19b794e25db30051b1dfc4bee83929bcd:/README.md diff --git a/README.md b/README.md index ca5aef91c1..fced2eb5b7 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,96 @@ -``` -Copyright (C) The Arvados Authors. All rights reserved. - -SPDX-License-Identifier: CC-BY-SA-3.0 -``` +[comment]: # (Copyright © The Arvados Authors. All rights reserved.) +[comment]: # () +[comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0) -# Arvados Java SDK +[![Join the chat at https://gitter.im/arvados/community](https://badges.gitter.im/arvados/community.svg)](https://gitter.im/arvados/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) | [Installing Arvados](https://doc.arvados.org/install/index.html) | [Installing Client SDKs](https://doc.arvados.org/sdk/index.html) | [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) | [Development and Contributing](CONTRIBUTING.md) -##### 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+ +[Arvados](https://arvados.org) is an open source platform for +managing, processing, and sharing genomic and other large scientific +and biomedical data. With Arvados, bioinformaticians run and scale +compute-intensive workflows, developers create biomedical +applications, and IT administrators manage large compute and storage +resources. -##### Logging +The key components of Arvados are: -SLF4J is used for logging. Concrete logging framework and configuration must be provided by a client. +* *Keep*: Keep is the Arvados storage system for managing and storing large +collections of files. Keep combines content addressing and a +distributed storage architecture resulting in both high reliability +and high throughput. Every file stored in Keep can be accurately +verified every time it is retrieved. Keep supports the creation of +collections as a flexible way to define data sets without having to +re-organize or needlessly copy data. Keep works on a wide range of +underlying filesystems and object stores. -##### Configuration +* *Crunch*: Crunch is the orchestration system for running [Common Workflow Language](https://www.commonwl.org) workflows. It is +designed to maintain data provenance and workflow +reproducibility. Crunch automatically tracks data inputs and outputs +through Keep and executes workflow processes in Docker containers. In +a cloud environment, Crunch optimizes costs by scaling compute on demand. -[TypeSafe Configuration](https://github.com/lightbend/config) is used for configuring this library. +* *Workbench*: The Workbench web application allows users to interactively access +Arvados functionality. It is especially helpful for querying and +browsing data, visualizing provenance, and tracking the progress of +workflows. -Please, have a look at java/resources/reference.conf for default values provided with this library. +* *Command Line tools*: The command line interface (CLI) provides convenient access to Arvados +functionality in the Arvados platform from the command line. -* **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) +* *API and SDKs*: Arvados is designed to be integrated with existing infrastructure. All +the services in Arvados are accessed through a RESTful API. SDKs are +available for Python, Go, R, Perl, Ruby, and Java. -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. +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: -ArvadosFacade has two constructors, one without arguments that uses values from reference.conf and second one -taking ExternalConfigProvider as an argument. - -##### 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 the [User Guide](https://doc.arvados.org/user/index.html), [Installation documentation](https://doc.arvados.org/install/index.html), [Administrator documentation](https://doc.arvados.org/admin/index.html) and +[API documentation](https://doc.arvados.org/api/index.html) 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](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/arvados/community](https://badges.gitter.im/arvados/community.svg)](https://gitter.im/arvados/community?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 [Arvados community channel](https://gitter.im/arvados/community) +channel at [gitter.im](https://gitter.im) is available for live +discussion and support. -##### Business logic +The [Arvados developement channel](https://gitter.im/arvados/development) +channel at [gitter.im](https://gitter.im) is used to coordinate development. -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** +The [Arvados user mailing list](http://lists.arvados.org/mailman/listinfo/arvados) +is used to announce new versions and other news. -##### Note regarding Keep-Web +All participants are expected to abide by the [Arvados Code of Conduct](CODE_OF_CONDUCT.md). -Current version requires both Keep Web and standard Keep Server API configured in order to use Keep-Web functionalities. +# Reporting bugs -##### Integration tests +[Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org). -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. +# Development and Contributing -Integration tests require connection to real Arvados server. +See [CONTRIBUTING](CONTRIBUTING.md) for information about Arvados development and how to contribute to the Arvados project. -##### Note regarding file naming +The [development road map](https://dev.arvados.org/issues/gantt?utf8=%E2%9C%93&set_filter=1&gantt=1&f%5B%5D=project_id&op%5Bproject_id%5D=%3D&v%5Bproject_id%5D%5B%5D=49&f%5B%5D=&zoom=1) outlines some of the project priorities over the next twelve months. -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](COPYING) for information about the open source licenses used in Arvados.