Skip to content
Riak's Java client
Java Makefile
Find file

README.md

Riak Java Client

The Riak Java Client enables communication with Riak, an open source, distributed database that focuses on high availability, horizontal scalability, and predictable latency. Both Riak and this code are maintained by Basho.

  1. Installation
  2. Documentation
  3. Contributing
  4. Roadmap
  5. License and Authors
  6. 2.0 Overview

Installation

This branch of the Riak Java Client is for the new v2.0 client, to be used with Riak 2.0.

Previous versions:

riak-client-1.4.4 - For use with Riak 1.4.x

riak-client-1.1.4 - For use with < Riak 1.4.0

This client is published to Maven Central and can be included in your project by adding:

<dependencies>
  <dependency>
    <groupId>com.basho.riak</groupId>
    <artifactId>riak-client</artifactId>
    <version>2.0.3</version>
  </dependency>
  ...
</dependencies>

All-in-one jar builds are available here for those that don't want to set up a maven project.

Documentation

  • Develop: Build Status

Most documentation is living in the wiki. For specifics on our progress here, see the release notes.

Also see the Javadoc site for more in-depth API docs.

Contributing

To build the Riak Java Client, you must have the correct version of the riak_pb dependency installed to your local Maven repository.

git clone https://github.com/basho/riak_pb
git checkout java-2.1.1.0
mvn clean install

This repository's maintainers are engineers at Basho and we welcome your contribution to the project! Review the details in CONTRIBUTING.md in order to give back to this project.

An honest disclaimer

Due to our obsession with stability and our rich ecosystem of users, community updates on this repo may take a little longer to review.

The most helpful way to contribute is by reporting your experience through issues. Issues may not be updated while we review internally, but they're still incredibly appreciated.

Thank you for being part of the community!

Roadmap

TODO

License and Authors

The Riak Java Client is Open Source software released under the Apache 2.0 License. Please see the LICENSE file for full license details.

Contributors

Thank you to all of our contributors! If your name is missing please let us know.

2.0 Overview

Version 2.0 of the Riak Java client is a completely new codebase. It relies on Netty4 in the core for handling network operations and all operations can be executed synchronously or asynchronously.

Getting started with the 2.0 client

The new client is designed to model a Riak cluster:

RJC model

The easiest way to get started with the client is using one of the static methods provided to instantiate and start the client:

RiakClient client = 
    RiakClient.newClient("192.168.1.1","192.168.1.2","192.168.1.3");

The RiakClient object is thread safe and may be shared across multiple threads.

For more complex configurations, you can instantiate a RiakCluster from the core packages and supply it to the RiakClient constructor.

RiakNode.Builder builder = new RiakNode.Builder();
builder.withMinConnections(10);
builder.withMaxConnections(50);

List<String> addresses = new LinkedList<String>();
addresses.add("192.168.1.1");
addresses.add("192.168.1.2");
addresses.add("192.168.1.3");

List<RiakNode> nodes = RiakNode.Builder.buildNodes(builder, addresses);
RiakCluster cluster = new RiakCluster.Builder(nodes).build();
cluster.start();
RiakClient client = new RiakClient(cluster)

Once you have a client, commands from the com.basho.riak.client.api.commands.* packages are built then executed by the client.

Some basic examples of building and executing these commands is shown below.

Getting Data In

Namespace ns = new Namespace("default", "my_bucket");
Location location = new Location(ns, "my_key");
RiakObject riakObject = new RiakObject();
riakObject.setValue(BinaryValue.create("my_value"));
StoreValue store = new StoreValue.Builder(riakObject)
  .withLocation(location)
  .withOption(Option.W, new Quorum(3)).build();
client.execute(store);

Getting Data Out

Namespace ns = new Namespace("default","my_bucket");
Location location = new Location(ns, "my_key");
FetchValue fv = new FetchValue.Builder(location).build();
FetchValue.Response response = client.execute(fv);
RiakObject obj = response.getValue(RiakObject.class);

Using 2.0 Data Types

A bucket type must be created (in all local and remote clusters) before 2.0 data types can be used. In the example below, it is assumed that the type "my_map_type" has been created and associated to the "my_map_bucket" prior to this code executing.

Once a bucket has been associated with a type, all values stored in that bucket must belong to that data type.

Namespace ns = new Namespace("my_map_type", "my_map_bucket");
Location location = new Location(ns, "my_key");
RegisterUpdate ru1 = new RegisterUpdate(BinaryValue.create("map_value_1"));
RegisterUpdate ru2 = new RegisterUpdate(BinaryValue.create("map_value_2"));
MapUpdate mu = new MapUpdate();
mu.update("map_key_1", ru1);
mu.update("map_key_2", ru2);
UpdateMap update = new UpdateMap.Builder(location, mu).build();
client.execute(update);

RiakCommand Subclasses

Fetching, storing and deleting objects

Listing keys in a namespace

Secondary index (2i) commands

Fetching and storing datatypes (CRDTs)

Querying and modifying buckets

Search commands

Map-Reduce

Something went wrong with that request. Please try again.