Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Simple client in Eclipse

This describes a step by step procedure for setting up an Eclipse project with a simple test application that allows debugging of stored procedure and client code.

Prerequisites.

  • You have downloaded VoltDB.
  • You have a VoltDB jar file.

Create a new test project and configure it for VoltDB.

  • Choose File / New / Java Project from the menu.
  • Provide a name, e.g. TEST.
  • Press Next >.

Add the Java library dependencies.

VoltDB relies on loading our own library jar file and some third party libraries. They can be found in the "voltdb" and "lib" folders of a VoltDB distribution. It also needs a native JNI library from the "voltdb" folder of the distribution.

  • Select the Libraries tab.
  • Press Add External JARs... and select all jar files in the VoltDB distribution "lib" folder.
  • Press Add External JARs... and select the voltdb (not client) jar file the VoltDB distribution "voltdb" folder.

Add the native library dependency.

From the Libraries tab...

  • Open the JRE System Library item in the build path tree.
  • Select the Native library location line.
  • Press Edit...
  • Press External Folder.. in the Native Library Folder Configuration dialog.
  • Pick the "voltdb" folder from the VoltDB distribution.
  • Press Open and then OK on the previous dialog.
  • Press Finish to create the new project.

Create a new package.

  • Choose File / New / Package from the menu.
  • Provide a name, e.g. testclient.

Create a new main class.

  • Select the package and choose New / Class from the context menu.
  • Provide a name, e.g. TestClient.
  • Enable the checkbox for generating a main() stub.
  • Press Finish to create and open the new class.

Write the test code.

Create a VoltDB Configuration object.

The configuration object specifies the catalog file paths. The example code below uses utility methods to generate output file paths for testing. The Configuration constructor accepts a port generator to determine runtime TCP port assignments.

// Create a VoltDB configuration.
VoltDB.Configuration config = new VoltDB.Configuration(new PortGenerator());
config.m_pathToCatalog = Configuration.getPathToCatalogForTest("testclient.jar");
config.m_pathToDeployment = Configuration.getPathToCatalogForTest("testclient.xml");

Use a VoltProjectBuilder object to create a schema.

VoltProjectBuilder can produce catalogs using an API rather than external files.

// Specify the DDL and partitioning.
VoltProjectBuilder builder = new VoltProjectBuilder();
builder.addLiteralSchema("CREATE TABLE t1 (" +
                     "  id INTEGER DEFAULT '0' NOT NULL," +
                     "  number INTEGER NOT NULL," +
                     "  text VARCHAR(255) NOT NULL," +
                     "  PRIMARY KEY (id)" +
                     "); " +
                     "CREATE UNIQUE INDEX i1 ON t1 (id);");
builder.addPartitionInfo("t1", "number");

Create the stored procedure.

  • Select the package and choose New / Class from the context menu.
  • Provide a name, e.g. TestProcedure.
  • Choose org.voltdb.VoltProcedure as the superclass.

For example:

  import org.voltdb.ProcInfo;
  import org.voltdb.SQLStmt;
  import org.voltdb.VoltProcedure;
  import org.voltdb.VoltTable;

  @ProcInfo (
      partitionInfo = "t1.number: 0",
     singlePartition = true
  )
  public class TestProcedure extends VoltProcedure {
      public final SQLStmt
      sqlAdd = new SQLStmt("insert into t1 (id, number, text) values (?, ?, ?);");

      public VoltTable[] run(int id, int number, String text)
              throws VoltAbortException {
          voltQueueSQL(sqlAdd, id, number, text);
          voltExecuteSQL();
          return null;
      }
  }

Add the stored procedure to the project builder.

// Register stored procedures.
builder.addProcedures(new Class<?>[] {
    TestProcedure.class
    // Add more procedures here.
} );

Compile the catalog using the project builder.

The example code below compiles the catalog for 2 sites per host, 1 host, and no replication.

// Compile the catalog using the configuration object catalog path.
// Copy the deployment file from where the builder puts it to where
// the configuration expects it.
boolean success = builder.compile(config.m_pathToCatalog, 2, 1, 0);
MiscUtils.copyFile(builder.getPathToDeployment(), config.m_pathToDeployment);

Create a ServerThread.

The ServerThread class implements a VoltDB server as an in-process thread.

// Start a ServerThread as an in-process VoltDB back-end.
ServerThread server = new ServerThread(config);
server.start();
server.waitForInitialization();

Create a Client and connect.

The server runs on "localhost" and uses the port generated by the PortGenerator.

// Create a client and connect.
Client client = ClientFactory.createClient();
client.createConnection("localhost", config.m_port);

Pulling it all together - the complete TestClient.

The full example code below pulls together the previous code snippets and adds shutdown and some minimal error checking.

package testclient;

import org.voltcore.utils.PortGenerator;
import org.voltdb.ServerThread;
import org.voltdb.VoltDB;
import org.voltdb.VoltDB.Configuration;
import org.voltdb.client.Client;
import org.voltdb.client.ClientFactory;
import org.voltdb.compiler.VoltProjectBuilder;
import org.voltdb.utils.MiscUtils;

public class TestClient {

    public static void main(String[] args) {
        ServerThread server = null;
        Client client = null;
        try {
            // Create a VoltDB configuration.
            VoltDB.Configuration config = new VoltDB.Configuration(new PortGenerator());
            config.m_pathToCatalog = Configuration.getPathToCatalogForTest("testclient.jar");
            config.m_pathToDeployment = Configuration.getPathToCatalogForTest("testclient.xml");

            // Specify the DDL and partitioning.
            VoltProjectBuilder builder = new VoltProjectBuilder();
            builder.addLiteralSchema("CREATE TABLE t1 (" +
                                 "  id INTEGER DEFAULT '0' NOT NULL," +
                                 "  number INTEGER NOT NULL," +
                                 "  text VARCHAR(255) NOT NULL," +
                                 "  PRIMARY KEY (id)" +
                                 "); " +
                                 "CREATE UNIQUE INDEX i1 ON t1 (id);");
            builder.addPartitionInfo("t1", "number");

            // Register stored procedures.
            builder.addProcedures(new Class<?>[] {
                    TestProcedure.class
                    // Add more procedures here.
                    } );

            // Compile the catalog using the configuration object catalog path.
            // Copy the deployment file from where the builder puts it to where
            // the configuration expects it.
            boolean success = builder.compile(config.m_pathToCatalog, 2, 1, 0);
            assert success;
            MiscUtils.copyFile(builder.getPathToDeployment(), config.m_pathToDeployment);

            // Start a ServerThread as an in-process VoltDB back-end.
            server = new ServerThread(config);
            server.start();
            server.waitForInitialization();

            // Create a client and connect.
            client = ClientFactory.createClient();
            client.createConnection("localhost", config.m_port);

            // Perform the client actions.
            client.callProcedure("TestProcedure", 1, 111, "some text");
            // More actions go here.
        }
        catch (Exception e) {
            e.printStackTrace();
        }
        finally {
            try {
                if (client != null) {
                    client.close();
                }

                if (server != null) {
                    server.shutdown();
                    server.join();
                }
            }
            catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }

}

Debugging the test client and stored procedure.

At this point you can launch the TestClient main program. The launcher needs no additions or changes to work. You can freely set breakpoints in either the client code or the stored procedure since they run in the same process.

Something went wrong with that request. Please try again.