How to Configure Drivers |
Well, where do we start? It is so easy that maybe we should just skip it all together. Just kidding! There are two XML files involved in configuring the drivers, namely 'driver.loader.xml' and 'odbc.driver.xml'. One of these files is specific to the Windows environment, and guess which one that is. Yeah, you got it right - odbc.driver.xml. Both of these files are situated in the application directory, either in the folder itself or inside the jar file that is bundled for release. Whichever of the two, the db-JAPI will find and load it. It is important to note that the hard disk directory takes preference if it exists.That way the user can override the default behaviour (which is actually the XML file stored in the release jar file) with his/her settings, and without damaging the original settings. Pushing on we can say that the driver.loader.xml file holds all the information for the JDBC drivers to be loaded by the system at startup. This includes the programmatic interface of the data source drivers, which is vendor specific. So what does that mean really? Well, it is simple but powerful. We allow the user to specify the functions and parameters for each driver and then the db-JAPI automatically builds the GUI around that. Furthermore it also supplies the input user data (at runtime) to the driver interface as defined in the xml file. Therefore, the programmer does not need to manually include JDBC driver (either Driver or Datasource types) code and therefore making it static to the build process. This mechanism allows for flexibility in loading drivers at any time, before or after the application is built. The other driver file (odbc.driver.xml) allows the user to specify which ODBC drivers to support for directly opening files from the application. In other words opening files without an ODBC declaration in the DSN of the Windows OS. |
The driver.loader.xml file
The driver.loader.xml file is pre-configured to connect to ODBC, ODBC Compatible Files, Oracle, MS-SQL, MySql and PostgreSQL.
Below, as a working example, we see the configuration for the MS SQL Datasource.
![]() |
On the left there is the first part of the <driverListItem> element, which
describes the MS SQL driver configuration. Each driver has it's own
<driverListItem>. There are two elements called <driverClass> and <rowSetClass>, which hold class information for the driver and rowset respecitively. The sub-element <JarFilePath> contains a clean path (without http: or file:jar or jar:). The <fullClassName> contains the complete path of the package and class to be loaded. The <pathType> dictates whether the class is in a jar file or can be found at a URL (options are FILE or URL). In the case of a URL the protocol needs to be supplied (http://my.driver.jar.file.path.jar). The type has two options (DRIVER or DATASOURCE) depending on the internal class type. <JdbcType> is 1-4, as per the JDBC standard types. The <connectionStringFormat> contains the string for connecting, which is not really required for datasource as the information can be provided through the interface functions described below. In the string to the left we see variables between $$ and $$. These variables are directly related to the <parameterListItems> in the interface section below. In this case the server name (shown below as the name of first parameter of the setServerName function) is substituted into the string at execution time along with the port number and the database instance. The <defaultCharset> is used to set the character set in the Connection Dialog with a default value. Below that we have the Operating Systems that support this driver. In this case, although the driver is for MS SQL, it is supported, and can therefore run, on any Java platform. |
![]() |
This is the interface sub-element of the <driverListItem> tag. This tag is
normally only used by the Datasource drivers due to their vendor specific functional
interface(refer to the JAVADOC accompanying the driver). The Driver type only uses
the connection string to connect Each function in the driver has needs to have its own <interfaceListItem> tag. The interface functions are the workhorse of the driver as they are executed at runtime when a connection is made. The functions outlined here must exist, exactly as specified with case sensitivity, in the driver specified above, otherwise it will not be able to execute at run-time. (Check the JavaDoc of the driver for the exact interface of functions and parameters to specify here). This interface, as specified here, can be seen in the Connection Dialog or accessed via the API directly. It is used to specify the names shown to the user and to get the input from the user. The value element holds a default value shown in the field next to the name of the parameter. The user can accept this value or change it. The valid type values are : STRING, DOUBLE, INTEGER, BYTE, BYTES, CHAR, CHARS. All this information is processed using the interface and the user input when the connection is made using the Connection Dialog GUI. In order to set a parameter value for execution by the dynamic interface, when directly coding, one should use the function setValueForInterfaceFunctionParameter (functionName,parameterName,parameterValue) of the TLptsDriverType instance. See an Example |
![]() |
The last part of the <driverListItem> specifies the default credentials of a
guest user. The password is in open text (not encrypted) and is intended for convenience
sake. Note: All credentials are encrypted before storing them in the <credentials> tag of the Connection data. Both the user name and the password are encrypted with the RSA key-pair that is generated for every logged-on user (stored in the user_home/lapetus directory). |
The odbc.driver.xml file
The odbc.driver.xml file provides the means to specify the correlation between the Microsoft file extensions and the drivers to use to open those extensions.
All the types supported by ODBC can be utilised in this file. (in Windows they can be found under the control panel, administrative tools, Data Sources ODBC).
Note: All the ODBC connections declared in the Windows User and System DSNs are shown in the Connection Dialog of the db-JAPI no matter what is declared in this file.
![]() |
The root <XLptsDriverExtensionType> has only one element type
called <operatingSystemListItem>. This holds the driver information for a
specific version of Windows. The supported types, under <osName> are Windows XP,
2003, Vista and Windows 7. As can be seen to the left we have <driverListItem> tags for each type of extension supported. The extension is specified without any '.' or '*.'. The driver name is exactly as specified in the Driver column in the ODBC tool of Windows (in the administrative tools). We can specify a driver many times with different extensions. For instance we could configure 'mdb' and 'accdb' extensions to use the Access driver. All the extensions configured here are included in the supported types of the file open dialog of the Connection Dialog under 'JDBC-ODBC File Open'. |
![]() |