com.basho.riak.client

Interface IRiakClient

All Known Implementing Classes:

DefaultRiakClient

public interface IRiakClient

Primary high-level interface for accessing Riak.

Used to create/fetch/update Buckets and to perform Map/Reduce query operations.

For example:

 IRiakClient client = RiakFactory.pbcClient();
 final byte[] id = client.generateAndSetClientId()
 Bucket b = client.createBucket("myNewBucket")
                      .nVal(3)
                      .allowSiblings(true)
                  .execute();
                  
 // do things with the bucket
 

Author:

russell

See Also:

Bucket, MapReduce

Method Summary

Methods

Modifier and Type	Method and Description
WriteBucket	createBucket(String bucketName) Create a new WriteBucket operation to create a Bucket named for the passed String.
FetchBucket	fetchBucket(String bucketName) Create a new FetchBucket operation, and return it.
byte[]	generateAndSetClientId() Generate, set and return "random" byte[4] id for the client.
byte[]	getClientId() Retrieve the client id from Riak that this client is using.
Transport	getTransport() Optional method, the underlying transport.
Set<String>	listBuckets() Deprecated.
StreamingOperation<String>	listBucketsStreaming() Iterate over the bucket names in Riak.
BucketKeyMapReduce	mapReduce() Create MapReduce operation for a set of bucket/key inputs.
IndexMapReduce	mapReduce(IndexQuery query) Create a MapReduce operation that uses the supplied IndexQuery as input
BucketMapReduce	mapReduce(String bucket) Create MapReduce operation that has the supplied bucket as its input.
SearchMapReduce	mapReduce(String bucket, String query) Create a MapReduce operation that uses the supplied Riak Search query as input.
void	ping() Ping Riak, check it is available
void	resetBucket(String bucketName) Reset a bucket's properties back to the defaults
IRiakClient	setClientId(byte[] clientId) Set an ID for this client.
void	shutdown()
Iterable<NodeStats>	stats() Perform the Riak /stats operation on the node(s) this client is connected to.
WriteBucket	updateBucket(Bucket bucket) Create a new WriteBucket operation to update passed bucket.
LinkWalk	walk(IRiakObject startObject) Create a LinkWalk operation that starts at startObject.

Method Detail

setClientId

IRiakClient setClientId(byte[] clientId)
                        throws RiakException

Set an ID for this client. All requests should include a client id, which can be any 4 bytes that uniquely identify the client, for purposes of tracing object modifications in the vclock. Note: this is 2 calls to Riak.

Parameters:

clientId - byte[4] that uniquely identify the client

Returns:

this

Throws:

RiakException - if operation fails

IllegalArgumentException - if clientId is null or not byte[4]

generateAndSetClientId

byte[] generateAndSetClientId()
                              throws RiakException

Generate, set and return "random" byte[4] id for the client. Note: this is a call to Riak.

Returns:

a byte[4] id for this client.

Throws:

RiakException

See Also:

ClientId

getClientId

byte[] getClientId()
                   throws RiakException

Retrieve the client id from Riak that this client is using. Note: this is a call to Riak.

Returns:

a byte[4] that Riak uses to identify this client.

Throws:

RiakException

listBuckets

Set<String> listBuckets()
                        throws RiakException

Deprecated.

Set view of buckets in Riak

Returns:

a Set of buckets (or empty)

Throws:

RiakException

listBucketsStreaming

StreamingOperation<String> listBucketsStreaming()
                                                throws RiakException

Iterate over the bucket names in Riak. This is a streaming operation. This is only available in Riak 1.4 and later You *must* call StreamingOperation.cancel() on the returned StreamingOperation if you do not iterate through the entire set. As a safeguard the stream is closed automatically when the iterator is weakly reachable but due to the nature of the GC it is inadvisable to rely on this to close the iterator. Do not retain a reference to this Iterable after you have used it.

Throws:

RiakException

See Also:

RawClient.listBucketsStreaming()

fetchBucket

FetchBucket fetchBucket(String bucketName)

Create a new FetchBucket operation, and return it.

Parameters:

bucketName -

Returns:

a FetchBucket configured to return the Bucket called bucketName for further configuration and execution.

See Also:

FetchBucket

updateBucket

WriteBucket updateBucket(Bucket bucket)

Create a new WriteBucket operation to update passed bucket.

Parameters:

bucket - the name of the Bucket.

Returns:

a WriteBucket configured to update the supplied bucket for further configuration and execution.

See Also:

WriteBucket

createBucket

WriteBucket createBucket(String bucketName)

Create a new WriteBucket operation to create a Bucket named for the passed String.

Parameters:

bucketName - the name of the new bucket.

Returns:

a WriteBucket configured to create the new bucket for further configuration and execution.

See Also:

WriteBucket

resetBucket

void resetBucket(String bucketName)
                 throws RiakException

Reset a bucket's properties back to the defaults

Parameters:

bucketName -

Throws:

RiakException

walk

LinkWalk walk(IRiakObject startObject)

Create a LinkWalk operation that starts at startObject. See also Link Walking on the basho site.

Parameters:

startObject - the IRiakObject to start the Link walk from.

Returns:

a LinkWalk operation for further configuration and execution.

See Also:

LinkWalk

mapReduce

BucketKeyMapReduce mapReduce()

Create MapReduce operation for a set of bucket/key inputs. See also Map Reduce on the basho site.

Returns:

a BucketKeyMapReduce for configuration and execution.

See Also:

MapReduce, BucketKeyMapReduce

mapReduce

BucketMapReduce mapReduce(String bucket)

Create MapReduce operation that has the supplied bucket as its input.

Parameters:

bucket - the String name of the input bucket to the M/R job.

Returns:

a BucketMapReduce for further configuration and execution.

See Also:

MapReduce, BucketMapReduce

mapReduce

SearchMapReduce mapReduce(String bucket,
                        String query)

Create a MapReduce operation that uses the supplied Riak Search query as input. See also Riak Search on the basho wiki for more information.

Parameters:

bucket - the input bucket for the search query

query - the input query for the search

Returns:

a SearchMapReduce operation for further configuration and execution.

mapReduce

IndexMapReduce mapReduce(IndexQuery query)

Create a MapReduce operation that uses the supplied IndexQuery as input

Note: if you just want to fetch an index see Bucket.fetchIndex(com.basho.riak.client.query.indexes.RiakIndex) to create a FetchIndex operation

Parameters:

query - the IndexQuery to use as input

Returns:

a MapReduce operation for further configuration and execution

ping

void ping()
          throws RiakException

Ping Riak, check it is available

Throws:

RiakException - if Riak does not respond OK

getTransport

Transport getTransport()

Optional method, the underlying transport.

Returns:

a Transport or null if not implemented.

shutdown

void shutdown()

stats

Iterable<NodeStats> stats()
                          throws RiakException

Perform the Riak /stats operation on the node(s) this client is connected to.

This is not supported by the Riak Protobuf API

Returns:

an Iterable object that contains one or more NodeStats

Throws:

RiakException - If Riak does not respond or if the protobuf API is being used