BBoxDB - A distributed storage manager for multi-dimensional big data.

This page shows, how to embed the BBoxDB client into your project and how to set up a connection to a BBoxDB cluster. Since BBoxDB is listed in the central maven repository, you can simple add BBoxDB by using maven.

Building with Maven

To add the BBoxDB client to your project, add the following lines to your pom.xml. All needed dependencies are automatically added to your project.

<dependency>
    <groupId>org.bboxdb</groupId>
    <artifactId>bboxdb-server</artifactId>
    <version>0.8.3</version>
</dependency>

Notice: See the BBoxDB website for the most recent version of the software and replace the value 0.8.3 with the newest version.

Creating your first BBoxDB client

To connect to a BBoxDB cluster, you need to know two things:

The endpoints of your Zookeeper installation
The name of the cluster

This information can be used to create a new object of type BBoxDBCluster:

// The name of the cluster
final String clustername = "mycluster";
    
// The zookeeper connection points
final List<String> connectPoints = Arrays.asList("node1:2181", "node2:2181");

// Connect to the server
final BBoxDB bboxdbClient = new BBoxDBCluster(connectPoints, clustername);

After the object is created, the connection to the cluster can be established and tested:

bboxdbClient.connect();
        
// Check the connection state
if (! bboxdbClient.isConnected()) {
    System.out.println("Error while connecting to the BBoxDB cluster");
    System.exit(-1);
}

After the connection is established, a new tuple can be created and inserted. Please not, all operations are performed asynchronously. Therefore, you have to wait for the operation to complete, until you can check if the operation was successfully or not. Please note, that the tuple is inserted into the table mygroup_data in the distribution group mygroup which has to be created which must be created before.

final Tuple tuple1 = new Tuple("key1", new BoundingBox(0.0, 5.0, 0.0, 1.0), "mydata1".getBytes());
final EmptyResultFuture insertResult1 = bboxdbClient.insertTuple("mygroup_data", tuple1);

// Wait for the insert operations to complete
insertResult1.waitForAll();

if(insertResult1.isFailed()) {
        System.err.println("Unable to insert tuple: " + insertResult1.getAllMessages());
        System.exit(-1);
}

As soon as the tuple is successfully inserted, the tuple can be retrieved by a key query. BBoxDB allows to keep the history of a tuple available. In this case, the key query retuns multiple tuple with different versions for the same key. Therefore, we have to iterate over the result. Please note, this operation is also executed asynchronously. The key query is executed as follows:

// Query by key
final TupleListFuture resultFuture1 = bboxdbClient.queryKey("mygroup_data", "key1");
    
// We got a future object, the search is performed asynchronous
// Wait for the result
resultFuture1.waitForAll();

if(resultFuture1.isFailed()) {
    System.err.println("Future has failed: " + resultFuture1.getAllMessages());
    System.exit(-1);
}

// Output all tuples
for(final Tuple tuple : resultFuture1) {
    System.out.println(tuple);
}

In the last step, the connection to the BBoxDB cluster can be closed. This is done by the disconnect method of the client object:

bboxdbClient.disconnect();

Notice: You will find a full working example for the BBoxDB Client here. This example also contains the creation of the distribution group and the table.

Client software

Building with Maven

Creating your first BBoxDB client