How do I configure JBuilder and the JDBC Explorer/Database Pilot to use my JDBC database drivers?

JBuilder, The JDBC Explorer And Database Drivers

Note: In JBuilder 5 and JBuilder 6 the JDBC Explorer has been renamed to Database Pilot.

In order for JBuilder, the JDBC Explorer (JDBCE)/Database Pilot (DBPilot), and your own applications to use a JDBC driver that JDBC driver must be on the classpath. An application's classpath, when you launch that application from JBuilder, is determined by the application's Project Properties. The JDBCE/DBPilot classpath is not determined by Project Properties. It is determined when you start up JBuilder, or when you start up the JDBCE/DBPilot in stand-alone mode. This means that in order to use your database driver in these different situations, you will have to have your classpath setup correctly for each case.

You will also find an explanation of how the drop-down database driver list works in the various parts of JBuilder at the end of this document.

For this document, let's say we have the following Oracle driver that we wish to use:

c:/orant/jdbc/lib/classes12_01.zip

Making A Driver Available To JDBCE/DBPilot

• JBuilder 4, JBuilder 5, JBuilder 6
  1. Select Tools | Enterprise Setup.
  2. Click on the Database Drivers tab.
  3. Click on the Add button.
  4. If you have a Library already defined that references the above zip file, goto step 10.
  5. If you do not have such a Library defined, click on the New button.
  6. Enter a name for the Library, e.g., "Oracle".
  7. Click on the add button.
  8. Navigate to and select c:/orant/jdbc/lib/classes12_01.zip
  9. Click OK.
  10. Select the Library that references the Oracle .zip file (it will be named "Oracle" if you just created it in step 6).
  11. Depending on the name of your Library, you will now see a .config file in the listbox, e.g., "Oracle.config".
  12. Select OK.

  You now need to restart JBuilder for your changes to take affect. If you run JDBCE/DBPilot stand-alone, the Oracle driver will also be on the JDBCE/DBPilot classpath.
  
  

• JBuilder 3.5
  1. Open the file "JBuilder.config" with a text editor. This file is located in your jbuilder35/bin directory.
  2. Towards the end of the config file, after the last "addjars" line, add the following:

     addpath c:/orant/jdbc/lib/classes12_01.zip

  3. Add the same line to "jdbce.config", after the "# Add other database drivers here" line:

     addpath c:/orant/jdbc/lib/classes12_01.zip

  The next time you run JBuilder or the JDBC Explorer, the driver will be available on the classpath.
  
  

• JBuilder 3
  1. With JBuilder not running, open "jbuilder.ini" in a text editor.
  2. Find the line that starts with "Djava.class.path=".
  3. Append ;c:/orant/jdbc/lib/classes12_01.zip to the end of that line. Note the semi-colon separating your driver from other entries on that line.

  The next time you start JBuilder, the driver will be available to the JDBC Explorer. Note that in JBuilder 3, the JDBC Explorer does not run outside of JBuilder.

Making A Driver Available To Your Application

1. With your application's Project open, select Project | Properties.
2. Click on the Required Libraries tab.
3. Click on the Add button.
4. If you have a library defined for your driver select it and click OK.
5. Otherwise, click on New, and define a library pointing to your driver.
6. Then select the new library and add it to your project's required libraries.

Fat Drivers

JDBC Type 2 drivers, also known as "fat" drivers, are drivers that call into local binaries that in turn communicate with the database. Some fat drivers include the Oracle OCI driver and IBM's DB2 driver (note that the Oracle thin driver, as its name implies, is not a fat driver). The JDBC driver needs to be able to find those local binaries in order to function properly. If you have the Java .jar/.zip file correctly set up on your classpath for fat driver, and the driver still does not appear to load correctly, there are a couple of things you can try:

• Add the client's binary directory to your operating system's PATH.
• Or, specify the location of the binary directory via the system property java.library.path
  • For JDBCE/DBPilot
    • JBuilder 4, JBuilder 5, JBuilder 6, and JBuilder 3.5:

      Add this line to the "jdk.config", located in your "jbuilder35/bin" or "/jbuilder4/bin" directory:

      vmparam -Djava.library.path=c:/orant/bin

      If you already have a "java.library.path" entry, simply append your path to the end of that entry, separating this new entry from the rest of the line either with a colon (Linux/Solaris), or a semi-colon (Windows).

    • JBuilder 3:

      Add this line to "jbuilder.ini", in the [JavaVM_Properties] section, when JBuilder is not running:

      Djava.library.path=c:/orant/bin

      If there is already a "Djava.library.path" entry, append your new binary directory to that line, separated by a semicolon.

  • For your application
    1. Project | Properties
    2. Click on the Run tab
    3. Append this to the VM Parameters entry: -Djava.library.path=c:/orant/bin

Drop Down List Of Drivers

In the JDBCE/DBPilot, when you do File | New, a combobox with a list of drivers appears. This combobox also appears in other contexts in JBuilder, e.g., in the ConnectionDescriptor property editor. This list of drivers is simply a facility to make it easier to select a driver. It is not an exhaustive list of drivers, nor does the presence of a driver on that list necessarily mean that the driver is on the classpath. It also possible that a driver is on your classpath, but not in the dropdown list. If a driver on the classpath is not in the list, you can still use that driver: simply type in the driver's classname.

In JBuilder 4, 5, and 6 you can tell which drivers in the dropdown list are actually on the classpath. Drivers on the classpath will be in black, while drivers not on the classpath will be in red. In versions before JBuilder 4, it is not visually possible to determine which of those drivers are on the classpath.

If you wish, you can add new drivers to the dropdown list, and/or remove drivers that you know you will never use:

• JBuilder 4, JBuilder 5, JBuilder 6
  1. Run the JDBCE/DBPilot
  2. View | Options
  3. Select the Drivers tab.
  4. Using the UI, you can add, edit, and remove drivers.
  
  
  
• JBuilder 3.5 and JBuilder 3

  There is no UI to manipulate that dropdown list. Instead, when JBuilder and the JDBC Explorer are not running, edit the "jdbcexplorer.properties" file with a text editor. This file is located in your <user home>/.jdatastore directory. The location of <user home> is operating system specific: on Linux/Solaris, that will be the userhome directory; in Windows 2000, it is in "Documents and Settings/<username>"; on NT 4.0 it is in "winnt/profiles/<username>".

  In the editor, add a line where you specify the classname of the driver, followed by ".sampleUrl=<some sample URL without "jdbc">". For example, if your driver classname is "com.mycompany.mydriver", and a URL for that driver looks like

  jdbc:mydriver://someserver.com/CustomerDatabase.mydbms

  then you might add a line like this:

  com.mycompany.driver.sampleUrl=mydriver://hostname/databasename