https://github.com/open-io/oio-api-java
OpenIO SDS Java client API, giving direct access to the object storage
https://github.com/open-io/oio-api-java
java object-storage openio openio-sds openio-sds-api
Last synced: 5 months ago
JSON representation
OpenIO SDS Java client API, giving direct access to the object storage
- Host: GitHub
- URL: https://github.com/open-io/oio-api-java
- Owner: open-io
- License: lgpl-3.0
- Created: 2016-02-05T22:04:40.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-05-19T06:14:40.000Z (about 6 years ago)
- Last Synced: 2023-07-28T18:20:15.202Z (almost 3 years ago)
- Topics: java, object-storage, openio, openio-sds, openio-sds-api
- Language: Java
- Homepage: https://www.openio.io/
- Size: 524 KB
- Stars: 8
- Watchers: 23
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
OpenIO SDS API
==============
OpenIO SDS API is a java remote API for [OpenIO Software Defined Storage](https://github.com/open-io/oio-sds). It is designed
to be as simple and fast as possible.
[![Build Status][build_status_svg]][repo] [![Codecov][codecov_svg]][codecov]
-------------
### Getting started
------------
###### OioUrl object
Each methods of the api will ask you for an OioUrl instance. This class simplify methods signatures and make code cleaner.
You will build it simply by calling OioUrl#url(String, String) for container url, i.e. to perform operations on container,
and by calling OioUrl#url(String, String, String) for object url.
The first parameter is called "ACCOUNT". It define a storage space inside your SDS namespace. It could be used
for a dedicated application space for example. If you don't care about that, just choose an account name and keep the same all the time.
The second parameter is the container name. It is the space in which your future objects will be created directly.
Its name is unique by account.
And the last parameter is the object name, which is the identifier of your object inside a container, so, like container in account,
an object name is unique inside a container.
Container url example:
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME");
Object url example:
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME", "MY_OBJECT_NAME");
------------
### Storage client usage
------------
OpenIO SDS API entry point is the Client implementations classes. Instances of these implementations
are built with ClientBuilder class. You could create a basic client by calling
ClientBuilder#newClient(String, String)} method, specifying the OpenIO namespace and proxyd
service url as argument. If you don't know what is proxyd service, please refer to OpenIO SDS documentation [here](https://github.com/open-io/oio-sds/wiki/OpenIO-SDS-Proxy).
Clients built from ClientBuilder are ready to be used. Let's see some basics examples.
###### Basic client instantiation
Client client = ClientBuilder.newClient("OPENIO", "http://127.0.0.1:6002");
###### Advanced client configuration
Settings settings = new Settings();
settings.proxy()
.ns("OPENIO")
.url("http://127.0.0.1:6002")
.ecd("http://127.0.0.1:5000"); //setup an ecd url for Erasure cogin management
client = ClientBuilder.newClient(settings);
###### Container creation example
As simple as it could be:
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME");
client.createContainer(url);
###### Upload an object from an InputStream
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME", "MY_OBJECT_NAME");
File file = new File("MY_SAMPLE_FILE.txt");
FileInputStream fis = new FileInputStream(file);
client.putObject(url, 1024L, fis);
###### Retrieve and download an object
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME", "MY_OBJECT_NAME");
ObjectInfo oinf = client.getObjectInfo(url);
InputStream data = client.downloadObject(oinf);
###### List objects inside a container
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME");
ObjectList list = client.listContainer(url, new ListOptions());
###### Delete a content
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME", "MY_OBJECT_NAME");
client.deleteObject(url);
###### Delete a container
An empty container (it should be explicitly empty) could be deleted from your SDS namespace, as follow.
OioUrl url = OioUrl.url("MY_ACCOUNT", "MY_CONTAINER_NAME");
client.deleteContainer(url);
------------
### Exception management
------------
OpenIO choose to make all possible exceptions as RuntimeException extensions. By this way, we allow cleaner code
when you decide to not check exceptions because you can't deal with unexpected behaviour (IOException etc...).
So our client throws only OioException : OioSystemException which indicates server error (connection issues, hardware issues,...),
and others OioException extension for all use case errors. See io.openio.sds.exceptions package for exceptions detail.
Usage exceptions are detailed just below
| Name | Description |
| --------------------------------- | -------------------------------------------------- |
| AccountNotFoundException | The account you try to deal with does not exist |
| BadRequestException | Some parameter is wrong in your request |
| ContainerExistException | The container you try to create is already created |
| ContainerNotFoundException | The container you want to reach does not exist |
| ObjectExistException | The object you try to created is alreay created |
| ObjectNotFoundException | The object you try to reach does not exist |
| OioException | Main OpenIO exception class |
| OioSystemException | A system error occurred during your request |
| ReferenceAlreadyExistException | The reference you try to create is alreayd created |
| ReferenceNotFoundException | the reference you try to reach does not exist |
------------
Contributing
------------
This project was originally indented with tabulations but should from now on
be indented with 4 spaces.
[build_status_svg]: https://travis-ci.org/open-io/oio-api-java.svg?branch=master
[repo]: https://travis-ci.org/open-io/oio-api-java
[codecov_svg]: https://codecov.io/gh/open-io/oio-api-java/branch/master/graph/badge.svg
[codecov]: https://codecov.io/gh/open-io/oio-api-java