Getting started

Overview
Installing the Easysoft JDBC-Access Gateway
Connecting to your Access database
Tracing

Overview

The Easysoft JDBC-Access Gateway provides JDBC access from Java applications, application servers, and servlets to MDB or ACCDB files. If you configure your Java security policy to allow the Easysoft JDBC-Access Gateway to load its native component, the driver can also be used with Java applets.

Access has four components: a structure to hold data (tables), a way to manipulate that data, an environment to create a front end for the data (Design view of forms and reports) and tools that can run the front end (Data view of forms and reports). Access data is stored in a database file, which has the extension .mdb or .accdb.

The Easysoft JDBC-Access Gateway is a JDBC driver for Access that uses the Java Native Interface (JNI) to communicate with Microsoft’s Access ODBC driver library. The Access ODBC driver is used to connect to the target database file.

The Access ODBC driver must be installed on the machine on which you install the Easysoft JDBC-Access Gateway. Since Windows 2000, the Access ODBC driver (one of the Jet Database Engine Components) has shipped with Windows and so should be already present on your machine as part of the Windows installation.

If the file you want to connect to is an ACCDB format database (.accdb) you need to install aceodbc.dll on the Easysoft JDBC-Access Gateway machine, which is available from Microsoft’s web site.

The target database file must be visible through the local file system on the Easysoft JDBC-Access Gateway machine. For example, in a folder on this machine or a mapped network drive or in a shared folder.

Installing the Easysoft JDBC-Access Gateway

Installing on Windows

The Windows installation can be done by anyone with local administrator privileges.

Download the Easysoft JDBC-Access Gateway installer.
Follow the onscreen instructions to progress through the installation wizard.

Updating files that are in use

To avoid rebooting your computer, the Easysoft JDBC-Access Gateway installer prompts you when files that it needs to update are in use by another application or service. This frees the locked files and allows the installation to complete without a system restart. The installer uses the Restart Manager to locate the applications that are using files that need updating. These applications are displayed in the Files in Use dialog box. To avoid a system restart, choose Automatically close applications and attempt to restart them after setup is complete. The Easysoft JDBC-Access Gateway installer then uses Restart Manager to try to stop and restart each application or service in the list. If possible, Restart Manager restores applications to the same state that they were in before it shut them down.

Licensing

By default, the installer starts the Easysoft License Manager, because you can’t use the Easysoft JDBC-Access Gateway until you have a license. If you choose not to run Easysoft License Manager as part of the installation process, run License Manager from the Easysoft group in the Windows Start menu when you’re ready to license the Easysoft JDBC-Access Gateway. These types of license are available:

A free time-limited trial license, which gives you free and unrestricted use of the product for a limited period (usually 14 days).
A full license if you have purchased the product. On purchasing the product you are given an authorization code, which you use to obtain a license.

To license the Easysoft JDBC-Access Gateway:

In License Manager, enter your contact details.

You must complete the Name, E-Mail Address, and Company fields.

The e-mail address must be the same as the one used to register at the Easysoft web site. Otherwise, you won’t be able to obtain a trial license.
Choose Request License.

You’re prompted to choose a license type.
Do one of the following:
- For a trial license, choose Time Limited Trial, and then choose Next.
  -Or-
- For a purchased license, choose Non-expiring License, and then choose Next.
Choose your product from the drop-down list when prompted, and then choose Next.
For a purchased license, enter your authorization code when prompted, and then choose Next.
Choose how to get your license when prompted.
Do one of the following:
- Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.
  With this method, License Manager automatically requests and then applies your license.
  -Or-
- Choose View Request. Then open a web browser and go to https://www.easysoft.com/support/licensing/trial_license.html or https://www.easysoft.com/support/licensing/full_license.html, as appropriate. In the web page, enter your machine number (labelled Number in the license request). For purchased licenses, you also need to enter your authorization code (labelled Ref in the license request).
  We’ll automatically email your license to the email address you supplied in License Manager.
  -Or-
- Choose Email Request to email your license request to our licensing team.
  Once we’ve processed you request, we’ll email your license to the email address you supplied in License Manager.
Close the License Manager windows and then choose Finish.

If you chose either View Request or Email Request, apply your license by double-clicking the email attachment when you get the license email from us. Alternatively, start License Manager from the Easysoft folder in the Windows Start menu. Then choose Enter License and paste the license in the space provided.

Once you’ve licensed the Easysoft JDBC-Access Gateway, the installation is complete.

Repairing the installation

The installer can repair a broken Easysoft JDBC-Access Gateway installation. For example, you can use the installer to restore missing Easysoft JDBC-Access Gateway files or registry keys. To do this:

In the Windows Taskbar, enter Add or remove programs in the Windows Search box.
Select Easysoft JDBC-Access Gateway in the list, and then choose Repair.

Uninstalling on Windows

This section explains how to remove the Easysoft JDBC-Access Gateway from your system.

Removing the Easysoft JDBC-Access Gateway

In the Windows Taskbar, enter Add or remove programs in the Windows Search box.
Select Easysoft JDBC-Access Gateway in the list, and then choose Uninstall.

Easysoft product licenses are stored in the Windows registry. When you uninstall, your licenses are not removed, so you do not need to relicense the product if you reinstall or upgrade.

Connecting to your Access database

Registering the Easysoft JDBC-Access Gateway

To register the Easysoft JDBC-Access Gateway JDBC driver, your Java application must specify the class easysoft.sql.esMdbDriver. For example:

Class.forName("easysoft.sql.esMdbDriver");

To make this class available, add the Easysoft JDBC-Access Gateway client (esmdb.jar) to the system-wide classpath or copy the client to a directory that’s already on the system-wide classpath or your application’s internal classpath.

The connection URL

When the Easysoft JDBC-Access Gateway JDBC driver is registered, you can establish a connection by using a connection URL and the getConnection method of the DriverManagerclass. For example:

String connectionUrl = "jdbc:easysoft:mdb?DBQ=C:/Users/Public/Northwind.mdb";
Connection con = DriverManager.getConnection(connectionUrl);

To establish a connection with the Easysoft JDBC-Access Gateway, use a connection URL of the form:

jdbc:easysoft:mdb?DBQ=<path>[;<odbc-driver-attribute>=<value>]

where:

<path> is the path to the Access database (.mdb).
<odbc-driver-attribute> is an Access ODBC driver attribute.

You can retrieve the available Access ODBC driver attributes along with a description for each attribute by using the getPropertyInfo method of the Driver class. For example:

public static void driverProperties() {

    // Replace the DBQ value with the path to your Access database.
    String connectionUrl = "jdbc:easysoft:mdb?" +
        "DBQ=C:/Northwind/BlankII.mdb";
    Driver driver = null;
    DriverPropertyInfo props[] = null;

    try {
        Class.forName("easysoft.sql.esMdbDriver");
        driver = DriverManager.getDriver(connectionUrl);
        props = driver.getPropertyInfo(connectionUrl, new Properties());
        System.out.println("JDBC URL Attributes");
        for (int i = 0; i < props.length; i++) {
            System.out.print("\t" + props[i].name);
            System.out.print(" = ");
            System.out.print(props[i].value);
            System.out.print(" : ");
            System.out.println(props[i].description + ".");
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
}

Example connection URLs

Opens an Access database and enables Jet 4.0 features:

jdbc:easysoft:mdb?DBQ=C:/Users/Public/Northwind.mdb;ExtendedAnsiSQL=True

Opens an Access database that’s stored in a shared folder:

jdbc:easysoft:mdb?DBQ=//mymachine/myshare/Sales.accdb

Opens a password-protected Access database from a mapped network drive:

jdbc:easysoft:mdb?DBQ=Z:/Orgdata.mdb;PWD=p455w0rd

Tracing

This section describes how to enable tracing when using the Easysoft JDBC-Access Gateway.

To help resolve issues and problems with the Easysoft JDBC-Access Gateway, you may need to enable JDBC tracing (also known as logging). This can be a very useful debugging aid, but it should be remembered that tracing will adversely affect performance, and so should be turned off when you have resolved your problem. You turn tracing on by using one of the following methods:

The DriverManager.setLogWriter method lets you specify a PrintWriter object that’s used to log any JDBC-related information. For example:
```
try {
    Class.forName("easysoft.sql.esMdbDriver");
    DriverManager.setLogWriter(new PrintWriter(System.out));
}
```
Alternatively, if you use a DataSource object to get a connection, you can use the DataSource.setLogWriter method to turn on JDBC tracing. For example:
```
try {
    DataSource ds = (DataSource) envCtx.lookup("jdbc/Northwind");
    ds.setLogWriter(new PrintWriter(System.out));
}
```

The Easysoft JDBC-Access Gateway communicates with the Microsoft ODBC driver directly rather than through the Microsoft ODBC Driver Manager. For this reason, the ODBC Driver Manager tracing facility, accessible from the ODBC Data Source Administrator, can’t be used to log Easysoft JDBC-Access Gateway activity. Error messages returned by the ODBC driver are returned through the JDBC tracing mechanism however.