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.


Copyright © 2005–2016 Health Market Science. All rights reserved.