Getting started with the BangDB for Java on Linux

Download

Please download the BangDB for Java for linux file and un-compress. Please ensure that you pick the right binary for 32/64 bit as you may need

Now we need to un compress the downloaded file.


	> tar -xzvf bangdb-linux-32-java-1.5.2.tar.gz
	# Or for 64 bits 
	> tar -xzvf bangdb-linux-64-java-1.5.2.tar.gz
	
	# go to the newly created folder;
	> cd bangdb-java-32bits
	
	# Or, for 64 bits 
	> cd bangdb-java-64bits
	

bangdb-linux-XX-java-1.5.2.tar.gz - downloaded from above (if you rrun ls command)

  • include folder - This contains all the headers and soruce files needed to build app (for C++)
  • libbangdb.so.1.5.2 - The BangDB native library
  • install-bangdb.sh - The BangDB native install file
  • uninstall-bangdb.sh - The BangDB native uninstall file
  • bangdb.config - The config file for BangDB
  • README - General info for the db and the release
  • bangdb-java - This contains bangdb java files and few script files to build jni wrapper. It also contains java bench dir which contains test files for running bangdb bench

Note that tar file contains the native BangDB as well. This is because the java support is provided through jni

Install

To install the BangDB native, run the install-bangdb.sh file

	> sudo bash install-bangdb.sh
		
	# It may ask for your password, please provide that. Next provide the user name;
	> Enter the user name (user who will use the db) :

After this the db will be installed. Basically it creates bangdb group, adds the user to the group, copies the bangdb lib to the /usr/local/lib dir and creates various soft links. Finally it creates a bangdb dir under /usr/local/include and copies all include files under it.

Note that this install is not required if you intend to include the db files providing the full path and also link to the bangdb by manually providing the path to it while compiling. But it's easier to install the bangdb this way for ease of operation in future. Since uninstall file is also included and if you care to unistall in future then running it cleans up completely

Running sample test file

To quickly build and run the test files, go to the bangdb-java dir, run the create-bangdb-java.sh files. Finally go to bangdb_java_bench dir and run make-app.sh to build the test files. Now you are ready to run the test files by running the exapp.sh

You can run the test app now as follows to get and put 100,000 items using 4 threads;

bash exeapp.sh 10000 4

To run the sample test or bench app provided along with the download, here are all the steps;

	> cd bangdb-java
	
	> bash create-bangdb-java.sh

	> cd bangdb_java_bench
	
	> bash make-app.sh
	
	# to run the default test case, do
	> bash exapp
	
	# to put and get 500000 keys and values with 4 threads use following;
	> bash exapp 500000 4
	
	#etc...

Below is sample code to do some simple operations using BangDB. The bangdb.config file defines many configurable parameters, but most importantly edit the following values based on your liking;

  • SERVER_DIR - This is basically the location where the db will keep its files
  • KEY_SIZE - This is to denote the maximum length of key that you will be using to store values. The min value is 8 bytes, and maximum is dependent upon the PAGE_SIZE defined. however keep it small for better performance
  • BUFF_POOL_SIZE_HINT - The size of the buffer pool

Please look at the document which describes meaning of various parameters in the config file at resources or go to the configuration section for detailed information and explanation

To compile and run, you will need to include the bangdb.jar and libbangdb.so. For example, if you code is under the package testbangdb, and you have kept bangdb.jar and libbangdb.so in the root folder then you can run following to compile stuff from the root dir


	> javac -cp "bangdb.jar" testbangdb/*.java
	# and to run the app, use following
	> java -cp .:bangdb.jar -Djava.library.path="." testbangdb.mainclass [command arguments]
	# change the mainclass with name of your class which contains main(), and provide command line arguments as required
	

	/* create db, table and get connection */
	System.loadLibrary("bangdbjava");
	Database db = new DatabaseImpl("mydb", null, TransactionType.DB_MULTIOPS_TRANSACTION_NONE, null, null);
	Table tbl = db.getTable("mytbl", DBAccess.OPENCREATE, null);
	if(tbl == null)
	{
		System.out.println("table null error");
		return;
	}
	Connection conn = tbl.getConnection();
	if(conn == null)
	{
		System.out.println("connection null error");
		return;
	}
	
	bool success = true;
	
	/* insert a value and get it */
	String k = "my key";
	String v = "The test value";
	byte[] key = k.getBytes();
	byte[] val = v.getBytes();

	if(conn.put(key, val, InsertOptions.INSERT_UNIQUE) < 0)
	{
		success = false;
		System.out.println("Put failed");
	}
		
	byte[] retval = conn.get(key);
	if(retval == null)
		System.out.println("Get Failed.");
	else
	{
		if(!Arrays.equals(retval, val))
	    	System.out.println("Get Mismatch.");
	}
	
	/* update */ 
	v = "This is the updated value";
	val = v.getBytes();

	if(conn.put(key, val, InsertOptions.UPDATE_EXISTING) < 0)
	{
		success = false;
		System.out.println("Update failed");
	}
		
	retval = conn.get(key);
	if(retval == null)
		System.out.println("Get Failed.");
	else
	{
		if(!Arrays.equals(retval, val))
	    	System.out.println("Get Mismatch.");
	}
	
	/* delete */
	if(conn.del(key) < 0)
	{
		success = false;
    	System.out.println("delete failed");
	}
		
	if(conn.get(key) != null)
	{
		success = false;
		System.out.println("got deleted value, failed");
	}
	
	/* for string types */
	k = "str key_1";
	v = "This is value 1 for key 1";
		
	if(conn.put(k, v, InsertOptions.INSERT_UPDATE) < 0)
	{
		success = false;
		System.out.println("str put, failed");
	}
		
	String outval;
	if((outval = conn.get(k)) == null)
	{
		success = false;
		System.out.println("str get, failed");
	}
	else if(outval.compareTo(v) != 0)
	{
		success = false;
	   	System.out.println("str mismatch get, failed");
	}
	
	db.closeDatabase(DBClose.DEFAULT);
	if(success)
		System.out.println("Test Passed");
	else
		System.out.println("Test Failed");	
		
	return;
	
	

Later in the section of developing using BangDB, more and advanced details are covered