com.healthmarketscience.jackcess
Class Database

java.lang.Object
  com.healthmarketscience.jackcess.Database

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Iterable<Table>

public class Database
extends java.lang.Object
implements java.lang.Iterable<Table>, java.io.Closeable, java.io.Flushable

An Access database.

There is optional support for large indexes (enabled by default). This optional support can be disabled via a few different means:

• Setting the system property "com.healthmarketscience.jackcess.bigIndex" to "false" will disable "large" index support across the jvm
• Calling setUseBigIndex(boolean) on a Database instance will override any system property setting for "large" index support for all tables subsequently created from that instance
• Calling getTable(String,boolean) can selectively enable/disable "large" index support on a per-table basis (overriding any Database or system property setting)

Author:

Tim McCune

Nested Class Summary

static class

Database.FileFormat

Field Summary

static java.lang.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 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.
static ErrorHandler	DEFAULT_ERROR_HANDLER default error handler used if none provided (just rethrows exception)
static java.lang.String	TIMEZONE_PROPERTY system property which can be used to set the default TimeZone used for date calculations.
static java.lang.String	USE_BIG_INDEX_PROPERTY system property which can be used to make big index support the default.

Method Summary

void	close() Close the database file
java.lang.String	copyTable(java.lang.String name, java.sql.ResultSet source) Copy an existing JDBC ResultSet into a new table in this database
java.lang.String	copyTable(java.lang.String name, java.sql.ResultSet source, ImportFilter filter) Copy an existing JDBC ResultSet into a new table in this database
static Database	create(Database.FileFormat fileFormat, java.io.File mdbFile) Create a new Database for the given fileFormat Equivalent to: create(fileFormat, mdbFile, DEFAULT_AUTO_SYNC);
static Database	create(Database.FileFormat fileFormat, java.io.File mdbFile, boolean autoSync) Create a new Database for the given fileFormat
static Database	create(Database.FileFormat fileFormat, java.io.File mdbFile, boolean autoSync, java.nio.charset.Charset charset, java.util.TimeZone timeZone) Create a new Database for the given fileFormat
static Database	create(java.io.File mdbFile) Create a new Access 2000 Database Equivalent to: create(FileFormat.V2000, mdbFile, DEFAULT_AUTO_SYNC);
static Database	create(java.io.File mdbFile, boolean autoSync) Create a new Access 2000 Database Equivalent to: create(FileFormat.V2000, mdbFile, DEFAULT_AUTO_SYNC);
void	createTable(java.lang.String name, java.util.List<Column> columns) Create a new table in this database
boolean	defaultUseBigIndex() Returns false if "big index support" has been disabled explicity on the this Database or via a system property, true otherwise.
boolean	doUseBigIndex() Whether or not big index support is enabled for tables.
static java.lang.String	escapeIdentifier(java.lang.String s)
void	flush() Flushes any current changes to the database file to disk.
Table	getAccessControlEntries()
java.nio.charset.Charset	getCharset() Gets currently configured Charset (always non-null).
static java.nio.charset.Charset	getDefaultCharset(JetFormat format) Returns the default Charset for the given JetFormat.
static java.util.TimeZone	getDefaultTimeZone() Returns the default TimeZone.
ErrorHandler	getErrorHandler() Gets the currently configured ErrorHandler (always non-null).
Database.FileFormat	getFileFormat() Returns the FileFormat of this database (which may involve inspecting the database itself).
JetFormat	getFormat()
PageChannel	getPageChannel()
java.util.List<Query>	getQueries() Finds all the queries in the database.
java.util.List<Relationship>	getRelationships(Table table1, Table table2) Finds all the relationships in the database between the given tables.
Table	getSystemCatalog()
Table	getSystemTable(java.lang.String tableName) Returns a reference to any available table in this access database, including system tables.
Table	getTable(java.lang.String name)
Table	getTable(java.lang.String name, boolean useBigIndex)
java.util.Set<java.lang.String>	getTableNames()
java.util.TimeZone	getTimeZone() Gets currently configured TimeZone (always non-null).
java.lang.String	importFile(java.lang.String name, java.io.File f, java.lang.String delim) Copy a delimited text file into a new table in this database
java.lang.String	importFile(java.lang.String name, java.io.File f, java.lang.String delim, ImportFilter filter) Copy a delimited text file into a new table in this database
java.lang.String	importReader(java.lang.String name, java.io.BufferedReader in, java.lang.String delim) Copy a delimited text file into a new table in this database
java.lang.String	importReader(java.lang.String name, java.io.BufferedReader in, java.lang.String delim, ImportFilter filter) Copy a delimited text file into a new table in this database
static boolean	isReservedWord(java.lang.String s)
java.util.Iterator<Table>	iterator()
static Database	open(java.io.File mdbFile) Open an existing Database.
static Database	open(java.io.File mdbFile, boolean readOnly) Open an existing Database.
static Database	open(java.io.File mdbFile, boolean readOnly, boolean autoSync) Open an existing Database.
static Database	open(java.io.File mdbFile, boolean readOnly, boolean autoSync, java.nio.charset.Charset charset, java.util.TimeZone timeZone) Open an existing Database.
void	setCharset(java.nio.charset.Charset newCharset) Sets a new Charset.
void	setErrorHandler(ErrorHandler newErrorHandler) Sets a new ErrorHandler.
void	setTimeZone(java.util.TimeZone newTimeZone) Sets a new TimeZone.
void	setUseBigIndex(boolean useBigIndex) Set whether or not big index support is enabled for tables.
java.lang.String	toString()
static void	validateIdentifierName(java.lang.String name, int maxLength, java.lang.String identifierType) Validates an identifier name.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_AUTO_SYNC

public 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

USE_BIG_INDEX_PROPERTY

public static final java.lang.String USE_BIG_INDEX_PROPERTY

system property which can be used to make big index support the default.

See Also:

Constant Field Values

TIMEZONE_PROPERTY

public static final java.lang.String TIMEZONE_PROPERTY

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

See Also:

Constant Field Values

CHARSET_PROPERTY_PREFIX

public static final java.lang.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

DEFAULT_ERROR_HANDLER

public static final ErrorHandler DEFAULT_ERROR_HANDLER

default error handler used if none provided (just rethrows exception)

Method Detail

open

public static Database open(java.io.File mdbFile)
                     throws java.io.IOException

Open an existing Database. If the existing file is not writeable, the file will be opened read-only. Auto-syncing is enabled for the returned Database.

Equivalent to: open(mdbFile, false);

Parameters:

mdbFile - File containing the database

Throws:

java.io.IOException

See Also:

open(File,boolean)

open

public static Database open(java.io.File mdbFile,
                            boolean readOnly)
                     throws java.io.IOException

Open an existing Database. If the existing file is not writeable or the readOnly flag is true, the file will be opened read-only. Auto-syncing is enabled for the returned Database.

Equivalent to: open(mdbFile, readOnly, DEFAULT_AUTO_SYNC);

Parameters:

mdbFile - File containing the database

readOnly - iff true, force opening file in read-only mode

Throws:

java.io.IOException

See Also:

open(File,boolean,boolean)

open

public static Database open(java.io.File mdbFile,
                            boolean readOnly,
                            boolean autoSync)
                     throws java.io.IOException

Open an existing Database. If the existing file is not writeable or the readOnly flag is true, the file will be opened read-only.

Parameters:

mdbFile - File containing the database

readOnly - iff true, force opening file in read-only mode

autoSync - whether or not to enable auto-syncing on write. if true, writes will be immediately flushed to disk. This leaves the database in a (fairly) consistent state on each write, but can be very inefficient for many updates. if false, flushing to disk happens at the jvm's leisure, which can be much faster, but may leave the database in an inconsistent state if failures are encountered during writing.

Throws:

java.io.IOException

open

public static Database open(java.io.File mdbFile,
                            boolean readOnly,
                            boolean autoSync,
                            java.nio.charset.Charset charset,
                            java.util.TimeZone timeZone)
                     throws java.io.IOException

Open an existing Database. If the existing file is not writeable or the readOnly flag is true, the file will be opened read-only.

Parameters:

mdbFile - File containing the database

readOnly - iff true, force opening file in read-only mode

autoSync - whether or not to enable auto-syncing on write. if true, writes will be immediately flushed to disk. This leaves the database in a (fairly) consistent state on each write, but can be very inefficient for many updates. if false, flushing to disk happens at the jvm's leisure, which can be much faster, but may leave the database in an inconsistent state if failures are encountered during writing.

charset - Charset to use, if null, uses default

timeZone - TimeZone to use, if null, uses default

Throws:

java.io.IOException

create

public static Database create(java.io.File mdbFile)
                       throws java.io.IOException

Create a new Access 2000 Database

Equivalent to: create(FileFormat.V2000, mdbFile, DEFAULT_AUTO_SYNC);

Parameters:

mdbFile - Location to write the new database to. If this file already exists, it will be overwritten.

Throws:

java.io.IOException

See Also:

create(File,boolean)

create

public static Database create(Database.FileFormat fileFormat,
                              java.io.File mdbFile)
                       throws java.io.IOException

Create a new Database for the given fileFormat

Equivalent to: create(fileFormat, mdbFile, DEFAULT_AUTO_SYNC);

Parameters:

fileFormat - version of new database.

mdbFile - Location to write the new database to. If this file already exists, it will be overwritten.

Throws:

java.io.IOException

See Also:

create(File,boolean)

create

public static Database create(java.io.File mdbFile,
                              boolean autoSync)
                       throws java.io.IOException

Create a new Access 2000 Database

Equivalent to: create(FileFormat.V2000, mdbFile, DEFAULT_AUTO_SYNC);

Parameters:

mdbFile - Location to write the new database to. If this file already exists, it will be overwritten.

autoSync - whether or not to enable auto-syncing on write. if true, writes will be immediately flushed to disk. This leaves the database in a (fairly) consistent state on each write, but can be very inefficient for many updates. if false, flushing to disk happens at the jvm's leisure, which can be much faster, but may leave the database in an inconsistent state if failures are encountered during writing.

Throws:

java.io.IOException

create

public static Database create(Database.FileFormat fileFormat,
                              java.io.File mdbFile,
                              boolean autoSync)
                       throws java.io.IOException

Create a new Database for the given fileFormat

Parameters:

fileFormat - version of new database.

mdbFile - Location to write the new database to. If this file already exists, it will be overwritten.

autoSync - whether or not to enable auto-syncing on write. if true, writes will be immediately flushed to disk. This leaves the database in a (fairly) consistent state on each write, but can be very inefficient for many updates. if false, flushing to disk happens at the jvm's leisure, which can be much faster, but may leave the database in an inconsistent state if failures are encountered during writing.

Throws:

java.io.IOException

create

public static Database create(Database.FileFormat fileFormat,
                              java.io.File mdbFile,
                              boolean autoSync,
                              java.nio.charset.Charset charset,
                              java.util.TimeZone timeZone)
                       throws java.io.IOException

Create a new Database for the given fileFormat

Parameters:

fileFormat - version of new database.

mdbFile - Location to write the new database to. If this file already exists, it will be overwritten.

autoSync - whether or not to enable auto-syncing on write. if true, writes will be immediately flushed to disk. This leaves the database in a (fairly) consistent state on each write, but can be very inefficient for many updates. if false, flushing to disk happens at the jvm's leisure, which can be much faster, but may leave the database in an inconsistent state if failures are encountered during writing.

charset - Charset to use, if null, uses default

timeZone - TimeZone to use, if null, uses default

Throws:

java.io.IOException

getPageChannel

public PageChannel getPageChannel()

getFormat

public JetFormat getFormat()

getSystemCatalog

public Table getSystemCatalog()

Returns:

The system catalog table

getAccessControlEntries

public Table getAccessControlEntries()

Returns:

The system Access Control Entries table

doUseBigIndex

public boolean doUseBigIndex()

Whether or not big index support is enabled for tables.

setUseBigIndex

public void setUseBigIndex(boolean useBigIndex)

Set whether or not big index support is enabled for tables.

getErrorHandler

public 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.

setErrorHandler

public void setErrorHandler(ErrorHandler newErrorHandler)

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

getTimeZone

public java.util.TimeZone getTimeZone()

Gets currently configured TimeZone (always non-null).

setTimeZone

public void setTimeZone(java.util.TimeZone newTimeZone)

Sets a new TimeZone. If null, resets to the value returned by getDefaultTimeZone().

getCharset

public java.nio.charset.Charset getCharset()

Gets currently configured Charset (always non-null).

setCharset

public void setCharset(java.nio.charset.Charset newCharset)

Sets a new Charset. If null, resets to the value returned by getDefaultCharset(com.healthmarketscience.jackcess.JetFormat).

getFileFormat

public Database.FileFormat getFileFormat()

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

Throws:

java.lang.IllegalStateException - if the file format cannot be determined

getTableNames

public java.util.Set<java.lang.String> getTableNames()

Returns:

The names of all of the user tables (String)

iterator

public java.util.Iterator<Table> iterator()

Specified by:

iterator in interface java.lang.Iterable<Table>

Returns:

an unmodifiable Iterator of the user Tables in this Database.

Throws:

java.lang.IllegalStateException - if an IOException is thrown by one of the operations, the actual exception will be contained within

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

getTable

public Table getTable(java.lang.String name)
               throws java.io.IOException

Parameters:

name - Table name

Returns:

The table, or null if it doesn't exist

Throws:

java.io.IOException

getTable

public Table getTable(java.lang.String name,
                      boolean useBigIndex)
               throws java.io.IOException

Parameters:

name - Table name

useBigIndex - whether or not "big index support" should be enabled for the table (this value will override any other settings)

Returns:

The table, or null if it doesn't exist

Throws:

java.io.IOException

createTable

public void createTable(java.lang.String name,
                        java.util.List<Column> columns)
                 throws java.io.IOException

Create a new table in this database

Parameters:

name - Name of the table to create

columns - List of Columns in the table

Throws:

java.io.IOException

getRelationships

public java.util.List<Relationship> getRelationships(Table table1,
                                                     Table table2)
                                              throws java.io.IOException

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

Throws:

java.io.IOException

getQueries

public java.util.List<Query> getQueries()
                                 throws java.io.IOException

Finds all the queries in the database.

Throws:

java.io.IOException

getSystemTable

public Table getSystemTable(java.lang.String tableName)
                     throws java.io.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:

java.io.IOException

copyTable

public java.lang.String copyTable(java.lang.String name,
                                  java.sql.ResultSet source)
                           throws java.sql.SQLException,
                                  java.io.IOException

Copy an existing JDBC ResultSet into a new table in this database

Parameters:

name - Name of the new table to create

source - ResultSet to copy from

Returns:

the name of the copied table

Throws:

java.sql.SQLException

java.io.IOException

See Also:

ImportUtil.importResultSet(ResultSet,Database,String)

copyTable

public java.lang.String copyTable(java.lang.String name,
                                  java.sql.ResultSet source,
                                  ImportFilter filter)
                           throws java.sql.SQLException,
                                  java.io.IOException

Copy an existing JDBC ResultSet into a new table in this database

Parameters:

name - Name of the new table to create

source - ResultSet to copy from

filter - valid import filter

Returns:

the name of the imported table

Throws:

java.sql.SQLException

java.io.IOException

See Also:

ImportUtil.importResultSet(ResultSet,Database,String,ImportFilter)

importFile

public java.lang.String importFile(java.lang.String name,
                                   java.io.File f,
                                   java.lang.String delim)
                            throws java.io.IOException

Copy a delimited text file into a new table in this database

Parameters:

name - Name of the new table to create

f - Source file to import

delim - Regular expression representing the delimiter string.

Returns:

the name of the imported table

Throws:

java.io.IOException

See Also:

ImportUtil.importFile(File,Database,String,String)

importFile

public java.lang.String importFile(java.lang.String name,
                                   java.io.File f,
                                   java.lang.String delim,
                                   ImportFilter filter)
                            throws java.io.IOException

Copy a delimited text file into a new table in this database

Parameters:

name - Name of the new table to create

f - Source file to import

delim - Regular expression representing the delimiter string.

filter - valid import filter

Returns:

the name of the imported table

Throws:

java.io.IOException

See Also:

ImportUtil.importFile(File,Database,String,String,ImportFilter)

importReader

public java.lang.String importReader(java.lang.String name,
                                     java.io.BufferedReader in,
                                     java.lang.String delim)
                              throws java.io.IOException

Copy a delimited text file into a new table in this database

Parameters:

name - Name of the new table to create

in - Source reader to import

delim - Regular expression representing the delimiter string.

Returns:

the name of the imported table

Throws:

java.io.IOException

See Also:

ImportUtil.importReader(BufferedReader,Database,String,String)

importReader

public java.lang.String importReader(java.lang.String name,
                                     java.io.BufferedReader in,
                                     java.lang.String delim,
                                     ImportFilter filter)
                              throws java.io.IOException

Copy a delimited text file into a new table in this database

Parameters:

name - Name of the new table to create

in - Source reader to import

delim - Regular expression representing the delimiter string.

filter - valid import filter

Returns:

the name of the imported table

Throws:

java.io.IOException

See Also:

ImportUtil.importReader(BufferedReader,Database,String,String,ImportFilter)

flush

public void flush()
           throws java.io.IOException

Flushes any current changes to the database file to disk.

Specified by:

flush in interface java.io.Flushable

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Close the database file

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException

escapeIdentifier

public static java.lang.String escapeIdentifier(java.lang.String s)

Returns:

A table or column name escaped for Access

isReservedWord

public static boolean isReservedWord(java.lang.String s)

Returns:

true if the given string is a reserved word, false otherwise

validateIdentifierName

public static void validateIdentifierName(java.lang.String name,
                                          int maxLength,
                                          java.lang.String identifierType)

Validates an identifier name.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

defaultUseBigIndex

public boolean defaultUseBigIndex()

Returns false if "big index support" has been disabled explicity on the this Database or via a system property, true otherwise.

getDefaultTimeZone

public static java.util.TimeZone getDefaultTimeZone()

Returns the default TimeZone. This is normally the platform default TimeZone as returned by TimeZone.getDefault(), but can be overridden using the system property "com.healthmarketscience.jackcess.timeZone".

getDefaultCharset

public static java.nio.charset.Charset getDefaultCharset(JetFormat format)

Returns the default Charset for the given JetFormat. This may or may not be platform specific, depending on the format, but can be overridden using a system property composed of the prefix "com.healthmarketscience.jackcess.charset." followed by the JetFormat version to which the charset should apply, e.g. "com.healthmarketscience.jackcess.charset.VERSION_3".