Home / Documentation / FAQ / Support / Download Mckoi JDBC(TM) Driver

### Mckoi JDBCTM Driver Index

> 1. The JDBCTM Interface
> 2. Installing the Driver
> 3. The Connection URL
> 4. How ResultSet works
> 5. Driver Concurrency

1. The JDBCTM Interface

> JDBCTM is the standard Java interface for connecting and communicating with a relational database. Mckoi SQL Database provides an implementation of the JDBC 2.0 standard. The driver is a type 4 driver which means it is written entirely in Java.

> The Mckoi JDBC driver currently operates in two modes - embedded and client/server mode. In embedded mode the JDBC driver starts the database engine within the current Java Virtual Machine and connects to it as a local user. Embedded mode is designed for stand alone applications that require database functionality. In client/server mode the JDBC driver uses TCP/IP to communicate with a Mckoi database server running on a remote machine.

> This chapter provides details of the Mckoi JDBC driver implementation. More general information about the JDBC API can be found at http://www.javasoft.com/jdbc/.

2. Installing the Driver

> Before the JDBC driver can be used it must be installed in your Java application. Installing the driver is a simple procedure. First ensure that either the `mckoidb.jar` or `mkjdbc.jar` file is included in your Java classpath. If you wish to embed the database engine directly into your application you need to include `mckoidb.jar` in your classpath. If you are connecting to a remote Mckoi server you should include `mkjdbc.jar`.

> Next install the driver by adding the following lines to your application's initialization code;

>       try {
>         Class.forName("com.mckoi.JDBCDriver");
>       }
>       catch (Exception e) {
>         // ... [ Handle error ]
>       }

> The above code will register the JDBC driver with your application so you can create new connections to the database by using the `java.sql.DriverManager` object from the JDBCTM API. If the above section of code generates an error the most likely cause is that you do not have either `mckoidb.jar` or `mkjdbc.jar` in your classpath.

3. The Connection URL

> When using the JDBCTM API to connect to a Mckoi database, a specially formatted string called the Connection URL is required to tell the driver where the database is located. The Connection URL is passed to the `getConnection` method in the `java.sql.DriverManager` class of the JDBCTM API. The Mckoi JDBCTM driver understands two types of URL specifications;

> `jdbc:mckoi://host[:port][/schema]/`

> This URL tells the driver to make a connection using TCP/IP to a database running at the given host. The :port is optional and if not given the driver will attempt to connect to the default port of 9157. The /schema part is also optional. If the schema part is included, the JDBCTM driver will attempt to initialize the connection in the given schema after successfully connecting to the database. If the schema is not included in the URL, the engine will attempt to initialize the connection in a schema with the same name as the username. If the engine is unable to find the schema, the connection will default to the '`APP`' schema.

> Below is an example that demonstrates this type of URL;

> `jdbc:mckoi://mydatabase.mydomain.org/MYSCHEMA/`

> The above JDBC URL will attempt to connect to a Mckoi database server running on the host at 'mydatabase.mydomain.org' on the default port (9157), and to change the schema to `MYSCHEMA` on successful connection.

> The second type of URL specification is for connecting to a database embedded inside your application;

> `jdbc:mckoi:local://path_to_database_config[/schema][?var1=value1&var2=value2&...]`

> This type of URL tells the JDBC driver to start up an instance of the database engine in the current Java Virtual Machine and establish a connection to it. The database is started using information in the configuration file located by path_to_database_config. All the configuration properties for the local database may be overridden by the URL encoded variables after the ?. For example,

> `jdbc:mckoi:local://c:/mydb/myconfig.conf?read_only=enabled&log_path=c:/mynewlogdir/`

> The above example will tell the local database to start in read-only mode in addition to overwriting the location of the log directory.

> As well as establishing a connection to an already existing database, a new database can be created using the `jdbc:mckoi:local://` URL specification. This offers a useful way of programatically creating and initializing a database that will later be connected to by either an embedded engine or made available via a Mckoi database server. To create a database simply add `create=true` to the URL encoded variables. For example,

> `jdbc:mckoi:local://c:/mydb/myconfig.conf?create=true`

> If the database already exists an error is generated and a connection will not be established. If you would like the JDBC driver to create a new database if one is not found, or if a database is found establish a connection to it, add `create_or_boot=true` to the JDBC URL.

> The following Java code is an example of using a Connection URL to establish a connection to a database server running on localhost. In the example below the user name and password are 'test_user' and 'test_pass'.

>     import java.sql.*;

>       ...

>       String username = "test_user";
>       String password = "test_pass";
>       try {
>         Connection connection = DriverManager.getConnection(
>                       "jdbc:mckoi://localhost/", username, password);
>       }
>       catch (SQLException e) {
>         // ... [ Handle connection problem ]
>       }

4. How ResultSet works

> When a query is executed using a JDBCTM Statement or PreparedStatement the result of the query is made available to your application via a JDBCTM ResultSet. The Mckoi engine features a sophisticated scrollable result set implementation that is mostly transparent to the developer but is interesting enough to warrant this section in the documentation.

> When the result of a query is found, the Mckoi JDBCTM driver does not download the entire result from the database. The content of a ResultSet is fetched in small blocks (or pages) when an application attempts to read data from the ResultSet object. By default the Mckoi JDBCTM driver fetches rows from the database in blocks of 32 rows at a time (this can be changed by using the `ResultSet.setFetchSize` method). Data fetched from the database is cached locally by the driver.

> This design allows an application to efficiently construct views of large data sets. An example of where this feature is useful is a servlet that displays the result of a query but has a limit of 25 records per web page. The servlet author would simply need to move the ResultSet index to the record being displayed at the top of the web page and read the contents of the ResultSet to the last record displayed on the page. Even though the number of rows in the ResultSet may be in the thousands, only the rows that were read are fetched from the server.

> Another practical example of the benfits of a cached scrollable ResultSet is the `com.mckoi.tools.JDBCQueryTool` program used in the tutorial section. `JDBCQueryTool` uses an implementation of `javax.swing.table.TableModel` to provide a view of the query result that only fetches data in a row when the row is being displayed on screen. To see how the TableModel implementation in JDBCQueryTool works, browse the source code and find the file `/src/com/mckoi/jfccontrols/ResultSetTableModel.java`.

> You may be asking yourself what happens if the data in a ResultSet is updated or deleted before it has been fetched from the database. Rest assured the engine handles this situation and will return the data that was the result at the time the query was made.

5. Driver Concurrency

> The Mckoi JDBC driver is designed for multi-threaded access but only if used in the correct way. The `ResultSet`, `Statement` and `PreparedStatement` objects are not multi-thread safe and instances of these objects may only safely be used by one thread at a time. The `Connection` object, however, is multi-thread safe. This means an application is able to safely pull `Statement` and `PreparedStatement` objects from a `Connection` and distribute them among multiple threads. A `Statement/ResultSet` being used in one thread will not interfere with a different `Statement/ResultSet` running concurrently on a second thread.

Last Updated: Mon Aug 16 00:27:18 PDT 2004 Mckoi SQL Database Copyright © 2000 - 2004 Diehl and Associates, Inc. All rights reserved.