Home / Documentation / FAQ / Support / Download Database Control API

### Database Control API Index

> 1. Control API Introduction
> 2. The Basics - Starting and Closing a database session
> 3. Binding a TCP/IP JDBC server to a database session
> 4. Advanced uses of the Control API

1. Control API Introduction

> The Control API provides a programmatic way to configure and manage one or more Mckoi database sessions within a Java environment. It is intended for developers who need more control or access to a Mckoi database session than the JDBC API alone can provide. It is also useful to developers who are writing database access APIs to Mckoi. The Control API is only available in Mckoi SQL Database.

> This section covers common uses of the Control API. It is recommended that developers who wish to become more familiar with this API generate the JavaDoc documentation. The API package is `com.mckoi.database.control`.

2. The Basics - Starting and Closing a database session

> The basic steps to using the Control API are as follows;

> 1. Create a database configuration - a `com.mckoi.database.control.DBConfig` object.
> 2. Get the `com.mckoi.database.control.DBController` object.
> 3. Use the `DBController` to either create or start a database session - a `com.mckoi.database.control.DBSystem` object.
> 4. Use the `DBSystem` object to access/modify the database. You can use `DBSystem` to create JDBC connections, or access the database in other ways.
> 5. Close the `DBSystem` object to disconnect the session and release the resources in the Java environment used by the session.

> Note that it is not necessary to base your database configuration on a 'db.conf' file when using the Control API. It is possible to specify the database configuration directly from Java code.

> Below is an example of using the Control API to detect the existence of a database and if it's not found create it, or connect to it if it does exist. The example also creates a JDBC connection and executes a simple query.

>     import com.mckoi.database.control.*;
>     import java.sql.*;
>     ....

>       // First create a database configuration.  We use this to
>       // set database properties such as if the database should
>       // be case insensitive, read only, etc.
>       DefaultDBConfig config = new DefaultDBConfig();
>       // Set the path of the database in the file system.
>       config.setDatabasePath("c:\\my_mckoi_database\\");
>       // Set the path of the logs in the file system.
>       config.setLogPath("c:\\my_mckoi_database\\logs\\");

>       // Get the controller interface
>       DBController control = DBController.getDefault();

>       // This will be the database session
>       DBSystem session;
>       // Does the database exist already?
>       if (control.databaseExists(config)) {
>         // If it exists then start the database session
>         session = control.startDatabase(config);
>       }
>       else {
>         // If it doesn't exist then create the database.
>         // Note we need to set the admin username and password.
>         session = control.createDatabase(config, "user", "pass");
>       }

>       // Create a local JDBC connection to the database (logging in
>       // as the given username and password).
>       Connection connection = session.getConnection("user", "pass");

>       // ... do something with the database through the JDBC
>       //     interface.

>       // For example, lists the tables in the database.
>       ResultSet all_tables =
>            connection.createStatement().executeQuery("SHOW TABLES");
>       while (all_tables.next()) {
>         System.out.println(all_tables.getString(1));
>       }

>       // ... when finished remember to close the connection and
>       //     the database

>       // Close the JDBC connection.
>       connection.close();
>       // Close the database session (frees up the resources)
>       session.close();

> The Control API provides a number of other important features. The API allows for the creation of multiple light-weight JDBC connections to a single session, and for an application to connect to multiple databases in the file system from inside a single Java environment. The Control API is also multi-thread safe so an application can construct and talk to multiple JDBC connections in a multi-threaded application.

3. Binding a TCP/IP JDBC server to a database session

> The Control API can be used to create one or more JDBC servers on the local machine. After a JDBC server has started a Mckoi JDBC client can remotely connect to the database session.

> The code below demonstrates starting a TCP/IP JDBC server on port 9888 of the local machine bound to the given database session.

>       DBSystem session = ....

>       // Construct the TCP/IP JDBC Server on port 9888
>       TCPJDBCServer server = new TCPJDBCServer(session, 9888);
>       // Start the server - returns immediately.
>       server.start();

> Connecting to the database session remotely is then simply a matter of supplying the correct JDBC URL in the client application. For example, if the local machine address is `mydatabase.davescomputer.com` and you are using the code above, the JDBC URL to connect to the database would be `mckoi:jdbc://mydatabase.davescomputer.com:9888/`.

4. Advanced uses of the Control API

> Low-level access to a database system is possible through the Control API. The API exposes the `com.mckoi.database.Database` object that allows direct access to the core database system facilities. The `com.mckoi.database.Database` object can be used to create connections and modify/access data in the database bypassing all higher level SQL parsing/planning and evaluation.

> It is recommended that a developer generates the JavaDoc documentation or reads the source code if they wish to become familiar with the core design. A useful example of using the low-level access facilities is shown below. The example generates a backup copy of the database while it is still active.

>     import java.io.*;
>     ....

>       DBSystem session = ....

>       session.getDatabase().liveCopyTo(
>                    new File("/home/databases/mckoi_backups/1/"));

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