Package com.healthmarketscience.jackcess

Interface Database

  • All Superinterfaces:
    AutoCloseable, 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.

    • 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 of 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.

      • ENABLE_EXPRESSION_EVALUATION_PROPERTY

        static final String ENABLE_EXPRESSION_EVALUATION_PROPERTY
        system property which can be used to disable expression evaluation if necessary. Defaults to true.
        See Also:
        Constant Field Values
        Usage:
        General: This field is general use.

      • DATE_TIME_TYPE_PROPERTY

        static final String DATE_TIME_TYPE_PROPERTY
        system property which can be used to set the default date/Time type. Value should be one of DateTimeType enum values.
        See Also:
        Constant Field Values
        Usage:
        General: This field is general use.

      • WRITE_BROKEN_INDEX_PROPERTY

        static final String WRITE_BROKEN_INDEX_PROPERTY
        (boolean) system property which can be used to allow writing indexes with unsupported text sort orders. Defaults to false. When enabled, instead of failing, an index with an unsupported text sort order will be written using the general legacy sort order. This allows the database to be created with all the structure necessary by jackcess, and then the index can be fixed by using "compact and repair" in MS Access.
        See Also:
        Constant Field Values
        Usage:
        Intermediate: This field requires moderate API knowledge.

      • ALLOW_LINK_RESOLUTION_PROPERTY

        static final String ALLOW_LINK_RESOLUTION_PROPERTY
        (boolean) system property which can be used to allow resolution of linked databases when no LinkResolver has been configured. Defaults to false, in which case LinkResolver.DEFAULT refuses to open any linked database. When enabled, LinkResolver.UNRESTRICTED is used instead, which opens whatever file name the linking database specifies. Since that file name comes from the database file itself, only enable this when the linked database file names can be trusted.
        See Also:
        Constant Field Values
        Usage:
        Intermediate: This field requires moderate API knowledge.

    • Method Detail

      • getFile

        File getFile()
        Returns the File underlying this Database

      • getPath

        Path getPath()
        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:
        UncheckedIOException - 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.

      • stream

        default Stream<Table> stream()
        Returns:
        a Stream using the default Iterator.

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

      • newTableMetaDataIterable

        Iterable<TableMetaData> newTableMetaDataIterable()
        Returns:
        an Iterable which returns an unmodifiable Iterator of the the TableMetaData for all tables in this Database.
        Throws:
        UncheckedIOException - 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:
        Intermediate: This method requires moderate API knowledge.

      • 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 AutoCloseable
        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.

      • 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 and aligned with the ZoneId).
        Usage:
        Intermediate: This method requires moderate API knowledge.

      • setTimeZone

        void setTimeZone​(TimeZone newTimeZone)
        Sets a new TimeZone. If null, resets to the default value. Note that setting the TimeZone will alter the ZoneId as well.
        Usage:
        Intermediate: This method requires moderate API knowledge.

      • getZoneId

        ZoneId getZoneId()
        Gets currently configured ZoneId (always non-null and aligned with the TimeZone).
        Usage:
        Intermediate: This method requires moderate API knowledge.

      • setZoneId

        void setZoneId​(ZoneId newZoneId)
        Sets a new ZoneId. If null, resets to the default value. Note that setting the ZoneId will alter the TimeZone as well.
        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.

      • isEvaluateExpressions

        boolean isEvaluateExpressions()
        Gets the current expression evaluation policy. Expression evaluation is enabled by default but can be disabled if necessary.

      • setEvaluateExpressions

        void setEvaluateExpressions​(Boolean evaluateExpressions)
        Sets the current expression evaluation policy. Expression evaluation is enabled by default but can be disabled if necessary. If null, resets to the default value.
        Usage:
        Intermediate: This method requires moderate API knowledge.

      • isWriteBrokenIndex

        boolean isWriteBrokenIndex()
        Gets the current write broken index policy. See WRITE_BROKEN_INDEX_PROPERTY for details.
        Usage:
        Intermediate: This method requires moderate API knowledge.

      • setWriteBrokenIndex

        void setWriteBrokenIndex​(Boolean writeBrokenIndex)
        Sets the current write broken index policy. 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.

      • getEvalConfig

        EvalConfig getEvalConfig()
        Returns the EvalConfig for configuring expression evaluation.

      • getDateTimeType

        DateTimeType getDateTimeType()
        Gets the currently configured DateTimeType.
        Usage:
        General: This method is general use.

      • setDateTimeType

        void setDateTimeType​(DateTimeType dateTimeType)
        Sets the DateTimeType. If null, resets to the default value.
        Usage:
        General: This method is general use.