com.basho.riak.client.api.RiakClient Maven / Gradle / Ivy
Show all versions of riak-client Show documentation
/*
* Copyright 2013 Basho Technologies Inc
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.basho.riak.client.api;
import com.basho.riak.client.core.RiakCluster;
import com.basho.riak.client.core.RiakFuture;
import com.basho.riak.client.core.RiakNode;
import java.net.InetSocketAddress;
import java.net.UnknownHostException;
import java.util.Arrays;
import java.util.LinkedList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
/**
*
* 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:
*
*
* {@code
* 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 {@link com.basho.riak.client.core.RiakNode}s
* and build a {@link com.basho.riak.client.core.RiakCluster} to supply to the
* RiakClient constructor.
*
*
* {@code
* RiakNode.Builder builder = new RiakNode.Builder();
* builder.withMinConnections(10);
* builder.withMaxConnections(50);
*
* List addresses = new LinkedList();
* addresses.add("192.168.1.1");
* addresses.add("192.168.1.2");
* addresses.add("192.168.1.3");
*
* List 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, {@literal RiakCommand}s from the {@literal com.basho.riak.client.api.commands.*}
* packages are built then executed by the client:
*
* {@code
* 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 {@literal RiakCommand}s asynchronously. A
* {@link RiakFuture} for the operation is immediately returned:
*
* {@code
* Namespace ns = new Namespace("default","my_bucket");
* Location loc = new Location(ns, "my_key");
* FetchValue fv = new FetchValue.Builder(loc).build();
* RiakFuture 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
*
* - {@link com.basho.riak.client.api.commands.kv.FetchValue}
* - {@link com.basho.riak.client.api.commands.kv.MultiFetch}
* - {@link com.basho.riak.client.api.commands.kv.StoreValue}
* - {@link com.basho.riak.client.api.commands.kv.UpdateValue}
* - {@link com.basho.riak.client.api.commands.kv.DeleteValue}
*
* Listing keys in a namespace
* - {@link com.basho.riak.client.api.commands.kv.ListKeys}
* Secondary index (2i) commands
*
* - {@link com.basho.riak.client.api.commands.indexes.RawIndexQuery}
* - {@link com.basho.riak.client.api.commands.indexes.BinIndexQuery}
* - {@link com.basho.riak.client.api.commands.indexes.IntIndexQuery}
* - {@link com.basho.riak.client.api.commands.indexes.BigIntIndexQuery}
*
* Fetching and storing datatypes (CRDTs)
*
* - {@link com.basho.riak.client.api.commands.datatypes.FetchCounter}
* - {@link com.basho.riak.client.api.commands.datatypes.FetchSet}
* - {@link com.basho.riak.client.api.commands.datatypes.FetchMap}
* - {@link com.basho.riak.client.api.commands.datatypes.UpdateCounter}
* - {@link com.basho.riak.client.api.commands.datatypes.UpdateSet}
* - {@link com.basho.riak.client.api.commands.datatypes.UpdateMap}
*
* Querying and modifying buckets
*
* - {@link com.basho.riak.client.api.commands.buckets.FetchBucketProperties}
* - {@link com.basho.riak.client.api.commands.buckets.StoreBucketProperties}
* - {@link com.basho.riak.client.api.commands.buckets.ListBuckets}
*
* Search commands
*
* - {@link com.basho.riak.client.api.commands.search.Search}
* - {@link com.basho.riak.client.api.commands.search.FetchIndex}
* - {@link com.basho.riak.client.api.commands.search.StoreIndex}
* - {@link com.basho.riak.client.api.commands.search.DeleteIndex}
* - {@link com.basho.riak.client.api.commands.search.FetchSchema}
* - {@link com.basho.riak.client.api.commands.search.StoreSchema}
*
* Map-Reduce
*
* - {@link com.basho.riak.client.api.commands.mapreduce.BucketMapReduce}
* - {@link com.basho.riak.client.api.commands.mapreduce.BucketKeyMapReduce}
* - {@link com.basho.riak.client.api.commands.mapreduce.IndexMapReduce}
* - {@link com.basho.riak.client.api.commands.mapreduce.SearchMapReduce}
*
* @author Dave Rusek
* @author Brian Roach
* @since 2.0
*/
public class RiakClient
{
private final 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.
*
* @param cluster the started RiakCluster to use.
*/
public RiakClient(RiakCluster cluster)
{
this.cluster = cluster;
}
/**
* 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).
*
* @return a new client instance.
* @throws UnknownHostException
*/
public static RiakClient newClient() throws UnknownHostException
{
RiakNode.Builder builder = new RiakNode.Builder()
.withMinConnections(10);
RiakCluster cluster = new RiakCluster.Builder(builder.build()).build();
cluster.start();
return new RiakClient(cluster);
}
/**
* Static factory method to create a new client instance.
* This method produces a client connected to the supplied addresses on
* the supplied port.
* @param remoteAddresses a list of IP addresses or hostnames
* @param port the (protocol buffers) port to connect to on the supplied hosts.
* @return a new client instance
* @throws UnknownHostException if a supplied hostname cannot be resolved.
*/
public static RiakClient newClient(int port, String... remoteAddresses) throws UnknownHostException
{
return newClient(port, Arrays.asList(remoteAddresses));
}
/**
* 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).
* @param remoteAddresses a list of IP addresses or hostnames
* @return a new client instance
* @throws UnknownHostException if a supplied hostname cannot be resolved.
*/
public static RiakClient newClient(List remoteAddresses) throws UnknownHostException
{
return newClient(RiakNode.Builder.DEFAULT_REMOTE_PORT, remoteAddresses);
}
/**
* 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).
* @param remoteAddresses a list of IP addresses or hostnames
* @return a new client instance
* @throws UnknownHostException if a supplied hostname cannot be resolved.
*/
public static RiakClient newClient(String... remoteAddresses) throws UnknownHostException
{
return newClient(RiakNode.Builder.DEFAULT_REMOTE_PORT, Arrays.asList(remoteAddresses));
}
/**
* Static factory method to create a new client instance.
* This method produces a client connected to the supplied addresses on
* the supplied port.
* @param remoteAddresses a list of IP addresses or hostnames
* @param port the (protocol buffers) port to connect to on the supplied hosts.
* @return a new client instance
* @throws UnknownHostException if a supplied hostname cannot be resolved.
*/
public static RiakClient newClient(int port, List remoteAddresses) throws UnknownHostException
{
RiakNode.Builder builder = new RiakNode.Builder()
.withRemotePort(port)
.withMinConnections(10);
List nodes = RiakNode.Builder.buildNodes(builder, remoteAddresses);
RiakCluster cluster = new RiakCluster.Builder(nodes).build();
cluster.start();
return new RiakClient(cluster);
}
/**
* Static factory method to create a new client instance.
* This method produces a client connected to the supplied addresses.
* @param addresses one or more addresses to connect to.
* @return a new RiakClient instance.
* @throws java.net.UnknownHostException if a supplied hostname cannot be resolved.
*/
public static RiakClient newClient(InetSocketAddress... addresses) throws UnknownHostException
{
RiakNode.Builder builder = new RiakNode.Builder().withMinConnections(10);
List nodes = new LinkedList();
for (InetSocketAddress addy : addresses)
{
builder.withRemoteAddress(addy.getHostName())
.withRemotePort(addy.getPort());
nodes.add(builder.build());
}
RiakCluster cluster = new RiakCluster.Builder(nodes).build();
cluster.start();
return new RiakClient(cluster);
}
/**
* 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.
*
*
* @param command
* The RiakCommand to execute.
* @param
* The RiakCommand's return type.
* @param The RiakCommand's query info type.
* @return a response from Riak.
* @throws ExecutionException if the command fails for any reason.
* @throws InterruptedException
*/
public T execute(RiakCommand command) throws ExecutionException, InterruptedException
{
return command.execute(cluster);
}
/**
* 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.
* @param RiakCommand's return type.
* @param The RiakCommand's query info type.
* @param command The RiakCommand to execute.
* @return a RiakFuture for the operation.
* @see RiakFuture
*/
public RiakFuture executeAsync(RiakCommand command)
{
return command.executeAsync(cluster);
}
/**
* 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.
*
* @return a future that will complete when shutdown
*/
public Future shutdown()
{
return cluster.shutdown();
}
/**
* Get the RiakCluster being used by this client.
*
* Allows for adding/removing nodes, etc.
*
* @return The RiakCluster instance being used by this client.
*/
public RiakCluster getRiakCluster()
{
return cluster;
}
}