();
/** for now, "big index support" is optional */
private boolean _useBigIndex;
/** optional error handler to use when row errors are encountered */
private ErrorHandler _dbErrorHandler;
/**
* 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:
* {@code open(mdbFile, false);}
*
* @param mdbFile File containing the database
*
* @see #open(File,boolean)
*/
public static Database open(File mdbFile) throws IOException {
return open(mdbFile, false);
}
/**
* 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:
* {@code open(mdbFile, readOnly, DEFAULT_AUTO_SYNC);}
*
* @param mdbFile File containing the database
* @param readOnly iff true, force opening file in read-only
* mode
*
* @see #open(File,boolean,boolean)
*/
public static Database open(File mdbFile, boolean readOnly)
throws IOException
{
return open(mdbFile, readOnly, DEFAULT_AUTO_SYNC);
}
/**
* Open an existing Database. If the existing file is not writeable or the
* readOnly flag is true, the file will be opened read-only.
* @param mdbFile File containing the database
* @param readOnly iff true, force opening file in read-only
* mode
* @param autoSync whether or not to enable auto-syncing on write. if
* {@code 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 {@code 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.
*/
public static Database open(File mdbFile, boolean readOnly, boolean autoSync)
throws IOException
{
if(!mdbFile.exists() || !mdbFile.canRead()) {
throw new FileNotFoundException("given file does not exist: " + mdbFile);
}
return new Database(openChannel(mdbFile,
(!mdbFile.canWrite() || readOnly)),
autoSync);
}
/**
* Create a new Database
*
* Equivalent to:
* {@code create(mdbFile, DEFAULT_AUTO_SYNC);}
*
* @param mdbFile Location to write the new database to. If this file
* already exists, it will be overwritten.
*
* @see #create(File,boolean)
*/
public static Database create(File mdbFile) throws IOException {
return create(mdbFile, DEFAULT_AUTO_SYNC);
}
/**
* Create a new Database
* @param mdbFile Location to write the new database to. If this file
* already exists, it will be overwritten.
* @param autoSync whether or not to enable auto-syncing on write. if
* {@code 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 {@code 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.
*/
public static Database create(File mdbFile, boolean autoSync)
throws IOException
{
FileChannel channel = openChannel(mdbFile, false);
channel.truncate(0);
channel.transferFrom(Channels.newChannel(
Thread.currentThread().getContextClassLoader().getResourceAsStream(
EMPTY_MDB)), 0, Integer.MAX_VALUE);
return new Database(channel, autoSync);
}
private static FileChannel openChannel(File mdbFile, boolean readOnly)
throws FileNotFoundException
{
String mode = (readOnly ? "r" : "rw");
return new RandomAccessFile(mdbFile, mode).getChannel();
}
/**
* Create a new database by reading it in from a FileChannel.
* @param channel File channel of the database. This needs to be a
* FileChannel instead of a ReadableByteChannel because we need to
* randomly jump around to various points in the file.
*/
protected Database(FileChannel channel, boolean autoSync) throws IOException
{
_format = JetFormat.getFormat(channel);
_pageChannel = new PageChannel(channel, _format, autoSync);
// note, it's slighly sketchy to pass ourselves along partially
// constructed, but only our _format and _pageChannel refs should be
// needed
_pageChannel.initialize(this);
_buffer = _pageChannel.createPageBuffer();
readSystemCatalog();
}
public PageChannel getPageChannel() {
return _pageChannel;
}
public JetFormat getFormat() {
return _format;
}
/**
* @return The system catalog table
*/
public Table getSystemCatalog() {
return _systemCatalog;
}
/**
* @return The system Access Control Entries table
*/
public Table getAccessControlEntries() {
return _accessControlEntries;
}
/**
* Whether or not big index support is enabled for tables.
*/
public boolean doUseBigIndex() {
return _useBigIndex;
}
/**
* Set whether or not big index support is enabled for tables.
*/
public void setUseBigIndex(boolean useBigIndex) {
_useBigIndex = useBigIndex;
}
/**
* Gets the currently configured ErrorHandler (always non-{@code null}).
* This will be used to handle all errors unless overridden at the Table or
* Cursor level.
*/
public ErrorHandler getErrorHandler() {
return((_dbErrorHandler != null) ? _dbErrorHandler :
DEFAULT_ERROR_HANDLER);
}
/**
* Sets a new ErrorHandler. If {@code null}, resets to the
* {@link #DEFAULT_ERROR_HANDLER}.
*/
public void setErrorHandler(ErrorHandler newErrorHandler) {
_dbErrorHandler = newErrorHandler;
}
/**
* Read the system catalog
*/
private void readSystemCatalog() throws IOException {
_systemCatalog = readTable(TABLE_SYSTEM_CATALOG, PAGE_SYSTEM_CATALOG,
defaultUseBigIndex());
for(Map row :
Cursor.createCursor(_systemCatalog).iterable(
SYSTEM_CATALOG_COLUMNS))
{
String name = (String) row.get(CAT_COL_NAME);
if (name != null && TYPE_TABLE.equals(row.get(CAT_COL_TYPE))) {
if (!name.startsWith(PREFIX_SYSTEM)) {
addTable((String) row.get(CAT_COL_NAME), (Integer) row.get(CAT_COL_ID));
} else if(TABLE_SYSTEM_ACES.equals(name)) {
int pageNumber = (Integer)row.get(CAT_COL_ID);
_accessControlEntries = readTable(TABLE_SYSTEM_ACES, pageNumber,
defaultUseBigIndex());
}
} else if (SYSTEM_OBJECT_NAME_TABLES.equals(name)) {
_tableParentId = (Integer) row.get(CAT_COL_ID);
}
}
// check for required system values
if(_accessControlEntries == null) {
throw new IOException("Did not find required " + TABLE_SYSTEM_ACES +
" table");
}
if(_tableParentId == null) {
throw new IOException("Did not find required parent table id");
}
if (LOG.isDebugEnabled()) {
LOG.debug("Finished reading system catalog. Tables: " +
getTableNames());
}
}
/**
* @return The names of all of the user tables (String)
*/
public Set getTableNames() {
if(_tableNames == null) {
_tableNames = new TreeSet(String.CASE_INSENSITIVE_ORDER);
for(TableInfo tableInfo : _tableLookup.values()) {
_tableNames.add(tableInfo.tableName);
}
}
return _tableNames;
}
/**
* @return an unmodifiable Iterator of the user Tables in this Database.
* @throws IllegalStateException if an IOException is thrown by one of the
* operations, the actual exception will be contained within
* @throws ConcurrentModificationException if a table is added to the
* database while an Iterator is in use.
*/
public Iterator iterator() {
return new TableIterator();
}
/**
* @param name Table name
* @return The table, or null if it doesn't exist
*/
public Table getTable(String name) throws IOException {
return getTable(name, defaultUseBigIndex());
}
/**
* @param name Table name
* @param useBigIndex whether or not "big index support" should be enabled
* for the table (this value will override any other
* settings)
* @return The table, or null if it doesn't exist
*/
public Table getTable(String name, boolean useBigIndex) throws IOException {
TableInfo tableInfo = lookupTable(name);
if ((tableInfo == null) || (tableInfo.pageNumber == null)) {
return null;
}
return readTable(tableInfo.tableName, tableInfo.pageNumber, useBigIndex);
}
/**
* Create a new table in this database
* @param name Name of the table to create
* @param columns List of Columns in the table
*/
public void createTable(String name, List columns)
throws IOException
{
validateIdentifierName(name, _format.MAX_TABLE_NAME_LENGTH, "table");
if(getTable(name) != null) {
throw new IllegalArgumentException(
"Cannot create table with name of existing table");
}
if(columns.isEmpty()) {
throw new IllegalArgumentException(
"Cannot create table with no columns");
}
if(columns.size() > _format.MAX_COLUMNS_PER_TABLE) {
throw new IllegalArgumentException(
"Cannot create table with more than " +
_format.MAX_COLUMNS_PER_TABLE + " columns");
}
Set colNames = new HashSet();
// next, validate the column definitions
for(Column column : columns) {
column.validate(_format);
if(!colNames.add(column.getName().toUpperCase())) {
throw new IllegalArgumentException("duplicate column name: " +
column.getName());
}
}
List autoCols = Table.getAutoNumberColumns(columns);
if(autoCols.size() > 1) {
// we can have one of each type
Set autoTypes = EnumSet.noneOf(DataType.class);
for(Column c : autoCols) {
if(!autoTypes.add(c.getType())) {
throw new IllegalArgumentException(
"Can have at most one AutoNumber column of type " + c.getType() + " per table");
}
}
}
//Write the tdef page to disk.
int tdefPageNumber = Table.writeTableDefinition(columns, _pageChannel,
_format);
//Add this table to our internal list.
addTable(name, Integer.valueOf(tdefPageNumber));
//Add this table to system tables
addToSystemCatalog(name, tdefPageNumber);
addToAccessControlEntries(tdefPageNumber);
}
/**
* Finds all the relationships in the database between the given tables.
*/
public List getRelationships(Table table1, Table table2)
throws IOException
{
// the relationships table does not get loaded until first accessed
if(_relationships == null) {
_relationships = getSystemTable(TABLE_SYSTEM_RELATIONSHIPS);
if(_relationships == null) {
throw new IOException("Could not find system relationships table");
}
}
int nameCmp = table1.getName().compareTo(table2.getName());
if(nameCmp == 0) {
throw new IllegalArgumentException("Must provide two different tables");
}
if(nameCmp > 0) {
// we "order" the two tables given so that we will return a collection
// of relationships in the same order regardless of whether we are given
// (TableFoo, TableBar) or (TableBar, TableFoo).
Table tmp = table1;
table1 = table2;
table2 = tmp;
}
List relationships = new ArrayList();
Cursor cursor = createCursorWithOptionalIndex(
_relationships, REL_COL_FROM_TABLE, table1.getName());
collectRelationships(cursor, table1, table2, relationships);
cursor = createCursorWithOptionalIndex(
_relationships, REL_COL_TO_TABLE, table1.getName());
collectRelationships(cursor, table2, table1, relationships);
return relationships;
}
/**
* Finds all the queries in the database.
*/
public List getQueries()
throws IOException
{
// the queries table does not get loaded until first accessed
if(_queries == null) {
_queries = getSystemTable(TABLE_SYSTEM_QUERIES);
if(_queries == null) {
throw new IOException("Could not find system queries table");
}
}
// find all the queries from the system catalog
List> queryInfo = new ArrayList>();
Map> queryRowMap =
new HashMap>();
for(Map row :
Cursor.createCursor(_systemCatalog).iterable(
SYSTEM_CATALOG_QUERY_COLUMNS))
{
String name = (String) row.get(CAT_COL_NAME);
if (name != null && TYPE_QUERY.equals(row.get(CAT_COL_TYPE))) {
queryInfo.add(row);
Integer id = (Integer)row.get(CAT_COL_ID);
queryRowMap.put(id, new ArrayList());
}
}
// find all the query rows
for(Map row : Cursor.createCursor(_queries)) {
Query.Row queryRow = new Query.Row(row);
List queryRows = queryRowMap.get(queryRow.objectId);
if(queryRows == null) {
LOG.warn("Found rows for query with id " + queryRow.objectId +
" missing from system catalog");
continue;
}
queryRows.add(queryRow);
}
// lastly, generate all the queries
List queries = new ArrayList();
for(Map row : queryInfo) {
String name = (String) row.get(CAT_COL_NAME);
Integer id = (Integer)row.get(CAT_COL_ID);
int flags = (Integer)row.get(CAT_COL_FLAGS);
List queryRows = queryRowMap.get(id);
queries.add(Query.create(flags, name, queryRows, id));
}
return queries;
}
/**
* 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.
*
* @param tableName Table name, may be a system table
* @return The table, or {@code null} if it doesn't exist
*/
public Table getSystemTable(String tableName)
throws IOException
{
for(Map row :
Cursor.createCursor(_systemCatalog).iterable(
SYSTEM_CATALOG_COLUMNS))
{
String name = (String) row.get(CAT_COL_NAME);
if (tableName.equalsIgnoreCase(name) &&
TYPE_TABLE.equals(row.get(CAT_COL_TYPE))) {
Integer pageNumber = (Integer) row.get(CAT_COL_ID);
if(pageNumber != null) {
return readTable(name, pageNumber, defaultUseBigIndex());
}
}
}
return null;
}
/**
* Finds the relationships matching the given from and to tables from the
* given cursor and adds them to the given list.
*/
private void collectRelationships(
Cursor cursor, Table fromTable, Table toTable,
List relationships)
{
for(Map row : cursor) {
String fromName = (String)row.get(REL_COL_FROM_TABLE);
String toName = (String)row.get(REL_COL_TO_TABLE);
if(fromTable.getName().equals(fromName) &&
toTable.getName().equals(toName))
{
String relName = (String)row.get(REL_COL_NAME);
// found more info for a relationship. see if we already have some
// info for this relationship
Relationship rel = null;
for(Relationship tmp : relationships) {
if(tmp.getName().equals(relName)) {
rel = tmp;
break;
}
}
if(rel == null) {
// new relationship
int numCols = (Integer)row.get(REL_COL_COLUMN_COUNT);
int flags = (Integer)row.get(REL_COL_FLAGS);
rel = new Relationship(relName, fromTable, toTable,
flags, numCols);
relationships.add(rel);
}
// add column info
int colIdx = (Integer)row.get(REL_COL_COLUMN_INDEX);
Column fromCol = fromTable.getColumn(
(String)row.get(REL_COL_FROM_COLUMN));
Column toCol = toTable.getColumn(
(String)row.get(REL_COL_TO_COLUMN));
rel.getFromColumns().set(colIdx, fromCol);
rel.getToColumns().set(colIdx, toCol);
}
}
}
/**
* Add a new table to the system catalog
* @param name Table name
* @param pageNumber Page number that contains the table definition
*/
private void addToSystemCatalog(String name, int pageNumber)
throws IOException
{
Object[] catalogRow = new Object[_systemCatalog.getColumnCount()];
int idx = 0;
Date creationTime = new Date();
for (Iterator iter = _systemCatalog.getColumns().iterator();
iter.hasNext(); idx++)
{
Column col = iter.next();
if (CAT_COL_ID.equals(col.getName())) {
catalogRow[idx] = Integer.valueOf(pageNumber);
} else if (CAT_COL_NAME.equals(col.getName())) {
catalogRow[idx] = name;
} else if (CAT_COL_TYPE.equals(col.getName())) {
catalogRow[idx] = TYPE_TABLE;
} else if (CAT_COL_DATE_CREATE.equals(col.getName()) ||
CAT_COL_DATE_UPDATE.equals(col.getName())) {
catalogRow[idx] = creationTime;
} else if (CAT_COL_PARENT_ID.equals(col.getName())) {
catalogRow[idx] = _tableParentId;
} else if (CAT_COL_FLAGS.equals(col.getName())) {
catalogRow[idx] = Integer.valueOf(0);
} else if (CAT_COL_OWNER.equals(col.getName())) {
byte[] owner = new byte[2];
catalogRow[idx] = owner;
owner[0] = (byte) 0xcf;
owner[1] = (byte) 0x5f;
}
}
_systemCatalog.addRow(catalogRow);
}
/**
* Add a new table to the system's access control entries
* @param pageNumber Page number that contains the table definition
*/
private void addToAccessControlEntries(int pageNumber) throws IOException {
if(_newTableSIDs.isEmpty()) {
initNewTableSIDs();
}
Column acmCol = _accessControlEntries.getColumn(ACE_COL_ACM);
Column inheritCol = _accessControlEntries.getColumn(ACE_COL_F_INHERITABLE);
Column objIdCol = _accessControlEntries.getColumn(ACE_COL_OBJECT_ID);
Column sidCol = _accessControlEntries.getColumn(ACE_COL_SID);
// construct a collection of ACE entries mimicing those of our parent, the
// "Tables" system object
List aceRows = new ArrayList(_newTableSIDs.size());
for(byte[] sid : _newTableSIDs) {
Object[] aceRow = new Object[_accessControlEntries.getColumnCount()];
aceRow[acmCol.getColumnIndex()] = SYS_FULL_ACCESS_ACM;
aceRow[inheritCol.getColumnIndex()] = Boolean.FALSE;
aceRow[objIdCol.getColumnIndex()] = Integer.valueOf(pageNumber);
aceRow[sidCol.getColumnIndex()] = sid;
aceRows.add(aceRow);
}
_accessControlEntries.addRows(aceRows);
}
/**
* Determines the collection of SIDs which need to be added to new tables.
*/
private void initNewTableSIDs() throws IOException
{
// search for ACEs matching the tableParentId. use the index on the
// objectId column if found (should be there)
Cursor cursor = createCursorWithOptionalIndex(
_accessControlEntries, ACE_COL_OBJECT_ID, _tableParentId);
for(Map row : cursor) {
Integer objId = (Integer)row.get(ACE_COL_OBJECT_ID);
if(_tableParentId.equals(objId)) {
_newTableSIDs.add((byte[])row.get(ACE_COL_SID));
}
}
if(_newTableSIDs.isEmpty()) {
// if all else fails, use the hard-coded default
_newTableSIDs.add(SYS_DEFAULT_SID);
}
}
/**
* Reads a table with the given name from the given pageNumber.
*/
private Table readTable(String name, int pageNumber, boolean useBigIndex)
throws IOException
{
_pageChannel.readPage(_buffer, pageNumber);
byte pageType = _buffer.get(0);
if (pageType != PageTypes.TABLE_DEF) {
throw new IOException("Looking for " + name + " at page " + pageNumber +
", but page type is " + pageType);
}
return new Table(this, _buffer, pageNumber, name, useBigIndex);
}
/**
* Creates a Cursor restricted to the given column value if possible (using
* an existing index), otherwise a simple table cursor.
*/
private static Cursor createCursorWithOptionalIndex(
Table table, String colName, Object colValue)
throws IOException
{
try {
return new CursorBuilder(table)
.setIndexByColumns(table.getColumn(colName))
.setSpecificEntry(colValue)
.toCursor();
} catch(IllegalArgumentException e) {
LOG.info("Could not find expected index on table " + table.getName());
}
// use table scan instead
return Cursor.createCursor(table);
}
/**
* Copy an existing JDBC ResultSet into a new table in this database
*
* @param name Name of the new table to create
* @param source ResultSet to copy from
*
* @return the name of the copied table
*
* @see ImportUtil#importResultSet(ResultSet,Database,String)
*/
public String copyTable(String name, ResultSet source)
throws SQLException, IOException
{
return ImportUtil.importResultSet(source, this, name);
}
/**
* Copy an existing JDBC ResultSet into a new table in this database
*
* @param name Name of the new table to create
* @param source ResultSet to copy from
* @param filter valid import filter
*
* @return the name of the imported table
*
* @see ImportUtil#importResultSet(ResultSet,Database,String,ImportFilter)
*/
public String copyTable(String name, ResultSet source, ImportFilter filter)
throws SQLException, IOException
{
return ImportUtil.importResultSet(source, this, name, filter);
}
/**
* Copy a delimited text file into a new table in this database
*
* @param name Name of the new table to create
* @param f Source file to import
* @param delim Regular expression representing the delimiter string.
*
* @return the name of the imported table
*
* @see ImportUtil#importFile(File,Database,String,String)
*/
public String importFile(String name, File f, String delim)
throws IOException
{
return ImportUtil.importFile(f, this, name, delim);
}
/**
* Copy a delimited text file into a new table in this database
*
* @param name Name of the new table to create
* @param f Source file to import
* @param delim Regular expression representing the delimiter string.
* @param filter valid import filter
*
* @return the name of the imported table
*
* @see ImportUtil#importFile(File,Database,String,String,ImportFilter)
*/
public String importFile(String name, File f, String delim,
ImportFilter filter)
throws IOException
{
return ImportUtil.importFile(f, this, name, delim, filter);
}
/**
* Copy a delimited text file into a new table in this database
*
* @param name Name of the new table to create
* @param in Source reader to import
* @param delim Regular expression representing the delimiter string.
*
* @return the name of the imported table
*
* @see ImportUtil#importReader(BufferedReader,Database,String,String)
*/
public String importReader(String name, BufferedReader in, String delim)
throws IOException
{
return ImportUtil.importReader(in, this, name, delim);
}
/**
* Copy a delimited text file into a new table in this database
* @param name Name of the new table to create
* @param in Source reader to import
* @param delim Regular expression representing the delimiter string.
* @param filter valid import filter
*
* @return the name of the imported table
*
* @see ImportUtil#importReader(BufferedReader,Database,String,String,ImportFilter)
*/
public String importReader(String name, BufferedReader in, String delim,
ImportFilter filter)
throws IOException
{
return ImportUtil.importReader(in, this, name, delim, filter);
}
/**
* Flushes any current changes to the database file to disk.
*/
public void flush() throws IOException {
_pageChannel.flush();
}
/**
* Close the database file
*/
public void close() throws IOException {
_pageChannel.close();
}
/**
* @return A table or column name escaped for Access
*/
static String escape(String s) {
if (isReservedWord(s)) {
return ESCAPE_PREFIX + s;
}
return s;
}
/**
* @return {@code true} if the given string is a reserved word,
* {@code false} otherwise
*/
public static boolean isReservedWord(String s) {
return RESERVED_WORDS.contains(s.toLowerCase());
}
/**
* Validates an identifier name.
*/
public static void validateIdentifierName(String name,
int maxLength,
String identifierType)
{
if((name == null) || (name.trim().length() == 0)) {
throw new IllegalArgumentException(
identifierType + " must have non-empty name");
}
if(name.length() > maxLength) {
throw new IllegalArgumentException(
identifierType + " name is longer than max length of " + maxLength +
": " + name);
}
}
@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}
/**
* Adds a table to the _tableLookup and resets the _tableNames set
*/
private void addTable(String tableName, Integer pageNumber)
{
_tableLookup.put(toLookupTableName(tableName),
new TableInfo(pageNumber, tableName));
// clear this, will be created next time needed
_tableNames = null;
}
/**
* @return the tableInfo of the given table, if any
*/
private TableInfo lookupTable(String tableName) {
return _tableLookup.get(toLookupTableName(tableName));
}
/**
* @return a string usable in the _tableLookup map.
*/
private String toLookupTableName(String tableName) {
return ((tableName != null) ? tableName.toUpperCase() : null);
}
/**
* Returns {@code true} if "big index support" has been enabled explicity on
* the this Database or via a system property, {@code false} otherwise.
*/
public boolean defaultUseBigIndex() {
return doUseBigIndex() || Boolean.getBoolean(USE_BIG_INDEX_PROPERTY);
}
/**
* Utility class for storing table page number and actual name.
*/
private static class TableInfo
{
public final Integer pageNumber;
public final String tableName;
private TableInfo(Integer newPageNumber,
String newTableName) {
pageNumber = newPageNumber;
tableName = newTableName;
}
}
/**
* Table iterator for this database, unmodifiable.
*/
private class TableIterator implements Iterator
{
private Iterator _tableNameIter;
private TableIterator() {
_tableNameIter = getTableNames().iterator();
}
public boolean hasNext() {
return _tableNameIter.hasNext();
}
public void remove() {
throw new UnsupportedOperationException();
}
public Table next() {
if(!hasNext()) {
throw new NoSuchElementException();
}
try {
return getTable(_tableNameIter.next());
} catch(IOException e) {
throw new IllegalStateException(e);
}
}
}
}