Appendix B. Using the Original VoltDB Client Interface

Documentation

VoltDB Home » Documentation » Upgrade Guide

Appendix B. Using the Original VoltDB Client Interface

Volt Active Data has two Java client programming interfaces: Client and Client2. Client2 is a modern API using the best features and design patterns of the Java programming language. Client is the original client API. Because of the improvements made to Client2, Client2 is recommended for all new application development and is featured in the documentation. However, the original Client API is still supported and in use in a number of existing customer applications.

Which is why this appendix is provided for anyone needing to support applications that use the original Client API. The following sections explain how to use the original VoltDB Java client interface for runtime access to VoltDB databases and functions. Please see the Using VoltDB guide for information on writing new applications using the Client2 API.

B.1. Connecting to the VoltDB Database

The first task for the calling program is to create a connection to the VoltDB database. You do this with the following steps:

org.voltdb.client.Client client = null;
ClientConfig config = null;
try {
       config = new ClientConfig("advent","xyzzy");       

       client = ClientFactory.createClient(config);       
 
       client.createConnection("myserver.xyz.net");       
} catch (java.io.IOException e) {
       e.printStackTrace();
       System.exit(-1);
}

Define the configuration for your connections. In its simplest form, the ClientConfig class specifies the username and password to use. It is not absolutely necessary to create a client configuration object. For example, if security is not enabled (and therefore a username and password are not needed) a configuration object is not required. But it is a good practice to define the client configuration to ensure the same credentials are used for all connections against a single client. It is also possible to define additional characteristics of the client connections as part of the configuration, such as the timeout period for procedure invocations or a status listener. (See Section B.5, “Handling Errors”.)

Create an instance of the VoltDB Client class.

Call the createConnection() method. After you instantiate your client object, the argument to createConnection() specifies the database node to connect to. You can specify the server node as a hostname (as in the preceding example) or as an IP address. You can also add a second argument if you want to connect to a port other than the default. For example, the following createConnection() call attempts to connect to the admin port, 21211:

client.createConnection("myserver.xyz.net",21211);

If security is enabled and the username and password in the ClientConfig() call do not match a user defined in the configuration file, the call to createConnection() will throw an exception.

When you are done with the connection, you should make sure your application calls the close() method to clean up any memory allocated for the connection. See Section B.4, “Closing the Connection”.

B.1.1. Connecting to Multiple Servers

You can create the connection to any of the nodes in the database cluster and your stored procedure will be routed appropriately. In fact, you can create connections to multiple nodes on the server and your subsequent requests will be distributed to the various connections. For example, the following Java code creates the client object and then connects to all three nodes of the cluster. In this case, security is not enabled so no client configuration is needed:

try {
       client = ClientFactory.createClient();
       client.createConnection("server1.xyz.net");
       client.createConnection("server2.xyz.net");
       client.createConnection("server3.xyz.net");
} catch (java.io.IOException e) {
       e.printStackTrace();
       System.exit(-1);
}

Creating multiple connections has three major benefits:

Multiple connections distribute the stored procedure requests around the cluster, avoiding a bottleneck where all requests are queued through a single host. This is particularly important when using asynchronous procedure calls or multiple clients.
For Java applications, the VoltDB Java client library uses client affinity. That is, the client knows which server to send each request to based on the partitioning, thereby eliminating unnecessary network hops.
Finally, if a server fails for any reason, when using K-safety the client can continue to submit requests through connections to the remaining nodes. This avoids a single point of failure between client and database cluster.

B.1.2. Using the Auto-Connecting Client

An easier way to create connections to all of the database servers is to use the "smart" or topology-aware client. By setting the Java client to be aware of the cluster topology, you only need to connect to one server and the client automatically connects to all of the servers in the cluster.

An additional advantage of the smart client is that it will automatically reconnect whenever the topology changes. That is, if a server fails and then rejoins the cluster, or new nodes are added to the cluster, the client will automatically create connections to the newly available servers.

You enable auto-connecting when you initialize the client object by setting the configuration option before creating the client object. For example:

org.voltdb.client.Client client = null;
ClientConfig config = new ClientConfig("","");
config.setTopologyChangeAware(true);
 try {
       client = ClientFactory.createClient(config);
       client.createConnection("server1.xyz.net");
             . . .

When setTopologyChangeAware() is set to true, the client library will automatically connect to all servers in the cluster and adjust its connections any time the cluster topology changes.

< previous

table of contents

next >