Riak Java Client 2.0 Upgrade Guide

Why a New Client

Version 2.0 of the Riak Java client (RJC) was a large overhaul of the client. The main goal was to remove years of technical debt at the core by retiring the original Protocol Buffers (PB) and HTTP clients, and replacing them with a modern core that uses Netty4. This also allowed us to remove the translation / abstraction layer that sat between IRiakClient at the top and the aforementioned original clients at the bottom in the 1.X series. Doing these things allowed us to address some long standing design issues, and helped reduce future maintainability and feature development costs.

Historically, the reason for supporting both Protocol Buffers and HTTP protocols in the client library was due to the Riak Protocol Buffers API not supporting all Riak operations. As of Riak 1.4 and the RJC 1.4.0 we have reached feature parity between the two APIs. Protocol buffers is the faster and more efficient way to talk to Riak. In addition, feature development and maintenance is again helped by not having to implement every feature multiple times.

Many Riak 2.0 clients will not support the HTTP interface going forward, but the Riak 2.0 server will still support it. The main drivers for this decision are:

• Performance - Internal tests at Basho have shown performance gains of 25% or more when using Protocol Buffers.
• Feature Support - The HTTP interface also does not support certificate-based authentication.
• Leaky Abstractions - Some HTTP abstractions don't mix well with a distributed database like Riak. For example, the If-None-Match, If-Match, If-Modified-Since, and If-Unmodified-Since headers can be used to invoke conditional request semantics on writes. With concurrent writes in an eventually-consistent environment, it is possible that multiple requests to a single key could all succeed their condition instead of the first one succeeding and the others failing. This was also one of the drivers for switching Riak default behavior of last_write_wins=true to allow_mult=true in Riak 2.0.

What's Not in Java Client 2.0

As mentioned above, HTTP is not supported with the 2.0 Java Client.

The following features are currently not implemented as of Riak Java Client 2.0.1:

• Streaming MapReduce
• Streaming 2i Queries
• Streaming List Keys
• Streaming List Buckets

These are slated to be added soon.

Upgrade Guide

The following is a guide on how to upgrade your code base from the old Java Client 1.x library to the new 2.0 library.

Architecture Differences

The Riak Java Client 1.x series was an amalgamation of two previous clients (a PB client, and an HTTP one), with an API to bridge them together. Since the internal APIs for each were quite different, maintenance and new feature development was a sizable cost. Each protocol sub-client implemented all the different Riak API methods, the majority of each sub-client was implemented in two "God" classes, and each protocol managed its own connections. Most of the operations were synchronous as well.

With the 2.0 Client, the Netty library was adopted to help manage network connections, offer asyncronous operations from the core, and simplify the code base. The API was also moved to use Command & Builder patterns to simplify it, increase testability, and slim down the RiakClient class. Below you can see v1.x and v2.0 code examples.

Cluster Setup

Pooling

To replace the old RiakFactory, use the new RiakClient object and it's static [newClient](http://basho.github.io/riak-java-client/2.0.1/com/basho/riak/client/api/RiakClient.html#newClient(int, java.util.List)) helper methods to create connections to Riak. If you need to specify min/max connection settings, operation retry settings, and security settings, see the example about configuring everything with RiakNode, RiakCluster, and RiakClient objects.

Java Client 1.4.x Creating Connections

import com.basho.riak.client.IRiakClient;
import com.basho.riak.client.RiakFactory; 
import com.basho.riak.client.raw.http.HTTPClusterConfig;
import com.basho.riak.client.raw.pbc.PBClusterConfig;
import com.basho.riak.client.RiakException;

public class App
{
    public static void main(String[] args) throws RiakException
    {
        int maxConnections = 50;

        PBClusterConfig myPbClusterConfig = new PBClusterConfig(maxConnections);
        
        PBClientConfig myPbClientConfig = PBClientConfig.defaults();
        myPbClusterConfig.addHosts(myPbClientConfig, "192.168.1.10","192.168.1.11","192.168.1.12");
        IRiakClient myPbClient = RiakFactory.newClient(myPbClusterConfig);

        myHttpClient.shutdown();
        myPbClient.shutdown();
    }
}

Java Client 2.0.x Creating Connections

import java.net.UnknownHostException;
import com.basho.riak.client.api.RiakClient;

public class RiakClusters {
    public static void main(String [] args) throws UnknownHostException {

        // Riak Client with multiple node connections
        LinkedList<String> ipAddresses = new LinkedList<String>();
        ipAddresses.add("172.16.1.34");
        ipAddresses.add("172.16.1.35");
        ipAddresses.add("172.16.1.36");

        RiakClient myNodeClient = RiakClient.newClient(8087, ipAddresses);

        myNodeClient.shutdown();
    }
}

KV Operations

Create

Read

Update

Delete

Bucket Properties

Querying

2i

MR

Search