Orchestrate Java Client

A high performance, asynchronous Java client to query the Orchestrate.io service.

About

The Orchestrate.io service is a platform for storing and querying data.

Using Orchestrate you can focus on building applications and adding new features while we handle safely storing the data, providing a large variety of ways to query the data and keeping the service highly available to support your applications as they grow.

You can create an account by signing up at the Dashboard.

### Getting Started

The client library is available on Maven Central.

Using Gradle

dependencies {
    compile group: 'io.orchestrate', name: 'orchestrate-client', version: '0.1.0'
}

Using Maven

<dependency>
    <groupId>io.orchestrate</groupId>
    <artifactId>orchestrate-client</artifactId>
    <version>0.1.0</version>
</dependency>

Example

The client API is designed around the concept of operations you can execute on the Orchestrate.io service. The client library is entirely asynchronous and conforms to the java.util.concurrent.Future specification in the standard library.

#### Creating a Client

You construct a client using the API key for your Application which can be found in the Dashboard (for help, see here).

// An API key looks something like:
//   3854bbd7-0a31-43b0-aa94-66236847a717
Client client = new Client("your api key");

Fetching Key-Value Data

For example, to fetch an object from a collection with a given key.

KvFetchOperation<MyObj> kvFetchOp =
    new KvFetchOperation<MyObj>("myCollection", "someKey", MyObj.class);

// execute the operation
Future<KvObject<MyObj>> future = client.execute(kvFetchOp);

// wait for the result
KvObject<MyObj> kvObject = future.get(3, TimeUnit.SECONDS);

// check the data exists
if (kvObject == null) {
    System.out.println("'someKey' does not exist.");
} else {
    MyObj data = kvObject.getValue();
    // do something with the 'data'
}

The client has operations for Key-Value, Search, Graph and Event features from the Orchestrate.io service.

User Guide

There's a User Guide for the client with more code examples and details on tuning the library for your server environment.

The Javadocs for the codebase are available here.

Note

The client API is still in flux, we're looking for feedback from developers and designing what you need to build incredible applications.

Developer notes

The client uses the Grizzly framework for processing HTTP requests and Jackson JSON parser for marshalling data to and from the Orchestrate.io service.

The codebase requires the Gradle build tool at version 1.6+ and the Java compiler at version 1.6.0 or greater.

Building the codebase

A list of all possible build targets can be displayed by Gradle with gradle tasks.

In a regular write-compile-test cycle use gradle test.

It is recommended to run Gradle with the Build Daemon enabled to improve performance. e.g. gradle --daemon once the daemon is running it can be stopped with gradle --stop.

Running Integration Tests

To run integration tests you'll need to create an application in the Orchestrate Dashboard, then put the API key into the gradle.properties as the value for the property orchestrate.apiKey.

Once you've configured the build system with an API key, it will create the oio-client-integration-tests collection when you run integration tests with gradle integTest.

Building the documentation

The documentation sources for the User Manual is in the www folder.

The documentation can be built with Middleman. To run the local server for viewing use middleman server and to build compiled code for deployment use middleman build.

Contribute

All contributions to the documentation and the codebase are very welcome and feel free to open issues on the tracker wherever the documentation needs improving.

Lastly, pull requests are always welcome! :)