Bottomline

Overview

Bottomline is a JDBC Bridge API that loads database drivers directly from JAR archives. Bottomline uses a jdbc:bottomline bridge to load multiple drivers from their respective JAR files. Unlike JDBC, Bottomline uses custom class loaders to load drivers completely bypassing JVM's bootstrap class loader.

Some features of Bottomline

Bottomline helps to load multiple database drivers using separate class loaders.
Multiple versions of the same database driver can be loaded from different JAR files.
Developers can build applications using conventional JDBC and transparently use Bottomline underneath.
Bottomline seamlessly integrates with applications servers like JBoss and can be bound in JNDI which allows connections to be pooled using the application server's Connection Pooler.

Below is a diagram that illustrates how seamlessly bottomline integrates with java applications.

Using Bottomline with raw JDBC

Using Bottomline with JDBC is very easy. Bottomline provides a custom driver (BottomlineDriver) and uses the jdbc:bottomline bridge to connect to any database that is supported by JDBC. Developers will use BottomlineDriver like any other database driver and use the bridge to connect to any required database.

First download latest versions of bottomline.jar and log4j.jar files and put them in the application's CLASSPATH. These files are included in the latest Bottomline binaries download.
Older versions prior to 1.2 also require jcl.jar

Class.forName("xeus.bottomline.BottomlineDriver");

Properties props = new Properties();
props.put("user", "root");
props.put("password", "root");
props.put("jar","D:\\database-drivers\\mysql-connector-java-5.0.3\\mysql-connector-java-5.0.3-bin.jar");
props.put("class", "com.mysql.jdbc.Driver");

Connection conn = DriverManager.getConnection("jdbc:bottomline:mysql://localhost:3306/myDB", props);

/*
In version 1.2 or later.
The connection parameters can be passed as Query String to the connection URL
*/

Connection conn1 = DriverManager.getConnection("jdbc:bottomline:mysql://localhost:3306/myDB?user=root&password=root"
+ "&jar=D:\\database-drivers\\mysql-connector-java-5.0.3\\mysql-connector-java-5.0.3-bin.jar"
+ "&class=com.mysql.jdbc.Driver");

// And also like the following

Connection conn2 = DriverManager.getConnection("jdbc:bottomline:mysql://localhost:3306/myDB?"
+ "&jar=D:\\database-drivers\\mysql-connector-java-5.0.3\\mysql-connector-java-5.0.3-bin.jar"
+ "&class=com.mysql.jdbc.Driver", "root", "root");

The example shows how easy it is to use Bottomline with JDBC.

The xeus.bottomline.BottomlineDriver class is loaded first like any other driverA java.util.Properties object is filled with all the required properties or they are passed as query string to the connection URL (v-1.2) as shown. There are four properties (case-sensitive) that are needed to be set
- user (The database user)
- password (The database password)
- jar (The driver JAR file)
- class (The driver class in the JAR file)
Connection is created by calling DriverManager's getConnection method.

* The connection string will always starts with jdbc:bottomline prefix.

Using Bottomline with JNDI Datasources on JBoss

It is also simple to use Bottomline with JNDI Datasources. Lets take an example of JBoss. In JBoss JNDI datasources are defined in a XXX-ds.xml file in the deploy directory. Adding Bottomline datasources in this file is like adding any other datasource using any driver. JNDI bound Bottomline datasources seamlessly integrate with the application without having to change a single line of java code. Only the JNDI datasource definition file shown below needs to be updated. First download and copy latest version of bottomline.jar in "lib" directory of JBoss server e.g. JBOSS_HOME/server/default/lib

Below is a sample spec from this file that illustrates how to bind Bottomline datasources in JNDI.

<datasources>
<local-tx-datasource>
     <jndi-name>MySQL_Version_5</jndi-name>
     <connection-url>jdbc:bottomline:mysql://192.0.0.1:3306/MyDB5</connection-url>
     <driver-class>xeus.bottomline.BottomlineDriver</driver-class>

     
     <connection-property name="user">
           root
     </connection-property>
     <connection-property name="password">
          root
    </connection-property>
    <connection-property name="jar">
          D:\\database-drivers\mysql\\mysql-5.0.3.jar
    </connection-property>
    <connection-property name="class">
         com.mysql.jdbc.Driver
    </connection-property>
</local-tx-datasource>

<local-tx-datasource>
     <jndi-name>MySQL_Version_3</jndi-name>


     <connection-url>            jdbc:bottomline:mysql://192.0.0.2:3306/MyDB3?user=root&password=root&jar=D:\\database-drivers\mysql\\mysql-3.jar&class=com.mysql.jdbc.Driver
     </connection-url>
     <driver-class>xeus.bottomline.BottomlineDriver</driver-class>
</local-tx-datasource>
</datasources>

The example shows how two different versions of MySQL driver are loaded and bound in JNDI using the JDBC-Bottomline bridge; this is only possible through Bottomline. The connection properties are defined just like in the previous JDBC example. The connections can be looked up from InitialContext like:

Context context = new InitialContext();
Connection mySQL5Con = ((DataSource)context.lookup("java:/MySQL_Version_5")).getConnection();
Connection mySQL3Con = ((DataSource)context.lookup("java:/MySQL_Version_3")).getConnection();

Downloads

Bottomline is open source and is distributed under ASL 2.0.

- Bottomline binaries

Bottomline source can be anonymously checked-out from Subversion using the following command:

svn co https://svn.sourceforge.net/svnroot/bottomline bottomline

Author: Kamran Zafar
xeus.man@gmail.com
[Author's Homepage]