JDBC Driver Manager—Functional Specification

Author: Radko Najman
$Revision: 1.4 $
$Date: 2005/05/02 18:03:01 $

Table of Contents:

1. Introduction
2. JDBC Driver Registration
3. User Scenarios
• IDE user
• 3rd party module
• IDE installer
4. How To Get the Registered Driver
5. Upgrade from Netbeans 3.5 and backward compatibility

1. Introduction

In NetBeans 3.5 and earlier versions it was necessary to copy JDBC driver into <NetBeans installation>/lib/ext directory. This approach was a bit uncomfortable and it was redesigned for releases after NetBeans 3.5. Now it is possible to use JDBC driver from user defined location. This document describes these changes.

2. JDBC Driver Registration

To register the driver within the IDE means to define driver file, driver class and driver descriptive name. This information about the driver is stored in an XML file with the following structure:

<?xml version='1.0'?>
<!DOCTYPE driver PUBLIC '-//NetBeans//DTD JDBC Driver 1.0//EN' 'http://www.netbeans.org/dtds/jdbc-driver-1_0.dtd'>
<driver>
    <name value='<descriptive name>'/>
    <class value='<driver class>'/>
    <urls>
        <url value='file:/<driver file1 location>'/>
        <url value='file:/<driver file2 location>'/>
    </urls>
</driver>

The JDBC driver can consist of more files, that's why it is possible to specify more URLs. These registration files are placed in default filesystem in Services/JDBCDrivers folder and can be found by Lookup.

3. User Scenarios

There are three typical user scenarios related to the driver registration.

IDE user

This scenario describes the situation when the IDE user decides to register the JDBC driver their self. This is the easier and probably more common case. The Database Explorer provides Add driver... action on the Drivers node. The dialog will appear and the user will specify all required information in it. The driver registration file will be created in <NetBeans userdir>/system/Services/JDBCDrivers.

For more info see the UI specification.

3rd Party Module

3rd party modules can register their own drivers. Example of this module can be a module which integrates a database to the IDE. The best way to register this driver is to put the registration file to the module's layer using the following code:

<filesystem>
    <folder name="Services">
        <folder name="JDBCDrivers">
            <file name="JDBC-ODBC Bridge.xml" url="nbresloc:/org/netbeans/modules/db/resources/JDBCODBC.xml"/>
        </folder>   
</filesystem>

The url parameter identifies the location of the registration XML file within the module hierarchy.

IDE Installer

The IDE installer can collect information about JDBC drivers and register these drivers for the user. To do this the installer have to generate the XML file described in section 2 and store this file in <NetBeans installation>/system/Services/JDBCDrivers directory.

4. How To Get the Registered Driver

It is possible to work with registered drivers using JDBCDriver and JDBCDriverManager classes from the org.netbeans.modules.db.explorer.driver package.

JDBCDriver represents the driver registration and it is possible to obtain the driver file location and driver class from it.

JDBCDriverManager manages the instances of the JDBCDriver class.

5. Upgrade From Netbeans 3.5 and Backward Compatibility

The new implementation of the Database Explorer module is able to recognize JDBC drivers in lib/ext directory if they are any and auto-register them. The check for JDBC drivers in lib/ext directory id done only once (when the module is upgraded to new version). If there is a JDBC driver in lib/ext directory and it is not registered by the new way, the Database Explorer is still able to work with it as in previous versions.