Package com.mckoi.database

## Class Database

- java.lang.Object
- - com.mckoi.database.Database

All Implemented Interfaces:
  `DatabaseConstants`

    public final class Database
    extends java.lang.Object
    implements DatabaseConstants

The representation of a single database in the system. A database is a set of schema, a set of tables and table definitions of tables in the schema, and a description of the schema.

This class encapsulates the top level behaviour of a database. That is of creating itself, initializing itself, shutting itself down, deleting itself, creating/dropping a table, updating a table. It is not the responsibility of this class to handle table behaviour above this. Top level table behaviour is handled by DataTable through the DatabaseConnection interface.

The Database object is also responsible for various database management functions such a creating, editing and removing users, triggers, functions and services.

Author:
  Tobias Downer

### Field Summary

Fields
`static java.lang.String` `DEFAULT_SCHEMA` The name of the default schema.
`static java.lang.String` `INTERNAL_SECURE_USERNAME` The username of the internal secure user.
`static java.lang.String` `JDBC_SCHEMA` The name of the schema that contains JDBC helper tables.
`static java.lang.String` `LOCK_GROUP` The name of the lock group.
`static TableName` `NEW_TRIGGER_TABLE` The NEW table used inside a triggered procedure to represent a triggered row after the operation occurs.
`static TableName` `OLD_TRIGGER_TABLE` The OLD table used inside a triggered procedure to represent a triggered row before the operation occurs.
`static java.lang.String` `SCHEMA_MANAGER_GROUP` The name of the schema manager group.
`static java.lang.String` `SECURE_GROUP` THe name of the secure access group.
`static TableName` `SYS_DATA_TRIGGER` The system internally generated 'sUSRDataTrigger' table.
`static TableName` `SYS_DB_STATISTICS` The system internally generated 'sUSRDatabaseStatistics' table.
`static TableName` `SYS_FUNCTION` The function table.
`static TableName` `SYS_FUNCTIONFACTORY` The function factory table.
`static TableName` `SYS_GRANTS`
`static TableName` `SYS_LABEL` The label table.
`static TableName` `SYS_PASSWORD` The password privs and grants table.
`static TableName` `SYS_SERVICE` The services table.
`static TableName` `SYS_TABLE_COLUMNS` The system internally generated 'sUSRTableColumns' table.
`static TableName` `SYS_TABLE_INFO` The system internally generated 'sUSRTableInfo' table.
`static TableName` `SYS_USERCONNECT`
`static TableName` `SYS_USERPRIV`
`static TableName` `SYS_VIEW` The view table.
`static java.lang.String` `SYSTEM_SCHEMA` The name of the system schema that contains tables refering to system information.
`static java.lang.String` `USER_MANAGER_GROUP` The name of the user manager group.

### Fields inherited from interface com.mckoi.database.DatabaseConstants

`MAX_DATABASE_NAME_LENGTH, MAX_PASSWORD_LENGTH, MAX_PRIVGROUP_NAME_LENGTH, MAX_TABLE_NAME_LENGTH, MAX_USER_NAME_LENGTH`

### Constructor Summary

Constructors
`Database​(DatabaseSystem system, java.lang.String name)` The Constructor.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addUserToGroup​(DatabaseQueryContext context, java.lang.String username, java.lang.String group)` Adds the user to the given group.
`void` `alterUserPassword​(DatabaseQueryContext context, java.lang.String username, java.lang.String password)` Alters the password of the user but otherwise does not change any information about the user.
`User` `authenticateUser​(java.lang.String username, java.lang.String password, java.lang.String connection_string)` Tries to authenticate a username/password against this database.
`boolean` `canUserAlterTableObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can alter a table or view with the given name, otherwise returns false.
`boolean` `canUserCompactTableObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can compact a table with the given name, otherwise returns false.
`boolean` `canUserCreateAndDropSchema​(DatabaseQueryContext context, User user, java.lang.String schema)` Returns true if the user is permitted to create and drop schema's in the database, otherwise returns false.
`boolean` `canUserCreateAndDropUsers​(DatabaseQueryContext context, User user)` Returns true if the user is permitted to create, alter and drop user information from the database, otherwise returns false.
`boolean` `canUserCreateProcedureObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can create a procedure with the given name, otherwise returns false.
`boolean` `canUserCreateSequenceObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can create a sequence with the given name, otherwise returns false.
`boolean` `canUserCreateTableObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can create a table or view with the given name, otherwise returns false.
`boolean` `canUserDeleteFromTableObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can delete from a table or view with the given name and given columns, otherwise returns false.
`boolean` `canUserDropProcedureObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can drop a procedure with the given name, otherwise returns false.
`boolean` `canUserDropSequenceObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can drop a sequence with the given name, otherwise returns false.
`boolean` `canUserDropTableObject​(DatabaseQueryContext context, User user, TableName table)` Returns true if the user can drop a table or view with the given name, otherwise returns false.
`boolean` `canUserExecuteStoredProcedure​(DatabaseQueryContext context, User user, java.lang.String procedure_name)` Returns true if the user is allowed to execute the given stored procedure.
`boolean` `canUserInsertIntoTableObject​(DatabaseQueryContext context, User user, TableName table, Variable[] columns)` Returns true if the user can insert into a table or view with the given name and given columns, otherwise returns false.
`boolean` `canUserSelectFromTableObject​(DatabaseQueryContext context, User user, TableName table, Variable[] columns)` Returns true if the user can select from a table or view with the given name and given columns, otherwise returns false.
`boolean` `canUserShutDown​(DatabaseQueryContext context, User user)` Returns true if the user can shut down the database server.
`boolean` `canUserUpdateTableObject​(DatabaseQueryContext context, User user, TableName table, Variable[] columns)` Returns true if the user can update a table or view with the given name and given columns, otherwise returns false.
`boolean` `convertToCurrent​(java.io.PrintStream out, java.lang.String admin_username)` Functionality for converting and old database format to the existing format.
`void` `create​(java.lang.String username, java.lang.String password)` Creates and sets up a new database to an initial empty state.
`java.lang.Object` `createEvent​(java.lang.Runnable runner)` Creates an event for the database dispatcher.
`DatabaseConnection` `createNewConnection​(User user, DatabaseConnection.CallBack call_back)` Returns a new DatabaseConnection instance that is used against this database.
`void` `createUser​(DatabaseQueryContext context, java.lang.String username, java.lang.String password)` Creates and adds a new user to this database.
`DebugLogger` `Debug()` Returns the DebugLogger implementation from the DatabaseSystem.
`void` `deleteAllUserGroups​(DatabaseQueryContext context, java.lang.String username)` Deletes all the groups the user belongs to.
`void` `deleteUser​(DatabaseQueryContext context, java.lang.String username)` Deletes the user from the system.
`void` `execute​(User user, DatabaseConnection database, java.lang.Runnable runner)` Executes database functions from the 'run' method of the given runnable instance on the first available worker thread.
`boolean` `exists()` Returns true if the database exists.
`void` `finalize()`
`Log` `getCommandsLog()` Returns the log file where commands are recorded.
`com.mckoi.database.DataCellCache` `getDataCellCache()` Returns the system DataCellCache.
`DatabaseProcedure` `getDBProcedure​(java.lang.String procedure_name, DatabaseConnection connection)` Resolves a procedure name into a DBProcedure object.
`java.lang.String` `getName()` Returns the name of this database.
`Table` `getSingleRowTable()` Returns a static table that has a single row but no columns.
`DatabaseSystem` `getSystem()` Returns the DatabaseSystem that this Database is from.
`com.mckoi.database.TriggerManager` `getTriggerManager()` Returns the system trigger manager.
`UserManager` `getUserManager()` Returns the system user manager.
`void` `grantHostAccessToUser​(DatabaseQueryContext context, java.lang.String user, java.lang.String protocol, java.lang.String host)` Grants the given user access to connect to the database from the given host address.
`java.lang.String[]` `groupsUserBelongsTo​(DatabaseQueryContext context, java.lang.String username)` Returns the list of all user groups the user belongs to.
`boolean` `hasShutDown()` Returns true if the database has shut down.
`void` `init()` Initializes the database.
`boolean` `isInitialized()` Returns true if the database is initialised.
`boolean` `isReadOnly()` Returns true if this database is in read only mode.
`void` `liveCopyTo​(java.io.File path)` Copies all the persistent data in this database (the conglomerate) to the given destination path.
`void` `postEvent​(int time, java.lang.Object event)` Posts an event on the database dispatcher.
`void` `registerShutDownDelegate​(java.lang.Runnable delegate)` Registers the delegate that is executed when the shutdown thread is activated.
`void` `setDeleteOnShutdown​(boolean status)` If the 'deleteOnShutdown' flag is set, the database will delete the database from the file system when it is shutdown.
`void` `setIsExecutingCommands​(boolean status)` Controls whether the database is allowed to execute commands or not.
`void` `setupSystemFunctions​(DatabaseConnection connection, java.lang.String admin_user)` Sets all the standard functions and procedures available to engine.
`void` `setUserLock​(DatabaseQueryContext context, User user, boolean lock_status)` Sets the lock status for the given user.
`void` `shutdown()` Cleanly shuts down the database.
`void` `startShutDownThread()` Starts the shutdown thread which should contain delegates that shut the database and all its resources down.
`Stats` `stats()` Convenience static for accessing the global Stats object.
`com.mckoi.database.StoreSystem` `storeSystem()` Returns the StoreSystem for this Database.
`boolean` `userBelongsToGroup​(DatabaseQueryContext context, java.lang.String username, java.lang.String group)` Returns true if the given user belongs to the given group otherwise returns false.
`boolean` `userExists​(DatabaseQueryContext context, java.lang.String username)` Returns true if a user exists in this database, otherwise returns false.
`void` `waitUntilShutdown()` Blocks until the database has shut down.

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

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

### Field Detail

#### SYSTEM_SCHEMA

    public static final java.lang.String SYSTEM_SCHEMA

The name of the system schema that contains tables refering to system information.

See Also:
  Constant Field Values

#### DEFAULT_SCHEMA

    public static final java.lang.String DEFAULT_SCHEMA

The name of the default schema.

See Also:
  Constant Field Values

#### JDBC_SCHEMA

    public static final java.lang.String JDBC_SCHEMA

The name of the schema that contains JDBC helper tables.

See Also:
  Constant Field Values

#### SYS_PASSWORD

    public static final TableName SYS_PASSWORD

The password privs and grants table.

#### SYS_USERCONNECT

    public static final TableName SYS_USERCONNECT

#### SYS_USERPRIV

    public static final TableName SYS_USERPRIV

#### SYS_GRANTS

    public static final TableName SYS_GRANTS

#### SYS_SERVICE

    public static final TableName SYS_SERVICE

The services table.

#### SYS_FUNCTIONFACTORY

    public static final TableName SYS_FUNCTIONFACTORY

The function factory table.

#### SYS_FUNCTION

    public static final TableName SYS_FUNCTION

The function table.

#### SYS_VIEW

    public static final TableName SYS_VIEW

The view table.

#### SYS_LABEL

    public static final TableName SYS_LABEL

The label table.

#### SYS_TABLE_COLUMNS

    public static final TableName SYS_TABLE_COLUMNS

The system internally generated 'sUSRTableColumns' table.

#### SYS_TABLE_INFO

    public static final TableName SYS_TABLE_INFO

The system internally generated 'sUSRTableInfo' table.

#### SYS_DATA_TRIGGER

    public static final TableName SYS_DATA_TRIGGER

The system internally generated 'sUSRDataTrigger' table.

#### SYS_DB_STATISTICS

    public static final TableName SYS_DB_STATISTICS

The system internally generated 'sUSRDatabaseStatistics' table.

#### OLD_TRIGGER_TABLE

    public static final TableName OLD_TRIGGER_TABLE

The OLD table used inside a triggered procedure to represent a triggered row before the operation occurs.

#### NEW_TRIGGER_TABLE

    public static final TableName NEW_TRIGGER_TABLE

The NEW table used inside a triggered procedure to represent a triggered row after the operation occurs.

#### LOCK_GROUP

    public static final java.lang.String LOCK_GROUP

The name of the lock group. If a user belongs to this group the user account is locked and they are not allowed to log into the database.

See Also:
  Constant Field Values

#### SECURE_GROUP

    public static final java.lang.String SECURE_GROUP

THe name of the secure access group. If a user belongs to this group they are permitted to perform a number of priviledged operations such as shutting down the database, and adding and removing users.

See Also:
  Constant Field Values

#### USER_MANAGER_GROUP

    public static final java.lang.String USER_MANAGER_GROUP

The name of the user manager group. Users that belong in this group can create, alter and drop users from the system.

See Also:
  Constant Field Values

#### SCHEMA_MANAGER_GROUP

    public static final java.lang.String SCHEMA_MANAGER_GROUP

The name of the schema manager group. Users that belong in this group can create and drop schema from the system.

See Also:
  Constant Field Values

#### INTERNAL_SECURE_USERNAME

    public static final java.lang.String INTERNAL_SECURE_USERNAME

The username of the internal secure user. The internal secure user is only used for internal highly privileged operations. This user is given full privs to everything and is used to manage the system tables, for authentication, etc.

See Also:
  Constant Field Values

### Constructor Detail

#### Database

    public Database​(DatabaseSystem system,
                    java.lang.String name)

The Constructor. This takes a directory path in which the database is stored.

### Method Detail

#### getName

    public java.lang.String getName()

Returns the name of this database.

#### isReadOnly

    public boolean isReadOnly()

Returns true if this database is in read only mode.

#### getCommandsLog

    public Log getCommandsLog()

Returns the log file where commands are recorded.

#### createNewConnection

    public DatabaseConnection createNewConnection​(User user,
                                                  DatabaseConnection.CallBack call_back)

Returns a new DatabaseConnection instance that is used against this database.

When a new connection is made on this database, this method is called to create a new DatabaseConnection instance for the connection. This connection handles all transactional queries and modifications to the database.

#### authenticateUser

    public User authenticateUser​(java.lang.String username,
                                 java.lang.String password,
                                 java.lang.String connection_string)

Tries to authenticate a username/password against this database. If we fail to authenticate then a 'null' object is returned, otherwise a valid User object is returned. If a valid object is returned, the user will be logged into the engine via the UserManager object (in DatabaseSystem). The developer must ensure that 'close' is called before the object is disposed (logs out of the system).

This method also returns null if a user exists but was denied access from the given host string. The given 'host_name' object is formatted in the database host connection encoding. This method checks all the values from the sUSRUserConnectPriv table for this user for the given protocol. It first checks if the user is specifically DENIED access from the given host. It then checks if the user is ALLOWED access from the given host. If a host is neither allowed or denied then it is denied.

#### userExists

    public boolean userExists​(DatabaseQueryContext context,
                              java.lang.String username)
                       throws DatabaseException

Returns true if a user exists in this database, otherwise returns false.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### createUser

    public void createUser​(DatabaseQueryContext context,
                           java.lang.String username,
                           java.lang.String password)
                    throws DatabaseException

Creates and adds a new user to this database. The User object for the user is returned.

If the user is already defined by the database then an error is generated.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### deleteAllUserGroups

    public void deleteAllUserGroups​(DatabaseQueryContext context,
                                    java.lang.String username)
                             throws DatabaseException

Deletes all the groups the user belongs to. This is intended for a user alter command for setting the groups a user belongs to.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### deleteUser

    public void deleteUser​(DatabaseQueryContext context,
                           java.lang.String username)
                    throws DatabaseException

Deletes the user from the system. This also deletes all information associated with a user such as the groups they belong to. It does not delete the privs a user has set up.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### alterUserPassword

    public void alterUserPassword​(DatabaseQueryContext context,
                                  java.lang.String username,
                                  java.lang.String password)
                           throws DatabaseException

Alters the password of the user but otherwise does not change any information about the user.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### groupsUserBelongsTo

    public java.lang.String[] groupsUserBelongsTo​(DatabaseQueryContext context,
                                                  java.lang.String username)
                                           throws DatabaseException

Returns the list of all user groups the user belongs to.

Throws:
  `DatabaseException`

#### userBelongsToGroup

    public boolean userBelongsToGroup​(DatabaseQueryContext context,
                                      java.lang.String username,
                                      java.lang.String group)
                               throws DatabaseException

Returns true if the given user belongs to the given group otherwise returns false.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### addUserToGroup

    public void addUserToGroup​(DatabaseQueryContext context,
                               java.lang.String username,
                               java.lang.String group)
                        throws DatabaseException

Adds the user to the given group. This makes an entry in the sUSRUserPriv for this user and the given group. If the user already belongs to the group then no changes are made.

It is important that any security checks for ensuring the grantee is allowed to give the user these privs are preformed before this method is called.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### setUserLock

    public void setUserLock​(DatabaseQueryContext context,
                            User user,
                            boolean lock_status)
                     throws DatabaseException

Sets the lock status for the given user. If a user account if locked, it is rejected from logging in to the database.

It is important that any security checks to determine if the process setting the user lock is allowed to do it is done before this method is called.

NOTE: Assumes exclusive lock on DatabaseConnection.

Throws:
  `DatabaseException`

#### grantHostAccessToUser

    public void grantHostAccessToUser​(DatabaseQueryContext context,
                                      java.lang.String user,
                                      java.lang.String protocol,
                                      java.lang.String host)
                               throws DatabaseException

Grants the given user access to connect to the database from the given host address. The 'protocol' string is the connecting protocol which can be either 'TCP' or 'Local'. The 'host' string is the actual host that is connecting. For example, if the protocol was TCP then the client host may be '127.0.0.1' for localhost.

Throws:
  `DatabaseException`

#### canUserCreateAndDropUsers

    public boolean canUserCreateAndDropUsers​(DatabaseQueryContext context,
                                             User user)
                                      throws DatabaseException

Returns true if the user is permitted to create, alter and drop user information from the database, otherwise returns false. Only members of the 'secure access' group, or the 'user manager' group can do this.

Throws:
  `DatabaseException`

#### canUserCreateAndDropSchema

    public boolean canUserCreateAndDropSchema​(DatabaseQueryContext context,
                                              User user,
                                              java.lang.String schema)
                                       throws DatabaseException

Returns true if the user is permitted to create and drop schema's in the database, otherwise returns false. Only members of the 'secure access' group, or the 'schema manager' group can do this.

Throws:
  `DatabaseException`

#### canUserShutDown

    public boolean canUserShutDown​(DatabaseQueryContext context,
                                   User user)
                            throws DatabaseException

Returns true if the user can shut down the database server. A user can shut down the database if they are a member of the 'secure acces' group.

Throws:
  `DatabaseException`

#### canUserExecuteStoredProcedure

    public boolean canUserExecuteStoredProcedure​(DatabaseQueryContext context,
                                                 User user,
                                                 java.lang.String procedure_name)
                                          throws DatabaseException

Returns true if the user is allowed to execute the given stored procedure.

Throws:
  `DatabaseException`

#### canUserCreateTableObject

    public boolean canUserCreateTableObject​(DatabaseQueryContext context,
                                            User user,
                                            TableName table)
                                     throws DatabaseException

Returns true if the user can create a table or view with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserAlterTableObject

    public boolean canUserAlterTableObject​(DatabaseQueryContext context,
                                           User user,
                                           TableName table)
                                    throws DatabaseException

Returns true if the user can alter a table or view with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserDropTableObject

    public boolean canUserDropTableObject​(DatabaseQueryContext context,
                                          User user,
                                          TableName table)
                                   throws DatabaseException

Returns true if the user can drop a table or view with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserSelectFromTableObject

    public boolean canUserSelectFromTableObject​(DatabaseQueryContext context,
                                                User user,
                                                TableName table,
                                                Variable[] columns)
                                         throws DatabaseException

Returns true if the user can select from a table or view with the given name and given columns, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserInsertIntoTableObject

    public boolean canUserInsertIntoTableObject​(DatabaseQueryContext context,
                                                User user,
                                                TableName table,
                                                Variable[] columns)
                                         throws DatabaseException

Returns true if the user can insert into a table or view with the given name and given columns, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserUpdateTableObject

    public boolean canUserUpdateTableObject​(DatabaseQueryContext context,
                                            User user,
                                            TableName table,
                                            Variable[] columns)
                                     throws DatabaseException

Returns true if the user can update a table or view with the given name and given columns, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserDeleteFromTableObject

    public boolean canUserDeleteFromTableObject​(DatabaseQueryContext context,
                                                User user,
                                                TableName table)
                                         throws DatabaseException

Returns true if the user can delete from a table or view with the given name and given columns, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserCompactTableObject

    public boolean canUserCompactTableObject​(DatabaseQueryContext context,
                                             User user,
                                             TableName table)
                                      throws DatabaseException

Returns true if the user can compact a table with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserCreateProcedureObject

    public boolean canUserCreateProcedureObject​(DatabaseQueryContext context,
                                                User user,
                                                TableName table)
                                         throws DatabaseException

Returns true if the user can create a procedure with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserDropProcedureObject

    public boolean canUserDropProcedureObject​(DatabaseQueryContext context,
                                              User user,
                                              TableName table)
                                       throws DatabaseException

Returns true if the user can drop a procedure with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserCreateSequenceObject

    public boolean canUserCreateSequenceObject​(DatabaseQueryContext context,
                                               User user,
                                               TableName table)
                                        throws DatabaseException

Returns true if the user can create a sequence with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### canUserDropSequenceObject

    public boolean canUserDropSequenceObject​(DatabaseQueryContext context,
                                             User user,
                                             TableName table)
                                      throws DatabaseException

Returns true if the user can drop a sequence with the given name, otherwise returns false.

Throws:
  `DatabaseException`

#### setupSystemFunctions

    public void setupSystemFunctions​(DatabaseConnection connection,
                                     java.lang.String admin_user)
                              throws DatabaseException

Sets all the standard functions and procedures available to engine. This creates an entry in the SYS_FUNCTION table for all the dynamic functions and procedures. This may not include the functions exposed though the FunctionFactory interface.

Throws:
  `DatabaseException`

#### create

    public void create​(java.lang.String username,
                       java.lang.String password)

Creates and sets up a new database to an initial empty state. The creation process involves creating all the system tables and views, adding an administrator user account, creating schema, and setting up the initial grant information for the administrator user.

The 'username' and 'password' parameter given are set for the administrator account.

#### init

    public void init()
              throws DatabaseException

Initializes the database. This opens all the files that are required for the operation of the database. If it finds that the version of the data files are not a compatible version, this method throws an exception.

NOTE: Perhaps a better name for this method is 'open'.

Throws:
  `DatabaseException`

#### shutdown

    public void shutdown()
                  throws DatabaseException

Cleanly shuts down the database. It is important that this method is called just before the system closes down.

The main purpose of this method is to ensure any tables that are backed by files and in a 'safe' state and cleanly flushed to the file system.

If 'delete_on_shutdown' is true, the database will delete itself from the file system when it shuts down.

Throws:
  `DatabaseException`

#### exists

    public boolean exists()

Returns true if the database exists. This must be called before 'init' and 'create'. It checks that the database files exist and we can boot into the database.

#### setDeleteOnShutdown

    public final void setDeleteOnShutdown​(boolean status)

If the 'deleteOnShutdown' flag is set, the database will delete the database from the file system when it is shutdown.

NOTE: Use with care - if this is set to true and the database is shutdown it will result in total loss of data.

#### isInitialized

    public boolean isInitialized()

Returns true if the database is initialised.

#### liveCopyTo

    public void liveCopyTo​(java.io.File path)
                    throws java.io.IOException

Copies all the persistent data in this database (the conglomerate) to the given destination path. This can copy information while the database is 'live'.

Throws:
  `java.io.IOException`

#### convertToCurrent

    public boolean convertToCurrent​(java.io.PrintStream out,
                                    java.lang.String admin_username)
                             throws java.io.IOException

Functionality for converting and old database format to the existing format. This would typically be called from a convert tool program.

Returns true if the convert was successful or false if it wasn't (error message is output to the PrintWriter).

Throws:
  `java.io.IOException`

#### getDBProcedure

    public DatabaseProcedure getDBProcedure​(java.lang.String procedure_name,
                                            DatabaseConnection connection)
                                     throws DatabaseException

Resolves a procedure name into a DBProcedure object. This is used for finding a server side script. It throws a DatabaseException if the procedure could not be resolved or there was an error retrieving it.

ISSUE: Move this to DatabaseSystem?

Throws:
  `DatabaseException`

#### getSystem

    public final DatabaseSystem getSystem()

Returns the DatabaseSystem that this Database is from.

#### storeSystem

    public final com.mckoi.database.StoreSystem storeSystem()

Returns the StoreSystem for this Database.

#### stats

    public final Stats stats()

Convenience static for accessing the global Stats object. Perhaps this should be deprecated?

#### Debug

    public final DebugLogger Debug()

Returns the DebugLogger implementation from the DatabaseSystem.

#### getTriggerManager

    public final com.mckoi.database.TriggerManager getTriggerManager()

Returns the system trigger manager.

#### getUserManager

    public final UserManager getUserManager()

Returns the system user manager.

#### createEvent

    public final java.lang.Object createEvent​(java.lang.Runnable runner)

Creates an event for the database dispatcher.

#### postEvent

    public final void postEvent​(int time,
                                java.lang.Object event)

Posts an event on the database dispatcher.

#### getDataCellCache

    public final com.mckoi.database.DataCellCache getDataCellCache()

Returns the system DataCellCache.

#### hasShutDown

    public final boolean hasShutDown()

Returns true if the database has shut down.

#### startShutDownThread

    public final void startShutDownThread()

Starts the shutdown thread which should contain delegates that shut the database and all its resources down. This method returns immediately.

#### waitUntilShutdown

    public final void waitUntilShutdown()

Blocks until the database has shut down.

#### execute

    public final void execute​(User user,
                              DatabaseConnection database,
                              java.lang.Runnable runner)

Executes database functions from the 'run' method of the given runnable instance on the first available worker thread. All database functions must go through a worker thread. If we ensure this, we can easily stop all database functions from executing if need be. Also, we only need to have a certain number of threads active at any one time rather than a unique thread for each connection.

#### registerShutDownDelegate

    public final void registerShutDownDelegate​(java.lang.Runnable delegate)

Registers the delegate that is executed when the shutdown thread is activated.

#### setIsExecutingCommands

    public final void setIsExecutingCommands​(boolean status)

Controls whether the database is allowed to execute commands or not. If this is set to true, then calls to 'execute' will be executed as soon as there is a free worker thread available. Otherwise no commands are executed until this is enabled.

#### getSingleRowTable

    public final Table getSingleRowTable()

Returns a static table that has a single row but no columns. This table is useful for certain database operations.

#### finalize

    public void finalize()
                  throws java.lang.Throwable

Overrides:
  `finalize` in class `java.lang.Object`
Throws:
  `java.lang.Throwable`