Chapter 5. Client2, A Modern Java Client Programming Interface (API)

Documentation

VoltDB Home » Documentation » Guide to Performance and Customization
< previoustable of contentsnext >

Chapter 5. Client2, A Modern Java Client Programming Interface (API)

VoltDB V11 introduces a new client programming interface. The Client2 interface is similar to the original Client interface in that you create a configuration object, then create the client itself using the client factory. After connecting to the database, you can then make either synchronous or asynchronous procedure calls.

However, that is where the similarity ends. Where Client provides a rudimentary interface using generic callbacks to handle both success and failure, Client2 uses modern Java programming techniques and smarter defaults to provide a structured and extensible interface, including:

  • A "builder" pattern for the Client2Config, with individual methods that can be chained to set configuration options.

  • No mandatory settings, all attributes have default values.

  • Smarter default behavior to simplify application development.

  • Individually configured notifications, set as callbacks on the configuration object, that let the application decide which events it wants to be notified about and how.

  • Use of Java CompletableFutures to handle asynchronous procedure calls, giving the application developer more structured and precise handling of invocation events.

The following sections describe the individual steps for creating and application using the Client2 API. For a complete listing of classes and methods, see the VoltDB Client API javadoc.

5.1. Configuring the Client

The first step is to set the configuration options for your client, using Client2Config. You can take the default options by just creating a new Client2Config object:

Client2Config config = new Client2Config(); 
Client2 client = ClientFactory.createClient(config);

Or you can specify individual attributes by chaining the associated methods, when you create the configuration object:

Client2Config config = new Client2Config().username("john")
                                          .password("doe"); 
Client2 client = ClientFactory.createClient(config);

Note that you can set up custom error handling as part of the configuration by defining which events the application wants to be notified about. For example:

Client2Config config = new Client2Config().username("john")
                                          .password("doe")
                                          .connectionDownHandler(..myDropHandler..); 
Client2 client = ClientFactory.createClient(config);

The interfaces to the handlers are defined as functional interfaces in the class Client2Notification, allowing use of method references or lambda expressions.

< previoustable of contentsnext >