• Stars
    star
    264
  • Rank 155,103 (Top 4 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created over 14 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The Riak client for Java.

Riak Java Client

Maven Central

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.

The latest version of the Java client supports both Riak KV 2.0+, and Riak TS 1.0+. Please see the Release Notes for more information on specific feature and version support.

  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.7</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

Integration Tests Setup

We've included Basho's riak-client-tools as a git submodule to help with Riak test setup and teardown. You can find these tools in the /tools subdirectory.

To configure your single riak instance, you may use the setup-riak script to setup the node with the appropriate bucket types. You can use it by running ./tools/setup-riak.

To configure a devrel for multiple node testing, please see the instructions located at basho/riak-client-tools on how to use the ./tools/setup-riak command with your devrel.

Running Integration Tests

To run the Riak KV integration test suite, execute:

make RIAK_PORT=8087 integration-test

To run the Riak TimeSeries test suite, execute:

make RIAK_PORT=8087 integration-test-timeseries

When running tests directly from Maven, you may also turn feature sets on and off with system properties:

mvn -Pitest,default -Dcom.basho.riak.timeseries=true -Dcom.basho.riak.pbcport=$(RIAK_PORT) verify

The supported test flags are:

System Property Default Value Note
com.basho.riak.buckettype true Riak KV 2.0 Bucket Type Tests
com.basho.riak.yokozuna true Riak KV 2.0 Solr/Yokozuna Search Tests
com.basho.riak.2i true Riak KV Secondary Index Tests
com.basho.riak.mr true Riak KV MapReduce Tests
com.basho.riak.crdt true Riak KV 2.0 Data Type Tests
com.basho.riak.lifecycle true Java Client Node/Cluster Lifecycle Tests
com.basho.riak.timeseries false Riak TS TimeSeries Tests
com.basho.riak.riakSearch false Riak KV 1.0 Legacy Search Tests
com.basho.riak.coveragePlan false Riak KV/TS Coverage Plan Tests
(need cluster to run these )
com.basho.riak.security false Riak Security Tests
com.basho.riak.clientcert false Riak Security Tests with Certificates

To run the HyperLogLog or GSet Data Type tests, you must have two test bucket types setup as following:

riak-admin bucket-type create gsets '{"props":{"allow_mult":true, "datatype": "gset"}}'
riak-admin bucket-type create hlls '{"props":{"allow_mult":true, "datatype": "hll"}}'
riak-admin bucket-type activate gsets
riak-admin bucket-type activate hlls

Some tests may require more than one feature to run, so please check the test to see which ones are required before running.

Connection Options

System Property Default Value Note
com.basho.riak.host 127.0.0.1 The hostname to connect to for tests
com.basho.riak.pbcport 8087 The Protocol Buffers port to connect to for tests

Security tests

To run the security-related integration tests, you will need to:

  1. Setup the certs by running the buildbot makefile's configure-security-certs target.
cd buildbot;
make configure-security-certs;
cd ../;
  1. Copy the certs to your Riak's etc dir, and configure the riak.conf file to use them.
resources_dir=./src/test/resources
riak_etc_dir=/fill/in/this/path/

# Shell
cp $resources_dir/cacert.pem $riak_etc_dir
cp $resources_dir/riak-test-cert.pem $riak_etc_dir
cp $resources_dir/riakuser-client-cert.pem $riak_etc_dir

# riak.conf file additions
ssl.certfile = (riak_etc_dir)/cert.pem
ssl.keyfile = (riak_etc_dir)/key.pem
ssl.cacertfile = (riak_etc_dir)/cacert.pem
  1. Enable Riak Security.
riak-admin security enable
  1. Create a user "riakuser" with the password "riak_cert_user" and configure it with certificate as a source
riak-admin security add-user riakuser
riak-admin security add-source riakuser 0.0.0.0/0 certificate
  1. Create a user "riak_trust_user" with the password "riak_trust_user" and configure it with trust as a source.
riak-admin security add-user riak_trust_user password=riak_trust_user
riak-admin security add-source riak_trust_user 0.0.0.0/0 trust
  1. Create a user "riakpass" with the password "riak_passwd_user" and configure it with password as a source.
riak-admin security add-user riakpass password=Test1234
riak-admin security add-source riakpass 0.0.0.0/0 password
  1. Run integration-test-security target of the makefile.
make integration-test-security

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

More Repositories

1

riak

Riak is a decentralized datastore from Basho Technologies.
Shell
3,841
star
2

riak_core

Distributed systems infrastructure used by Riak.
Erlang
1,185
star
3

bitcask

because you need another a key/value storage engine
Erlang
1,179
star
4

rebar

ATTENTION: Please find the canonical repository here:
Erlang
1,070
star
5

riak_kv

Riak Key/Value Store
Erlang
633
star
6

riak_cs

Riak CS is simple, available cloud storage built on Riak.
Erlang
564
star
7

leveldb

Clone of http://code.google.com/p/leveldb/
C++
408
star
8

erlang_protobuffs

An implementation of Google's Protocol Buffers for Erlang, based on ngerakines/erlang_protobuffs.
Erlang
390
star
9

riak_dt

Convergent replicated datatypes in Erlang
Erlang
346
star
10

riak-python-client

The Riak client for Python.
Python
324
star
11

riak-erlang-client

The Riak client for Erlang.
Erlang
312
star
12

basho_bench

A load-generation and testing tool for basically whatever you can write a returning Erlang function for.
Erlang
310
star
13

eleveldb

Erlang LevelDB API
C++
266
star
14

yokozuna

Riak + Solr
Erlang
245
star
15

erlang_js

A linked-in driver for Erlang to Mozilla's Spidermonkey Javascript runtime.
Erlang
238
star
16

riak-ruby-client

The Riak client for Ruby.
Ruby
232
star
17

cuttlefish

never lose your childlike sense of wonder baby cuttlefish, promise me?
Erlang
205
star
18

basho_docs

Basho Products Documentation
SCSS
169
star
19

riak_ensemble

Multi-Paxos framework in Erlang
Erlang
166
star
20

riak-php-client

PHP clients for Riak
PHP
163
star
21

riak_pipe

Riak Pipelines
Erlang
162
star
22

clique

CLI Framework for Erlang
Erlang
147
star
23

riak_search

Full-text search engine based on Riak
Erlang
141
star
24

riak_control

Webmachine-based administration interface for Riak.
CSS
136
star
25

machi

Machi file store
Erlang
122
star
26

enm

Erlang driver for nanomsg
Erlang
120
star
27

sidejob

Parallel worker and capacity limiting library for Erlang
Erlang
104
star
28

riak-go-client

The Riak client for Go.
Go
91
star
29

node_package

RPM/Debian/FreeBSD/SmartOS/Solaris/OSX packaging templates for Erlang Nodes
Shell
90
star
30

merge_index

MergeIndex is an Erlang library for storing ordered sets on disk. It is very similar to an SSTable (in Google's Bigtable) or an HFile (in Hadoop).
Erlang
81
star
31

riak_function_contrib

Riak Function Contrib
Erlang
79
star
32

mochiweb

a branch of Mochi Media's excellent HTTP library -- their canonical source can be found at https://github.com/mochi/mochiweb
Erlang
78
star
33

riak-dotnet-client

The Riak client for .NET
C#
76
star
34

riak_sysmon

Simple OTP app for managing Erlang VM system_monitor event messages
Erlang
74
star
35

riak-nodejs-client

The Riak client for Node.js.
JavaScript
72
star
36

riak_pb

Riak Protocol Buffers Messages
Erlang
71
star
37

riak_test

I'm in your cluster, testing your riaks
Erlang
70
star
38

cluster_info

Fork of Hibari's nifty cluster_info OTP app
Erlang
63
star
39

ebloom

A NIF wrapper around a basic bloom filter.
C++
62
star
40

spark-riak-connector

The official Riak Spark Connector for Apache Spark with Riak TS and Riak KV
Scala
60
star
41

innertube

A thread-safe re-entrant resource pool for Ruby, extracted from the Riak Ruby Client.
Ruby
59
star
42

lager_syslog

Syslog backend for lager
Erlang
59
star
43

riaknostic

A diagnostic tool for Riak installations, to find common errors asap
Erlang
58
star
44

riaktant

A node.js sample app that stores syslog messages in Riak Search
JavaScript
56
star
45

riak_repl

Riak DC Replication
Erlang
55
star
46

giddyup

Visual scorecard for riak_test.
JavaScript
54
star
47

riak-erlang-http-client

Riak Erlang client using the HTTP interface
Erlang
48
star
48

riak_crdt_cookbook

A Cookbook full of Tutorials to get Developers started with Riak's CRDTs
Erlang
42
star
49

riak_err

Enhanced SASL Error Logger for Riak
Erlang
36
star
50

riak-hadoop

Riak data as input to hadoop m/r and output of hadoop m/r
Java
33
star
51

cloudformation-riak

Create Riak clusters with AWS CloudFormation
31
star
52

innostore

Innostore is a simple Erlang API to Embedded InnoDB.
C
31
star
53

riak_ql

SQL query language for Riak
Erlang
30
star
54

riak_api

Riak Client APIs
Erlang
27
star
55

luke

Dataflow / MapReduce coordination framework.
Erlang
22
star
56

taste-of-riak

Source code for all the taste of riak examples
C#
22
star
57

basho_metrics

Fast performance metrics for Erlang
C++
21
star
58

skerl

Skein hash function for Erlang, via NIFs
C
19
star
59

jam

Erlang time/date processing
Erlang
17
star
60

stanchion

Stanchion is an application to enforce the serialization of requests for Riak CS.
Erlang
16
star
61

dactyl

String templating library for Erlang
Erlang
16
star
62

faulterl

Erlang glue & control code for dynamic library-level fault injection
C++
15
star
63

tools.mk

A small makefile library for working with erlang tools
Makefile
14
star
64

nifwait

Utility to test effect of blocking NIFs on Erlang scheduler
Erlang
14
star
65

rebar_raw_resource

A rebar3 resource wrapper to accommodate non-OTP-app dependencies
Erlang
14
star
66

columbo

Columbo - the dependency detective - will highlight 3rd party dependency problems in your Erlang programs.
Erlang
14
star
67

canola

Simple PAM port driver for erlang
C
12
star
68

bashubot

Our own little hubot.
CoffeeScript
11
star
69

riak_cs_control

Webmachine-based administration interface for Riak CS.
Erlang
9
star
70

bench_shim

A Jinterface shim between basho_bench and riak-java-client
Java
9
star
71

riak_on_azure

Shell
8
star
72

basho-dtrace

DTrace scripts that Basho Team has found useful
D
8
star
73

riak-client-tools

Tools for Riak Client libraries
Shell
8
star
74

riak-nodejs-client-examples

Riak Node.js Client example code
JavaScript
8
star
75

stableboy

basho_harness VM / Harness provisioner
Erlang
7
star
76

riak_shell

A Repl for Riak
Erlang
7
star
77

riak-phppb-client

Official PHP Protocol Buffers Client for Riak
PHP
7
star
78

bashobot

A friendly little bot for the #riak IRC channel
Ruby
7
star
79

riak-zabbix

A set of tools and templates to help monitor Riak with the Zabbix monitoring tool.
ApacheConf
7
star
80

riak_cs_auth

Authentication schemes for Riak CS
Erlang
6
star
81

systest

Miscellaneous system test scripts
Erlang
6
star
82

recap-blog

[depreciated] The Riak Recap Blog
6
star
83

casbench

tools for benchmarking cassandra
Erlang
6
star
84

zdgrab

Zdgrab is a utility for downloading attachments to tickets from Zendesk.
Python
5
star
85

planet_riak

Riak Planet
Python
5
star
86

riak_cs_core

Core functionality for RIak CS
Erlang
5
star
87

data_platform

Basho Data Platform
Shell
5
star
88

data_platform_core

Basho Data Platform Core
Erlang
5
star
89

riak_auth_mods

Standard interface for security auth modules for Riak
Erlang
5
star
90

riak_cs_web

HTTP APIs for Riak Cloud Storage
Erlang
4
star
91

rfc

JavaScript
4
star
92

cluster_info_browser

In-browser app to easily flip through a cluster_info report
JavaScript
4
star
93

riak_ee-issues

Issue tracking for Riak Enterprise
3
star
94

riak_cs_lfs

Large file support for Riak CS
Erlang
3
star
95

ripple-encryption

Ruby
3
star
96

congruent

Generic test suite for Riak clients
Erlang
3
star
97

riak_cs_multibag

Riak CS Multi-cluster module
Erlang
3
star
98

riak_cs_acl

ACL support for Riak CS
Erlang
3
star
99

riak_cs_report

Reporting functionality for Riak CS
Erlang
3
star
100

velvet

Client library for Stanchion
Erlang
3
star