com.healthmarketscience.jackcess
Interface Database

All Superinterfaces:

Closeable, Flushable, Iterable<Table>

All Known Implementing Classes:

DatabaseImpl

public interface Database
extends Iterable<Table>, Closeable, Flushable

An Access database instance. A new instance can be instantiated by opening an existing database file (DatabaseBuilder.open(File)) or creating a new database file (DatabaseBuilder.create(Database.FileFormat,File)) (for more advanced opening/creating use DatabaseBuilder). Once a Database has been opened, you can interact with the data via the relevant Table. When a Database instance is no longer useful, it should always be closed (close()) to avoid corruption.

Database instances (and all the related objects) are not thread-safe. However, separate Database instances (and their respective objects) can be used by separate threads without a problem.

Database instances do not implement any "transactional" support, and therefore concurrent editing of the same database file by multiple Database instances (or with outside programs such as MS Access) will generally result in database file corruption.

Author:

James Ahlborn

Usage:

General: This class is general use.

Nested Class Summary

static class

Database.FileFormat Enum which indicates which version of Access created the database.

Field Summary

static String	ALLOW_AUTONUM_INSERT_PROPERTY system property which can be used to set the default allow auto number insert policy.
static String	BROKEN_NIO_PROPERTY (boolean) system property which can be used to indicate that the current vm has a poor nio implementation (specifically for FileChannel.transferFrom)
static String	CHARSET_PROPERTY_PREFIX system property prefix which can be used to set the default Charset used for text data (full property includes the JetFormat version).
static String	COLUMN_ORDER_PROPERTY system property which can be used to set the default sort order for table columns.
static boolean	DEFAULT_AUTO_SYNC default value for the auto-sync value (true).
static Table.ColumnOrder	DEFAULT_COLUMN_ORDER the default sort order for table columns.
static String	FK_ENFORCE_PROPERTY system property which can be used to set the default enforcement of foreign-key relationships.
static String	RESOURCE_PATH_PROPERTY system property which can be used to set the path from which classpath resources are loaded (must end with a "/" if non-empty).
static String	TIMEZONE_PROPERTY system property which can be used to set the default TimeZone used for date calculations.

Method Summary

void	close() Close the database file (and any linked databases).
void	createLinkedTable(String name, String linkedDbName, String linkedTableName) Create a new table in this database
void	flush() Flushes any current changes to the database file (and any linked databases) to disk.
Charset	getCharset() Gets currently configured Charset (always non-null).
Table.ColumnOrder	getColumnOrder() Gets currently configured Table.ColumnOrder (always non-null).
ColumnValidatorFactory	getColumnValidatorFactory() Gets currently configured ColumnValidatorFactory (always non-null).
String	getDatabasePassword()
PropertyMap	getDatabaseProperties()
ErrorHandler	getErrorHandler() Gets the currently configured ErrorHandler (always non-null).
File	getFile() Returns the File underlying this Database
Database.FileFormat	getFileFormat() Returns the FileFormat of this database (which may involve inspecting the database itself).
Map<String,Database>	getLinkedDatabases() Returns an unmodifiable view of the currently loaded linked databases, mapped from the linked database file name to the linked database.
LinkResolver	getLinkResolver() Gets the currently configured LinkResolver (always non-null).
List<Query>	getQueries() Finds all the queries in the database.
List<Relationship>	getRelationships() Finds all the relationships in the database in non-system tables.
List<Relationship>	getRelationships(Table table) Finds all the relationships in the database for the given table.
List<Relationship>	getRelationships(Table table1, Table table2) Finds all the relationships in the database between the given tables.
PropertyMap	getSummaryProperties()
List<Relationship>	getSystemRelationships() Finds all the relationships in the database, including system tables.
Table	getSystemTable(String tableName) Returns a reference to any available table in this access database, including system tables.
Set<String>	getSystemTableNames()
Table	getTable(String name)
TableMetaData	getTableMetaData(String name)
Set<String>	getTableNames()
TimeZone	getTimeZone() Gets currently configured TimeZone (always non-null).
PropertyMap	getUserDefinedProperties()
boolean	isAllowAutoNumberInsert() Gets current allow auto number insert policy.
boolean	isEnforceForeignKeys() Gets current foreign-key enforcement policy.
boolean	isLinkedTable(Table table) Returns true if this Database links to the given Table, false otherwise.
Iterator<Table>	iterator()
TableIterableBuilder	newIterable() Convenience method for constructing a new TableIterableBuilder for this cursor.
void	setAllowAutoNumberInsert(Boolean allowAutoNumInsert) Sets the new auto number insert policy for the database (unless overridden at the Table level).
void	setCharset(Charset newCharset) Sets a new Charset.
void	setColumnOrder(Table.ColumnOrder newColumnOrder) Sets a new Table.ColumnOrder.
void	setColumnValidatorFactory(ColumnValidatorFactory newFactory) Sets a new ColumnValidatorFactory.
void	setEnforceForeignKeys(Boolean newEnforceForeignKeys) Sets a new foreign-key enforcement policy.
void	setErrorHandler(ErrorHandler newErrorHandler) Sets a new ErrorHandler.
void	setLinkResolver(LinkResolver newLinkResolver) Sets a new LinkResolver.
void	setTimeZone(TimeZone newTimeZone) Sets a new TimeZone.

Field Detail

DEFAULT_AUTO_SYNC

static final boolean DEFAULT_AUTO_SYNC

default value for the auto-sync value (true). this is slower, but leaves more chance of a useable database in the face of failures.

See Also:

Constant Field Values

Usage:

General: This field is general use.

DEFAULT_COLUMN_ORDER

static final Table.ColumnOrder DEFAULT_COLUMN_ORDER

the default sort order for table columns.

Usage:

Intermediate: This field requires moderate API knowledge.

TIMEZONE_PROPERTY

static final String TIMEZONE_PROPERTY

system property which can be used to set the default TimeZone used for date calculations.

See Also:

Constant Field Values

Usage:

General: This field is general use.

CHARSET_PROPERTY_PREFIX

static final String CHARSET_PROPERTY_PREFIX

system property prefix which can be used to set the default Charset used for text data (full property includes the JetFormat version).

See Also:

Constant Field Values

Usage:

General: This field is general use.

RESOURCE_PATH_PROPERTY

static final String RESOURCE_PATH_PROPERTY

system property which can be used to set the path from which classpath resources are loaded (must end with a "/" if non-empty). Default value is "com/healthmarketscience/jackcess/" if unspecified.

See Also:

Constant Field Values

Usage:

General: This field is general use.

BROKEN_NIO_PROPERTY

static final String BROKEN_NIO_PROPERTY

(boolean) system property which can be used to indicate that the current vm has a poor nio implementation (specifically for FileChannel.transferFrom)

See Also:

Constant Field Values

Usage:

Intermediate: This field requires moderate API knowledge.

COLUMN_ORDER_PROPERTY

static final String COLUMN_ORDER_PROPERTY

system property which can be used to set the default sort order for table columns. Value should be one Table.ColumnOrder enum values.

See Also:

Constant Field Values

Usage:

Intermediate: This field requires moderate API knowledge.

FK_ENFORCE_PROPERTY

static final String FK_ENFORCE_PROPERTY

system property which can be used to set the default enforcement of foreign-key relationships. Defaults to true.

See Also:

Constant Field Values

Usage:

General: This field is general use.

ALLOW_AUTONUM_INSERT_PROPERTY

static final String ALLOW_AUTONUM_INSERT_PROPERTY

system property which can be used to set the default allow auto number insert policy. Defaults to false.

See Also:

Constant Field Values

Usage:

General: This field is general use.

Method Detail

getFile

File getFile()

Returns the File underlying this Database

getTableNames

Set<String> getTableNames()
                          throws IOException

Returns:

The names of all of the user tables

Throws:

IOException

Usage:

General: This method is general use.

getSystemTableNames

Set<String> getSystemTableNames()
                                throws IOException

Returns:

The names of all of the system tables (String). Note, in order to read these tables, you must use getSystemTable(java.lang.String). Extreme care should be taken if modifying these tables directly!.

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

iterator

Iterator<Table> iterator()

Specified by:

iterator in interface Iterable<Table>

Returns:

an unmodifiable Iterator of the user Tables in this Database.

Throws:

RuntimeIOException - if an IOException is thrown by one of the operations, the actual exception will be contained within

ConcurrentModificationException - if a table is added to the database while an Iterator is in use.

Usage:

General: This method is general use.

newIterable

TableIterableBuilder newIterable()

Convenience method for constructing a new TableIterableBuilder for this cursor. A TableIterableBuilder provides a variety of options for more flexible iteration of Tables.

getTable

Table getTable(String name)
               throws IOException

Parameters:

name - User table name (case-insensitive)

Returns:

The Table, or null if it doesn't exist (or is a system table)

Throws:

IOException

Usage:

General: This method is general use.

getTableMetaData

TableMetaData getTableMetaData(String name)
                               throws IOException

Parameters:

name - Table name (case-insensitive), may be any table type (i.e. includes system or linked tables).

Returns:

The meta data for the table, or null if it doesn't exist

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getRelationships

List<Relationship> getRelationships(Table table1,
                                    Table table2)
                                    throws IOException

Finds all the relationships in the database between the given tables.

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getRelationships

List<Relationship> getRelationships(Table table)
                                    throws IOException

Finds all the relationships in the database for the given table.

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getRelationships

List<Relationship> getRelationships()
                                    throws IOException

Finds all the relationships in the database in non-system tables.

Warning, this may load all the Tables (metadata, not data) in the database which could cause memory issues.

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getSystemRelationships

List<Relationship> getSystemRelationships()
                                          throws IOException

Finds all the relationships in the database, including system tables.

Warning, this may load all the Tables (metadata, not data) in the database which could cause memory issues.

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getQueries

List<Query> getQueries()
                       throws IOException

Finds all the queries in the database.

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getSystemTable

Table getSystemTable(String tableName)
                     throws IOException

Returns a reference to any available table in this access database, including system tables.

Warning, this method is not designed for common use, only for the occassional time when access to a system table is necessary. Messing with system tables can strip the paint off your house and give your whole family a permanent, orange afro. You have been warned.

Parameters:

tableName - Table name, may be a system table

Returns:

The table, or null if it doesn't exist

Throws:

IOException

Usage:

Intermediate: This method requires moderate API knowledge.

getDatabaseProperties

PropertyMap getDatabaseProperties()
                                  throws IOException

Returns:

the core properties for the database

Throws:

IOException

Usage:

General: This method is general use.

getSummaryProperties

PropertyMap getSummaryProperties()
                                 throws IOException

Returns:

the summary properties for the database

Throws:

IOException

Usage:

General: This method is general use.

getUserDefinedProperties

PropertyMap getUserDefinedProperties()
                                     throws IOException

Returns:

the user-defined properties for the database

Throws:

IOException

Usage:

General: This method is general use.

getDatabasePassword

String getDatabasePassword()
                           throws IOException

Returns:

the current database password, or null if none set.

Throws:

IOException

Usage:

General: This method is general use.

createLinkedTable

void createLinkedTable(String name,
                       String linkedDbName,
                       String linkedTableName)
                       throws IOException

Create a new table in this database

Parameters:

name - Name of the table to create in this database

linkedDbName - path to the linked database

linkedTableName - name of the table in the linked database

Throws:

IOException

Usage:

General: This method is general use.

flush

void flush()
           throws IOException

Flushes any current changes to the database file (and any linked databases) to disk.

Specified by:

flush in interface Flushable

Throws:

IOException

Usage:

General: This method is general use.

close

void close()
           throws IOException

Close the database file (and any linked databases). A Database must be closed after use or changes could be lost and the Database file corrupted. A Database instance should be treated like any other external resource which would be closed in a finally block (e.g. an OutputStream or jdbc Connection).

Specified by:

close in interface Closeable

Throws:

IOException

Usage:

General: This method is general use.

getErrorHandler

ErrorHandler getErrorHandler()

Gets the currently configured ErrorHandler (always non-null). This will be used to handle all errors unless overridden at the Table or Cursor level.

Usage:

Intermediate: This method requires moderate API knowledge.

setErrorHandler

void setErrorHandler(ErrorHandler newErrorHandler)

Sets a new ErrorHandler. If null, resets to the ErrorHandler.DEFAULT.

Usage:

Intermediate: This method requires moderate API knowledge.

getLinkResolver

LinkResolver getLinkResolver()

Gets the currently configured LinkResolver (always non-null). This will be used to handle all linked database loading.

Usage:

Intermediate: This method requires moderate API knowledge.

setLinkResolver

void setLinkResolver(LinkResolver newLinkResolver)

Sets a new LinkResolver. If null, resets to the LinkResolver.DEFAULT.

Usage:

Intermediate: This method requires moderate API knowledge.

getLinkedDatabases

Map<String,Database> getLinkedDatabases()

Returns an unmodifiable view of the currently loaded linked databases, mapped from the linked database file name to the linked database. This information may be useful for implementing a LinkResolver.

Usage:

Intermediate: This method requires moderate API knowledge.

isLinkedTable

boolean isLinkedTable(Table table)
                      throws IOException

Returns true if this Database links to the given Table, false otherwise.

Throws:

IOException

Usage:

General: This method is general use.

getTimeZone

TimeZone getTimeZone()

Gets currently configured TimeZone (always non-null).

Usage:

Intermediate: This method requires moderate API knowledge.

setTimeZone

void setTimeZone(TimeZone newTimeZone)

Sets a new TimeZone. If null, resets to the default value.

Usage:

Intermediate: This method requires moderate API knowledge.

getCharset

Charset getCharset()

Gets currently configured Charset (always non-null).

Usage:

Intermediate: This method requires moderate API knowledge.

setCharset

void setCharset(Charset newCharset)

Sets a new Charset. If null, resets to the default value.

Usage:

Intermediate: This method requires moderate API knowledge.

getColumnOrder

Table.ColumnOrder getColumnOrder()

Gets currently configured Table.ColumnOrder (always non-null).

Usage:

Intermediate: This method requires moderate API knowledge.

setColumnOrder

void setColumnOrder(Table.ColumnOrder newColumnOrder)

Sets a new Table.ColumnOrder. If null, resets to the default value.

Usage:

Intermediate: This method requires moderate API knowledge.

isEnforceForeignKeys

boolean isEnforceForeignKeys()

Gets current foreign-key enforcement policy.

Usage:

Intermediate: This method requires moderate API knowledge.

setEnforceForeignKeys

void setEnforceForeignKeys(Boolean newEnforceForeignKeys)

Sets a new foreign-key enforcement policy. If null, resets to the default value.

Usage:

Intermediate: This method requires moderate API knowledge.

isAllowAutoNumberInsert

boolean isAllowAutoNumberInsert()

Gets current allow auto number insert policy. By default, jackcess does not allow auto numbers to be inserted or updated directly (they are always handled internally by the Table). Setting this policy to true allows the caller to optionally set the value explicitly when adding or updating rows (if a value is not provided, it will still be handled internally by the Table). This value can be set database-wide using setAllowAutoNumberInsert(java.lang.Boolean) and/or on a per-table basis using Table.setAllowAutoNumberInsert(java.lang.Boolean) (and/or on a jvm-wide using the ALLOW_AUTONUM_INSERT_PROPERTY system property). Note that enabling this feature should be done with care to reduce the chances of screwing up the database.

Usage:

Intermediate: This method requires moderate API knowledge.

setAllowAutoNumberInsert

void setAllowAutoNumberInsert(Boolean allowAutoNumInsert)

Sets the new auto number insert policy for the database (unless overridden at the Table level). If null, resets to the default value.

Usage:

Intermediate: This method requires moderate API knowledge.

getColumnValidatorFactory

ColumnValidatorFactory getColumnValidatorFactory()

Gets currently configured ColumnValidatorFactory (always non-null).

Usage:

Intermediate: This method requires moderate API knowledge.

setColumnValidatorFactory

void setColumnValidatorFactory(ColumnValidatorFactory newFactory)

Sets a new ColumnValidatorFactory. If null, resets to the default value. The configured ColumnValidatorFactory will be used to create ColumnValidator instances on any user tables loaded from this point onward (this will not be used for system tables).

Usage:

Intermediate: This method requires moderate API knowledge.

getFileFormat

Database.FileFormat getFileFormat()
                                  throws IOException

Returns the FileFormat of this database (which may involve inspecting the database itself).

Throws:

IllegalStateException - if the file format cannot be determined

IOException

Usage:

General: This method is general use.