Package acdp.design

Class CustomDatabase

java.lang.Object
acdp.design.CustomDatabase
All Implemented Interfaces:
AutoCloseable
public abstract class CustomDatabase extends Object implements AutoCloseable
Defines the super class of a custom database class. (See the section "Weakly and Strongly Typed" in the description of the Database interface to learn about the motivation of a custom database class.)

At a minimum, a concrete custom database class declares for each table a variable (typically with the final modifier) referencing that table, for example, 

 final MyTable myTable = new MyTable();
where MyTable denotes a concrete subclass of the CustomTable class. The table variable can be declared as a class variable, hence, with a static modifier unless the table class is reused in this custom database or the table class is reused in another custom database and that custom database is opened at a time this database is open.

If you plan to use the Setup Tool for creating the database layout and all backing files of the database then make sure that your custom database class is annotated with the @SetupDatabase annotation and that all of your table declarations are annotated with the @SetupTableDeclaration annotation, for example, 

 @SetupDatabase(
    name = "My Database",
    tables = { "My Table", "Your Table" }
 )
 class MyDB extends CustomDatabase {
    @SetupTableDeclaration("My Table")
    final MyTable myTable = new MyTable();
    @SetupTableDeclaration("Your Table")
    final YourTable yourTable = new YourTable();
 
    MyDB(...) {
       open(..., myTable, yourTable);
    }
 }

Since an ACDP database must finally be closed, you may want to apply the try-with-resources statement like this (MyDB denotes a subclass of the CustomDatabase class): 

 try (MyDB db = new MyDB(...)) {
    MyTable myTable = db.myTable;  // or MyDB.MY_TABLE if MY_TABLE is declared
                                   // as a final class variable.
    do something with myTable
 }
This code snippet also shows how to access a particular table (here the "My Table") from a strongly typed custom database. Compare this to the corresponding code snippet in the Database class description.
Author:
Beat Hörmann

  • Constructor Details

    • CustomDatabase

      protected CustomDatabase()
      Constructs but does not open the database.

  • Method Details

    • isOpen

      protected final boolean isOpen()
      Returns the information whether the database is open or closed.
      Returns:
      The boolean value true if and only if the database is open.

    • open

      protected final void open(Path mainFile, int opMode, boolean writeProtect, ICipherFactory cipherFactory, int consistencyNumber, CustomTable... customTables) throws NullPointerException, IllegalArgumentException, ConsistencyException, InvalidPathException, ImplementationRestrictionException, OverlappingFileLockException, CreationException, IllegalStateException
      Opens the database as a strongly typed database.

      As long as the database is empty, or as soon as it is empty again, the type of encryption can be defined (or redefined) with the cipherFactory argument.

      The order of the custom tables in the specified array of custom tables must be the same as the order in which the corresponding table layouts appear in the database layout.

      The database can only be opened once. This method throws an IllegalStateException if the database is opened again, regardless of whether the database is currently open or closed.

      Parameters:
      mainFile - The main database file, not allowed to be null. If the database is a WR database then the main file is identical to the layout file. Otherwise, the database is an RO database and the main file is identical to the one and only one RO database file.
      opMode - The operating mode of the database. If the value is equal to zero then the backing table files are immediately closed as soon as they become idle. If the value is positive and equal to n then the backing table files are closed max(10, n) milliseconds after they become idle or when the database is closed. If the value is equal to -1 then the backing table files once opened remain open until the database is closed. If the value is equal to -2 then the compressed content of an RO database is completely mapped into memory. If the value is equal to -3 then the uncompressed content of an RO database is completely mapped into memory. A value equal to zero is recommended only if the database is a WR database and the operating system can't sustain a bunch of files all being opened at the same time. In a server environment a positive value is recommended or, provided that the database is an RO database and there is enough memory available, a value equal to -2 (less memory required, less fast) or -3 (more memory required, faster). Note that a value equal to -2 or equal to -3 raises an IllegalArgumentException if the database is a WR database.
      writeProtect - Protects the database from being written. If set to true then no data can be modified in any of the database's tables. Note that this parameter has no effect if the database is an RO database. A read-only database needs less system resources than a writable database.
      cipherFactory - The cipher factory or null if no encryption is required.
      consistencyNumber - The consistency number of the database. This value must be equal to the corresponding value saved in the database layout. If this is not the case then this method throws a ConsistencyException.
      customTables - The array of custom tables, not allowed to be null and not allowed to be empty.
      Throws:
      NullPointerException - If mainFile or customTables is null.
      IllegalArgumentException - If opMode is less than -3 or if opMode is equal to -2 or -3 and the database is a WR database.
      ConsistencyException - If the logic of the database is inconsistent with its data.
      InvalidPathException - If the database layout contains an invalid file path. This exception never happens if the database is an RO database.
      ImplementationRestrictionException - If a table has too many columns needing a separate null information. This exception never happens if the database is an RO database.
      OverlappingFileLockException - If the database was already opened before in this process (Java virtual machine) or in another process that holds a lock which cannot co-exist with the lock to be acquired. This exception never happens if the database is an RO database.
      CreationException - If the database can't be created due to any other reason including problems with the database layout, problems with any of the tables' sublayouts, problems regarding encryption, problems with the array of custom tables and problems with the backing files of the database.
      IllegalStateException - If the database was opened before.

    • name

      public final String name() throws IllegalStateException
      See Database.name()
      Returns:
      The name of the database, never null and never an empty string.
      Throws:
      IllegalStateException - If the database was never opened.

    • info

      public final Information.DatabaseInfo info() throws IllegalStateException
      See Database.info()
      Returns:
      The information object of the database, never null.
      Throws:
      IllegalStateException - If the database is closed.

    • getTables

      public final CustomTable[] getTables() throws IllegalStateException
      Returns all tables of this database.

      The order in which the tables appear in the returned array is equal to the order in which the tables appear in the database layout.

      Returns:
      The tables of this database, never null and never empty.
      Throws:
      IllegalStateException - If the database is closed.

    • openUnit

      public final Unit openUnit() throws UnitBrokenException, ShutdownException, ACDPException, IllegalStateException
      See Database.openUnit()
      Returns:
      The unit, never null.
      Throws:
      UnitBrokenException - If the unit is broken.
      ShutdownException - If the database is closed.
      ACDPException - If the database is read-only or if this method is invoked within a read zone.
      IllegalStateException - If the database is closed.

    • openReadZone

      public final ReadZone openReadZone() throws ShutdownException, IllegalStateException
      See Database.openReadZone()
      Returns:
      The read zone, never null.
      Throws:
      ShutdownException - If the synchronization manager is shut down. This exception never happens if the database is read-only.
      IllegalStateException - If the database is closed.

    • createRO

      public final void createRO(Path roDbFilePath, ICipherFactory cipherFactory) throws UnsupportedOperationException, NullPointerException, ImplementationRestrictionException, ShutdownException, CreationException, CryptoException, IOFailureException, IllegalStateException
      See Database.createRO(Path, ICipherFactory)
      Parameters:
      roDbFilePath - The path of the newly created RO database file. The value must be the path of a non-existing file.
      cipherFactory - The cipher factory or null if no encryption is required.
      Throws:
      UnsupportedOperationException - If this database is an RO database.
      NullPointerException - If roDbFilePath is null.
      ImplementationRestrictionException - If at least one of the tables of the WR database has more than Integer.MAX_VALUE rows or if the length of the byte representation of a stored column value of a table of the WR database exceeds Integer.MAX_VALUE or if at least one of the tables of the WR database has too many columns or if the number of row gaps in at least one of the tables of the WR database is greater than Integer.MAX_VALUE.
      ShutdownException - If the database's file channel provider or the synchroniziation manager is shut down. A reason for this exception to happen is that the WR database is closed.
      CreationException - If creating the RO crypto object fails or if computing the cipher challenge fails. This exception never happens if cipherFactory is null.
      CryptoException - If decrypting the byte representation of a stored column value of a table of the WR database fails. This exception never happens if the WR database does not apply encryption.
      IOFailureException - If the specified file already exists or if another I/O error occurs.
      IllegalStateException - If the database is closed.

    • zip

      public final void zip(int level, boolean home, OutputStream out) throws NullPointerException, IllegalArgumentException, ShutdownException, IOFailureException, IllegalStateException
      See Database.zip(int, boolean, OutputStream)
      Parameters:
      level - the compression level or -1 for the default compression level. Valid compression levels are greater than or equal to zero and less than or equal to nine.
      home - The information whether all the files should be unzipped into a single directory with a name equal to the name of the main directory.
      out - The output stream, not allowed to be null.
      Throws:
      NullPointerException - If out is null.
      IllegalArgumentException - If the compression level is invalid.
      ShutdownException - If the database's file channel provider or the synchroniziation manager is shut down. A reason for this exception to happen is that the WR database is closed.
      IOFailureException - If an I/O error occurs.
      IllegalStateException - If the database is closed.

    • forceWrite

      public final void forceWrite() throws IOFailureException, IllegalStateException
      See Database.forceWrite()
      Throws:
      IOFailureException - If an I/O error occurs.
      IllegalStateException - If the database is closed.

    • customClose

      protected void customClose()
      This method is invoked by the close() method immediately before the database is closed, provided that the database is open.

      This implementation does nothing. Subclasses may want to override this method to close, for example, an index file.

    • close

      public final void close() throws IOFailureException
      Closes this database and releases any system resources associated with it.

      Note that closing the database is final: Reopening the database by invoking the open method will fail.

      If the database is closed then invoking this method has no effect.

      Specified by:
      close in interface AutoCloseable
      Throws:
      IOFailureException - if an I/O error occurs.

    • toString

      public String toString() throws IllegalStateException
      See Database.toString()
      Overrides:
      toString in class Object
      Throws:
      IllegalStateException - If the database was never opened.