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 , Alex Moore , Sergey Galkin

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	cleanup() Cleans up any Thread-Local variables after shutdown.
static RiakNode.Builder	createDefaultNodeBuilder()
<T,S> T	execute(RiakCommand<T,S> command) Execute a RiakCommand synchronously.
<T,S> T	execute(RiakCommand<T,S> command, long timeout, TimeUnit unit) Execute a RiakCommand synchronously with a specified client timeout.
<T,S> RiakFuture<T,S>	executeAsync(RiakCommand<T,S> command) Execute a RiakCommand asynchronously.
<I extends StreamableRiakCommand.StreamableResponse,S> RiakFuture<I,S>	executeAsyncStreaming(StreamableRiakCommand<I,S,?,?> command, int timeoutMS) Execute a StreamableRiakCommand asynchronously, and stream the results back before the command is done.
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(Collection<HostAndPort> hosts) Static factory method to create a new client instance.
static RiakClient	newClient(Collection<HostAndPort> hosts, RiakNode.Builder nodeBuilder) 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(RiakNode.Builder nodeBuilder, List<String> addresses) Static factory method to create a new client instance.
static RiakClient	newClient(RiakNode.Builder nodeBuilder, String... addresses) 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.

newClient

public static RiakClient newClient(RiakNode.Builder nodeBuilder,
                                   List<String> addresses)
                            throws UnknownHostException

Static factory method to create a new client instance. This method produces a client connected to the supplied addresses and containing the RiakNodes that will be build by using provided builder.

Parameters:

addresses - one or more addresses to connect to.

Returns:

a new RiakClient instance.

Throws:

UnknownHostException - if a supplied hostname cannot be resolved.

Since:

2.0.3

See Also:

RiakCluster.Builder.RiakCluster.Builder(RiakNode.Builder, List)

newClient

public static RiakClient newClient(RiakNode.Builder nodeBuilder,
                                   String... addresses)
                            throws UnknownHostException

Static factory method to create a new client instance.

Throws:

UnknownHostException

Since:

2.0.3

See Also:

newClient(RiakNode.Builder, List)

newClient

public static RiakClient newClient(Collection<HostAndPort> hosts)
                            throws UnknownHostException

Static factory method to create a new client instance.

Throws:

UnknownHostException

Since:

2.0.6

newClient

public static RiakClient newClient(Collection<HostAndPort> hosts,
                                   RiakNode.Builder nodeBuilder)
                            throws UnknownHostException

Static factory method to create a new client instance.

Throws:

UnknownHostException

Since:

2.0.6

createDefaultNodeBuilder

public static RiakNode.Builder createDefaultNodeBuilder()

Since:

2.0.3

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

execute

public <T,S> T execute(RiakCommand<T,S> command,
                       long timeout,
                       TimeUnit unit)
                throws ExecutionException,
                       InterruptedException,
                       TimeoutException

Execute a RiakCommand synchronously with a specified client timeout.

Calling this method causes the client to execute the provided RiakCommand synchronously. It will block until the operation completes or up to the given timeout. It will either return the response on success or throw an exception on failure. Note: Using this timeout is different that setting a timeout on the command itself using the timeout() method of the command's associated builder. The command timeout is a Riak-side timeout value. This timeout is client-side.

Type Parameters:

T - The RiakCommand's return type.

S - The RiakCommand's query info type.

Parameters:

command - The RiakCommand to execute.

timeout - the amount of time to wait before returning an exception

unit - the unit of time.

Returns:

a response from Riak.

Throws:

ExecutionException - if the command fails for any reason.

InterruptedException

TimeoutException - if the call to execute the command did not finish within the time limit

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

executeAsyncStreaming

public <I extends StreamableRiakCommand.StreamableResponse,S> RiakFuture<I,S> executeAsyncStreaming(StreamableRiakCommand<I,S,?,?> command,
                                                                                                    int timeoutMS)

Execute a StreamableRiakCommand asynchronously, and stream the results back before the command is done.

Calling this method causes the client to execute the provided StreamableRiakCommand asynchronously. It will immediately return a RiakFuture that contains an immediately available result (via RiakFuture.get()) that data will be streamed to. The RiakFuture will also keep track of the overall operation's progress with the RiakFuture.isDone(), etc methods.

Because the consumer thread will poll for new results, it is advisable to check the consumer thread's interrupted status via Thread.currentThread().isInterrupted() , as the result iterator will not propagate an InterruptedException, but it will set the Thread's interrupted flag.

Type Parameters:

I - StreamableRiakCommand's immediate return type, available before the command/operation is complete.

S - The RiakCommand's query info type.

Parameters:

command - The RiakCommand to execute.

timeoutMS - The polling timeout in milliseconds for each result chunk. If the timeout is reached it will try again, instead of blocking indefinitely. If the value is too small (less than the average chunk arrival time), the result iterator will essentially busy wait. If the timeout is too large (much greater than the average chunk arrival time), the result iterator can block the consuming thread from seeing the done() status until the timeout is reached.

Returns:

a RiakFuture for the operation

Since:

2.1.0

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.

cleanup

public void cleanup()

Cleans up any Thread-Local variables after shutdown. This operation is useful when you are in a container environment, and you do not want to leave the thread local variables in the threads you do not manage. Call this method when your application is being unloaded from the container, after all RiakNode, RiakCluster, and RiakClient objects are in the shutdown state.