Mimer JDBC Driver 2.2 Guide

Contents

Introduction

The Mimer JDBC Driver provides access to Mimer databases from Java applications and applets. The driver is a type 4 driver, which means that the driver is written in 100% Java. This allows the driver to be downloaded in applets.

Related links


How to set up the Mimer JDBC Driver

The package

The Mimer JDBC package includes the following:

About the Mimer JDBC Driver version numbering: the major version number is equal to the major version number of the JDBC specification that the driver supports, the minor version number is the release number of the driver.

Requirements

The Mimer database server accessed by using the Mimer JDBC Driver must be of version 8.2.2 or later. See the Mimer download web page.

The Java environment must support at least JDK 1.2.


Using the Mimer JDBC Driver

Loading the driver

To be able to use the Mimer JDBC Driver, it must be loaded into the Java environment. To achieve this, a program loads a driver explicitly by calling the Class.forName method with the driver class as the parameter. The name of the Mimer driver class is com.mimer.jdbc.Driver (see the "JDBC application example" below). The driver is then located by the Java environment with a search along the class path, defined in the CLASSPATH environment variable.

The CLASSPATH environment variable informs the Java environment where to find Java class files, such as those delivered with the Mimer JDBC Driver and any other class files used by the applications. The Mimer JDBC Driver jar file, including the directory specification, should be added to the Java class path, as can be seen in the following examples:

Unix style:

  # echo $CLASSPATH
  CLASSPATH=.:/usr/lib/mimjdbc-2_2.jar

Windows style:

  % set
  CLASSPATH=.;D:\MIMJDBC-2_2.JAR

Besides defining the CLASSPATH environment variable explicitly, it can also be defined for a specific session when executing the application. See the following example:

  java -classpath /usr/lib/mimjdbc-2_2.jar JdbcApplication

Connecting to a Mimer database

URL syntax

The following URL syntax should be used when connecting to Mimer:

  jdbc:mimer:[URL-field-list][property-list]

...where the URL-field-list syntax is as follows (all items are optional, but to connect without specifying a database is rather unpredictable. A host specification, with or without a user specification, is introduced by '//' and a database specification is introduced by '/'):

  [//[user[:password]@]host[:port]] [/database]

...and where the property-list syntax is as follows (it must have a leading question mark ('?') and if several properties are defined they should be divided by ampersands ('&')):

  ?property=value[&property=value[&property=value]]

The following properties are known to the driver:

URL examples

The following examples describe URL usage. Wherever suitable, both a field and a property based URL syntax will be given (or a combined one):

Specifying a database

  jdbc:mimer:/customers

  jdbc:mimer:?databaseName=customers

Connects to the customers database at the default host localhost using the default port 1360.

Specifying node and database

  jdbc:mimer://my_node.mimer.se/customers

  jdbc:mimer:?databaseName=customers&serverName=my_node.mimer.se

  jdbc:mimer://my_node.mimer.se?databaseName=customers

Connects to the customers database at the host my_node.mimer.se using the default port 1360.

Specifying Mimer-user, node and database

  jdbc:mimer://SYSADM@my_node.mimer.se/customers

  jdbc:mimer:?databaseName=customers&serverName=my_node.mimer.se&user=SYSADM

Connects to the customers database at the host my_node.mimer.se as user SYSADM using the default port 1360.

Specifying Mimer-user and password, node, port number and database

  jdbc:mimer://SYSADM:SYSPW@my_node.mimer.se:1366/customers

  jdbc:mimer:?serverName=my_node.mimer.se&portNumber=1366&user=SYSADM&password=SYSPW&databaseName=customers

Connects to the customers database at the host my_node.mimer.se using the port 1366. Database login will be performed using the SYSADM user and the SYSPW password.

JDBC Application example

The example Java program below creates a result set containing all rows of the data dictionary view INFORMATION_SCHEMA.TABLES, then each row is read and displayed on the standard output. (In the example, the username and password are given separately using the DriverManager.getConnection method, i.e. not given in the URL specification):

import java.sql.*;

class Example
{
    public static void main(String[] args)
    {
        try {
            Class.forName("com.mimer.jdbc.Driver");
            String url = "jdbc:mimer://my_node.mimer.se/customers";
            Connection con = DriverManager.getConnection(url, "SYSADM", "SYSPW");
            Statement stmt = con.createStatement();
            String sql = "select TABLE_SCHEMA,TABLE_NAME,TABLE_TYPE from INFORMATION_SCHEMA.TABLES";
            ResultSet rs = stmt.executeQuery(sql);
            while (rs.next()) {
                String schema = rs.getString(1);
                String name = rs.getString(2);
                String type = rs.getString(3);
                System.out.println(schema + "  " + name + "  " + type);
            }
            rs.close();
            stmt.close();
            con.close();
        } catch (SQLException e) {
            System.out.println("SQLException!");
            while (e != null) {
                System.out.println("SQLState  : " + e.getSQLState());
                System.out.println("Message   : " + e.getMessage());
                System.out.println("ErrorCode : " + e.getErrorCode());
                e = e.getNextException();
                System.out.println("");
            }
        } catch (Exception e) {
            System.out.println("Other Exception");
            e.printStackTrace();
        }
    }
}

Another way to provide connection properties is to supply a java.util.Properties object to the DriverManager.getConnection method.

(The example program above is similar to the simple example program written in embedded SQL that is included in the standard Mimer database server distribution.)

Using the driver from applets

If the example program is to be used as an applet it must be slightly modified, as can be seen in the following example:

import java.sql.*;
import java.applet.*;
import java.awt.*;

public class ExampleApplet extends java.applet.Applet {
    public void init() {
        resize(1200, 600);
    }

    public void paint(Graphics g) {
        int row = 1;
        g.drawString("Listing tables:", 20, 10 * row++);
        try {
            Class.forName("com.mimer.jdbc.Driver");
            String url = "jdbc:mimer://my_node.mimer.se/customers";
            Connection con = DriverManager.getConnection(url, "SYSADM", "SYSPW");
            Statement stmt = con.createStatement();
            String sql = "select TABLE_SCHEMA,TABLE_NAME,TABLE_TYPE from INFORMATION_SCHEMA.TABLES";
            ResultSet rs = stmt.executeQuery(sql);
            while (rs.next()) {
                String schema = rs.getString(1);
                String name = rs.getString(2);
                String type = rs.getString(3);
                g.drawString(schema + "  " + name + "  " + type, 50, 10 * row++);
            }
            rs.close();
            stmt.close();
            con.close();
        } catch (SQLException e) {
            g.drawString("SQLException!", 20, 10 * row++);
            while (e != null) {
                g.drawString("SQLState  : " + e.getSQLState(), 20, 10 * row++);
                g.drawString("Message   : " + e.getMessage(), 20, 10 * row++);
                g.drawString("ErrorCode : " + e.getErrorCode(), 20, 10 * row++);
                e = e.getNextException();   
                g.drawString("", 20, 10*row++);
            }
        } catch (Exception e) {
            g.drawString("Other Exception!", 20, 10 * row++);
            g.drawString(e.toString(), 20, 10 * row++);
        }
    }
}

To use the Mimer JDBC Driver in a Java applet, the driver jar file should be copied to the location of the other Java classes of the applet. This directory must be accessible by the web server. The driver jar file name should be given as the ARCHIVE parameter of the applet tag in the HTML file, as can be seen in the following example:


<html>
<head>
<title> The Example Applet 
</head>
<body>
Example Applet:
<applet archive="mimjdbc-2_2.jar" code="ExampleApplet.class" width=800 height=600>
</applet>
</body>
</html>

The applet is executed by accessing the HTML file from a browser:

http://my_node/ExampleApplet.html

Note that there is a security restriction for Java applets, which states that a network connection can only be opened to the host from which the applet itself was downloaded. This means that the web server distributing the applet code and the database server must reside on the same host computer.


Characteristics

Driver specifics

It is possible for an application to get statistical information from a database access. When a MimConnection object is closed, a statistics report is sent over the DriverManager log stream. The report contains the following information:

The Mimer JDBC driver is thread safe and uses one lock per connection. Thus, to achieve higher concurrency, the application should try to use several connections.

The driver is implemented to perform automatic prefetch, i.e. whenever a resultSet is created, a buffer is filled with several successive rows. This is an optimization for throughput, allowing more data to be fetched to the client in the single communication made. The flip side of the coin is that the response time, i.e. the elapsed time before the first record will show up, may be increased.

Both the JDBC specification and the Java language lack support for the INTERVAL data types. The methods getString and setString can be applied for values accessed by the driver from database columns containing INTERVAL data.

By using the java com.mimer.jdbc.Driver command, it is possible to view characteristics of a specific driver and the current environment. Used without any arguments, it will display its usage information:

  java com.mimer.jdbc.Driver
  Usage: com.mimer.jdbc.Driver options

  where options include:
      -version     Display driver version
      -sysprop     Display all system properties
      -errors      List all JDBC error codes
      -ping url    Test the database at the specified url

The following is an example that uses the -version option:

  java com.mimer.jdbc.Driver -version
  Mimer JDBC driver version 2.2

Trace facility

The Mimer JDBC Driver performs minimal logging activities to keep the driver size small and to optimize performance. Instead, a separate trace driver is available.

This trace driver is a full JDBC Driver that covers all of JDBC by calling the matching routines of the traced JDBC Driver. The trace driver produces a log of every JDBC call the application makes, and also measures the elapsed time for each call. The trace log can be written to a file, or can be displayed directly in a window.

The trace driver is invoked by using a special URL that contains the URL of the driver to be traced. See the Mimer JDBC Trace Driver Guide.


Programming considerations

Close objects

Although Java has automatic garbage collection it is essential to close JDBC objects, such as ResultSets, Statements and Connections, when done with them. By performing correct close operations, the application gains better control over resources. Without proper close operations, resources are kept allocated in the database server until garbage collection is triggered, which may lead to exhaustion of server resources.

Performance

One of the main issues when trying to increase performance is to reduce the network traffic. For example, the server can be used to provide more accurate data instead of having a large, unqualified amount of data passed over to the client side where the application must sort out the specific data of interest. This can be achieved by using more developed SQL statements or by using stored procedures (PSM). Note that, as said before, ResultSets are already optimized in this respect by the driver itself (using array fetch). If it is known that only a small number of records are to be fetched, then the setMaxRows method can be used to optimize the response time, i.e. to avoid an array fetch.

It is also possible to reduce the number of network requests by using batched statements. If, for example, 20 conventional calls to Statement.execute() is replaced by 20 calls to Statement.addBatch() followed by a Statement.executeBatch() call, the result will be that 20 server network requests are replaced by a single network request. If the execution speed is constrained by network latencies (which is often the case), this simple change may give a twenty-fold performance improvement!

Another performance issue is to avoid "compilations" of SQL statements. Such compilations are done whenever invoking the Statement.executeXXX methods. Instead, use parameterized precompiled statements, i.e. PreparedStatement, whenever possible.

Note that batched statements for PreparedStatement and CallableStatement differ from the implementation for the Statement class. When using PreparedStatement or CallableStatement, only a single SQL statement can be used in a batch. The addBatch() call (without argument) adds a set of parameters to the batch. The use of batches allows the same SQL statement to called repeatedly with different parameters in a single network request.

Transactions

By default, each SQL statement forms a transaction of its own, i.e. autocommit is enabled. If using explicit transaction management, it should be pointed out that if such a program is to be used in an Enterprise Java Beans (EJB) server it must be modified, since transaction management is provided by the EJB environment.


Change history

Changes in 2.2

The following problems were removed and enhancements were introduced in 2.2.

Changes in 2.1

The following changes were introduced in 2.1

Changes in 2.0

The following major changes were introduced in 2.0

Changes in 1.3

The following major change were introduced in 1.3:

Changes in 1.2

The following major changes were introduced in 1.2:

Unsupported Features

The following features are not supported in this release of the driver. They will be supported in a future release: