Getting Started With VoltDB

contents

3.8. Writing the Client Application

Now that you have defined your database schema and written the stored procedures, you can write the client code to call the stored procedures. Client interfaces are available for several programming languages. But for this example we will use the VoltDB java client.

Our client application is very simple: it calls the Insert procedure repeatedly to load the database, then it calls Select to retrieve and display the hello world message in the language of your choice. Start your text editor and create a new file called Client.java. Begin your client code by importing the necessary system and VoltDB libraries and starting the client class.

Note

For serious programming, you will want to organize your Java code into packages. For example, keeping your stored procedures in one package and your client classes in another. When you do this, you need to import the procedures package as well. But to keep this sample simple, we are keeping all code in a single directory,

import org.voltdb.*;
import org.voltdb.client.*;

public class Client {

The first thing your application needs to do is create a client connection to the database. This is done by creating a org.voltdb.client.Client (using the ClientFactory) and opening the connection, like so:

    public static void main(String[] args) throws Exception {

        /*
         * Instantiate a client and connect to the database.
         */
        org.voltdb.client.Client myApp;
        myApp = ClientFactory.createClient();
        myApp.createConnection("localhost");

Note that when you create the connection, you specify the network node where the database server is running. If the database is running on a cluster, you can specify any one of the cluster nodes when you create a connection. In fact, you can create connections to multiple nodes in the cluster to help distribute the work by invoking the createConnection method once for each node.

But for now, we are running the database and the client locally. So you can specify the node as "localhost" when you create the connection for your Hello World application.

Once you open the database connection, you are ready to call the stored procedures. To call a VoltDB stored procedure, use the volt.Client.callProcedure method. For our example, we first call the Insert procedure several times, passing in the three arguments it requires.

    /*
     * Load the database.
     */
    myApp.callProcedure("Insert", "English", "Hello", "World");
    myApp.callProcedure("Insert", "French", "Bonjour", "Monde");
    myApp.callProcedure("Insert", "Spanish", "Hola", "Mundo");
    myApp.callProcedure("Insert", "Danish", "Hej", "Verden");
    myApp.callProcedure("Insert", "Italian", "Ciao", "Mondo");

Next we call the Select procedure to retrieve the message in a language of your choice. For the example code, we will use Spanish, but you can choose any of the languages stored by the Insert procedure.

To retrieve the message, we not only want to call the procedure, we also want to decipher the results that are in the VoltTable array returned by the stored procedure. The following code segment shows how this is done. First we check to make sure we have valid results by ensuring that the status from the procedure call is SUCCESS. Then we get the actual results from the ClientResponse object with the GetResults method. To evaluate the results, we then fetch the first row of the first VoltTable in the array. Finally, we use the getString method to fetch the individual fields from the returned table row and output them to standard output.

Type this into your Client.java file.

        /*
         * Retrieve the message.
         */
        final ClientResponse response = myApp.callProcedure("Select", 
                                                            "Spanish");
        if (response.getStatus() != ClientResponse.SUCCESS){
            System.err.println(response.getStatusString());
            System.exit(-1);
        }

        final VoltTable results[] = response.getResults();
        if (results.length == 0 || results[0].getRowCount() != 1) {
            System.out.printf("I can't say Hello in that language.\n");
            System.exit(-1);
        }

        VoltTable resultTable = results[0];
        VoltTableRow row = resultTable.fetchRow(0);
        System.out.printf("%s, %s!\n", row.getString("hello"), 
                                       row.getString("world"));
    }
}

Your client application is now done. See Example A.4, “Client.java” for a complete listing of the client.java source code.

contents