Package com.mckoi.database.control

## Class DBSystem

- java.lang.Object
- - com.mckoi.database.control.DBSystem

    public final class DBSystem
    extends java.lang.Object

An object used to access and control a single database system running in the current JVM. This object provides various access methods to safely manipulate the database, as well as allowing server plug-ins. For example, a TCP/IP JDBC server component might be plugged into this object to open the database to remote access.

Author:
  Tobias Downer

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `close()` Closes this database system so it is no longer able to process queries.
`DBConfig` `getConfig()` Returns an immutable version of the database system configuration.
`java.sql.Connection` `getConnection​(java.lang.String username, java.lang.String password)` Makes a connection to the database and returns a java.sql.Connection object that can be used to execute queries on the database.
`java.sql.Connection` `getConnection​(java.lang.String schema, java.lang.String username, java.lang.String password)` Makes a connection to the database and returns a java.sql.Connection object that can be used to execute queries on the database.
`Database` `getDatabase()` Returns the com.mckoi.database.Database object for this control.
`void` `setDeleteOnClose​(boolean status)` Sets a flag that causes the database to delete itself from the file system when it is shut down.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Method Detail

#### getConfig

    public DBConfig getConfig()

Returns an immutable version of the database system configuration.

#### getDatabase

    public Database getDatabase()

Returns the com.mckoi.database.Database object for this control. This methods only works correctly if the database engine has successfully been initialized.

This object is generally not very useful unless you intend to perform some sort of low level function on the database. This object can be used to bypass the SQL layer and talk directly with the internals of the database.

Returns:
  a Database object that can be used to access the database system at a low level.

#### getConnection

    public java.sql.Connection getConnection​(java.lang.String schema,
                                             java.lang.String username,
                                             java.lang.String password)
                                      throws java.sql.SQLException

Makes a connection to the database and returns a java.sql.Connection object that can be used to execute queries on the database. This is a standard connection that talks directly with the database without having to go through any communication protocol layers.

For example, if this control is for a Mckoi database server, the java.sql.Connection returned here does not go through the TCP/IP connection. For this reason certain database configuration constraints (such as number of concurrent connection on the database) may not apply to this connection.

The java.sql.Connection returned here acts exactly as an object returned by a java.sql.MDriver object.

An SQLException is thrown if the login fails.

Parameters:
  `schema` - the initial database schema to start the connection in.
  `username` - the user to login to the database under.
  `password` - the password of the user.
Returns:
  a JDBC java.sql.Connection used to access the database.
Throws:
  `java.sql.SQLException` - if authentication of the user fails.

#### getConnection

    public java.sql.Connection getConnection​(java.lang.String username,
                                             java.lang.String password)
                                      throws java.sql.SQLException

Makes a connection to the database and returns a java.sql.Connection object that can be used to execute queries on the database. This is a standard connection that talks directly with the database without having to go through any communication protocol layers.

For example, if this control is for a Mckoi database server, the java.sql.Connection returned here does not go through the TCP/IP connection. For this reason certain database configuration constraints (such as number of concurrent connection on the database) may not apply to this connection.

The java.sql.Connection returned here acts exactly as an object returned by a java.sql.MDriver object.

An SQLException is thrown if the login fails.

Parameters:
  `username` - the user to login to the database under.
  `password` - the password of the user.
Returns:
  a JDBC java.sql.Connection used to access the database.
Throws:
  `java.sql.SQLException` - if authentication of the user fails.

#### setDeleteOnClose

    public final void setDeleteOnClose​(boolean status)

Sets a flag that causes the database to delete itself from the file system when it is shut down. This is useful if an application needs a temporary database to work with that is released from the file system when the application ends.

By default, a database is not deleted from the file system when it is closed.

NOTE: Use with care - setting this flag will cause all data stored in the database to be lost when the database is shut down.

#### close

    public void close()

Closes this database system so it is no longer able to process queries. A database may be shut down either through this method or by executing a query that shuts the system down (for example, 'SHUTDOWN').

When a database system is closed, it is not able to be restarted again unless a new DBSystem object is obtained from the DBController.

This method also disposes all resources associated with the database system (such as threads, etc) so that it may be reclaimed by the garbage collector.

When this method returns this object is no longer usable.