com.basho.riak.client.api

Class RiakClient

java.lang.Object

com.basho.riak.client.api.RiakClient

public class RiakClient
extends Object

The client used to perform operations on Riak.

The core of the Java client models a Riak cluster:

The easiest way to get started with the client API 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");  

Note that the Riak Java client uses the Riak Protocol Buffers API exclusively.

For more complex configurations you will instantiate one or more RiakNodes and build a RiakCluster to supply 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, RiakCommands from the com.basho.riak.client.api.commands.* packages are built then executed by the client:

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

You can also execute all RiakCommands asynchronously. A RiakFuture for the operation is immediately returned:

 Namespace ns = new Namespace("default","my_bucket");
 Location loc = new Location(ns, "my_key");
 FetchValue fv = new FetchValue.Builder(loc).build();
 RiakFuture<FetchValue.Response, Location> future = client.executeAsync(fv);
 future.await();
 if (future.isSuccess())
 {
     FetchValue.Response response = future.getNow();
     RiakObject obj = response.getValue(RiakObject.class);
     ...
 }
 else
 {
     Throwable error = future.cause();
     ...
 }

RiakCommand subclasses

Fetching, storing and deleting objects

• FetchValue
• MultiFetch
• StoreValue
• UpdateValue
• DeleteValue

Listing keys in a namespace

• ListKeys

Secondary index (2i) commands

• RawIndexQuery
• BinIndexQuery
• IntIndexQuery
• BigIntIndexQuery

Fetching and storing datatypes (CRDTs)

• FetchCounter
• FetchSet
• FetchMap
• UpdateCounter
• UpdateSet
• UpdateMap

Querying and modifying buckets

• FetchBucketProperties
• StoreBucketProperties
• ListBuckets

Search commands

• Search
• FetchIndex
• StoreIndex
• DeleteIndex
• FetchSchema
• StoreSchema

Map-Reduce

• BucketMapReduce
• BucketKeyMapReduce
• IndexMapReduce
• SearchMapReduce

Since:

2.0

Author:

Dave Rusek , Brian Roach

Constructor Summary

Constructors

Constructor and Description
RiakClient(RiakCluster cluster) Create a new RiakClient to perform operations on the given cluster.

Method Summary

Methods

Modifier and Type	Method and Description
<T,S> T	execute(RiakCommand<T,S> command) Execute a RiakCommand synchronously.
<T,S> RiakFuture<T,S>	executeAsync(RiakCommand<T,S> command) Execute a RiakCommand asynchronously.
RiakCluster	getRiakCluster() Get the RiakCluster being used by this client.
static RiakClient	newClient() Static factory method to create a new client instance.
static RiakClient	newClient(InetSocketAddress... addresses) Static factory method to create a new client instance.
static RiakClient	newClient(int port, List<String> remoteAddresses) Static factory method to create a new client instance.
static RiakClient	newClient(int port, String... remoteAddresses) Static factory method to create a new client instance.
static RiakClient	newClient(List<String> remoteAddresses) Static factory method to create a new client instance.
static RiakClient	newClient(String... remoteAddresses) Static factory method to create a new client instance.
Future<Boolean>	shutdown() Shut down the client and the underlying RiakCluster.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RiakClient

public RiakClient(RiakCluster cluster)

Create a new RiakClient to perform operations on the given cluster.

The RiakClient provides a user API on top of the client core. Once instantiated, commands are submitted to it for execution on Riak.

Parameters:

cluster - the started RiakCluster to use.

Method Detail

newClient

public static RiakClient newClient()
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client that connects to 127.0.0.1 on the default protocol buffers port (8087).

Returns:

a new client instance.

Throws:

UnknownHostException

newClient

public static RiakClient newClient(int port,
                   String... remoteAddresses)
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client connected to the supplied addresses on the supplied port.

Parameters:

remoteAddresses - a list of IP addresses or hostnames

port - the (protocol buffers) port to connect to on the supplied hosts.

Returns:

a new client instance

Throws:

UnknownHostException - if a supplied hostname cannot be resolved.

newClient

public static RiakClient newClient(List<String> remoteAddresses)
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client connected to the supplied addresses on the default (protocol buffers) port (8087).

Parameters:

remoteAddresses - a list of IP addresses or hostnames

Returns:

a new client instance

Throws:

UnknownHostException - if a supplied hostname cannot be resolved.

newClient

public static RiakClient newClient(String... remoteAddresses)
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client connected to the supplied addresses on the default (protocol buffers) port (8087).

Parameters:

remoteAddresses - a list of IP addresses or hostnames

Returns:

a new client instance

Throws:

UnknownHostException - if a supplied hostname cannot be resolved.

newClient

public static RiakClient newClient(int port,
                   List<String> remoteAddresses)
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client connected to the supplied addresses on the supplied port.

Parameters:

remoteAddresses - a list of IP addresses or hostnames

port - the (protocol buffers) port to connect to on the supplied hosts.

Returns:

a new client instance

Throws:

UnknownHostException - if a supplied hostname cannot be resolved.

newClient

public static RiakClient newClient(InetSocketAddress... addresses)
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client connected to the supplied addresses.

Parameters:

addresses - one or more addresses to connect to.

Returns:

a new RiakClient instance.

Throws:

UnknownHostException - if a supplied hostname cannot be resolved.

execute

public <T,S> T execute(RiakCommand<T,S> command)
          throws ExecutionException,
                 InterruptedException

Execute a RiakCommand synchronously.

Calling this method causes the client to execute the provided RiakCommand synchronously. It will block until the operation completes then either return the response on success or throw an exception on failure.

Type Parameters:

T - The RiakCommand's return type.

S - The RiakCommand's query info type.

Parameters:

command - The RiakCommand to execute.

Returns:

a response from Riak.

Throws:

ExecutionException - if the command fails for any reason.

InterruptedException

executeAsync

public <T,S> RiakFuture<T,S> executeAsync(RiakCommand<T,S> command)

Execute a RiakCommand asynchronously.

Calling this method causes the client to execute the provided RiakCommand asynchronously. It will immediately return a RiakFuture that contains the running operation.

Type Parameters:

T - RiakCommand's return type.

S - The RiakCommand's query info type.

Parameters:

command - The RiakCommand to execute.

Returns:

a RiakFuture for the operation.

See Also:

RiakFuture

shutdown

public Future<Boolean> shutdown()

Shut down the client and the underlying RiakCluster.

The underlying client core (RiakCluster) uses a number of threads as does Netty. Calling this method will shut down all those threads cleanly. Failure to do so may prevent your application from exiting.

Returns:

a future that will complete when shutdown

getRiakCluster

public RiakCluster getRiakCluster()

Get the RiakCluster being used by this client.

Allows for adding/removing nodes, etc.

Returns:

The RiakCluster instance being used by this client.