Package acdp.tools

Class Setup

java.lang.Object
acdp.tools.Setup
public final class Setup extends Object
Assists with setting up a database once the concrete custom database class, the concrete custom table classes and the optional custom column types have been coded. All generated files, among them the database's layout file, are saved into a single directory. As a side effect, the Setup Tool checks the coded classes for correctness and writes a meaningful message to the standard output stream in the case of an error.

The Setup Tool needs as input the name of the database class, that is, a concrete subclass of the CustomDatabase class. In order for the Setup Tool to be able to process the database class, the database class and the table classes must be annotated as described in the descriptions of the CustomDatabase and the CustomTable classes. Needless to say that such annotations are only required for setting up the database. They can be removed once the database is setup.

Although the generated database layout, containing the nested layouts of the tables and columns, is complete and can be immediately used to open the database, you may want to manually customize it to suit your personal needs, for example for adding some comments (comment lines in a layout begin with the number sign ('#') character), for renaming or relocating the generated backing files of the database or for reducing the values of the table-specific settings nobsRowRef, nobsOutrowPtr and nobsRefCount to get a more compact storage format. (For an explanation of these fields read chapter "Explanation of the nobsRowRef, nobsOutrowPtr and nobsRefCount Settings" at the bottom.) Of course, all this can also be done later when some data has made its way into the database, but then no longer manually because there is a risk of data integrity violation. Use the methods defined in the Settings class to view all database settings stored in the layout file and to modify some of them or refactor the database to safely change the structure of the database.

If a table has a custom column type (contrary to a built-in column type) then its annotated type factory method is assumed to be a member of the class defining that custom column type. If this is not the case then please change the value of the typeFactoryClassName field of the corresponding column sublayout accordingly. On this occasion, you may want to add the typeFactoryClasspath field in that column sublayout with a value equal to the directory housing the class file of the class that defines the type factory class method and any depending class files. Of course, this is only necessary if those class files are not yet on the classpath which may be the case if the database is opened as a weakly typed database. (You can also put your class files inside a JAR file and save it into the directory specified by the typeFactoryClasspath layout field or into any subdirectory of this directory.)

When running the Setup Tool it is not necessary to specify whether the data in the database should be encrypted or not. As long as the database is empty, or as soon as it is empty again, the type of encryption can be defined (or redefined) when opening the empty database.

The Setup Tool can be run from the main(java.lang.String[]) method or by invoking the run(java.lang.String, java.nio.file.Path) method.

Explanation of the nobsRowRef, nobsOutrowPtr and nobsRefCount Settings

Each table is roughly sized by the values of the following three parameters which appear in the store section of the table layout: The nobsRowRef, nobsOutrowPtr and nobsRefCount parameters. (The abbreviation nobs stands for "number of bytes".)

nobsRowRef

The value of the nobsRowRef parameter limits the number of rows in the table to 256nobsRowRef - 1, e.g., 65535 if nobsRowRef is equal to 2. The value of nobsRowRef cannot be greater than 8 and if it is 8 then the size of the table is limited to the absolute maximum of Long.MAX_VALUE ≈ 9⋅1018 rows. (In practice, this is not a limitation if we keep in mind that a file cannot be larger than Long.MAX_VALUE bytes.) The size of the byte representation of a reference is identical to the value of this parameter.

nobsOutrowPtr

Table data from columns with an outrow storage scheme or being of an inrow array type having an outrow element type is stored in a separate file, the so called "VL data file". Outrow data is referenced by a file position that locates the start of the outrow data within the VL data file. The file position is an unsigned integer of length equal to the value of the nobsOutrowPtr parameter thus limiting the size of the VL data file by the size of all blocks with a file position less than 256nobsOutrowPtr - 1. As with the nobsRowRef parameter, the value of nobsOutrowPtr cannot be greater than 8 and if it is 8 then the size of the file storing the outrow data of the table is limited to the absolute maximum of Long.MAX_VALUE bytes which is around eight million terabytes. This parameter is missing if the table doesn't store any outrow data.

nobsRefCount

The value of the nobsRefCount parameter limits the number of rows that can reference a particular row within the table to 256nobsRefCount-1, e.g., 255 if nobsRefCount is equal to 1. As with the other two fields, the value of nobsRefCount cannot be greater than 8 and if it is 8 then the number of rows referencing a particular row within the table is limited to the absolute maximum of Long.MAX_VALUE ≈ 9⋅1018 rows. This parameter is missing if none of the tables of the database (including this table) has a column referencing this table.

The Setup Tool sets these three parameters to their maximum value of 8. As long as the table is empty you can reduce these values by simply editing the database layout file manually, but with one exception concerning the nobsRowRef parameter of a table referenced by other tables, because changing this parameter changes the size of the byte representation of a reference, which may change the length of the referencing column and thus the length of the row of the referencing table. However, this is not a problem if the referencing tables are empty. Anyway, to be on the safe side, these values should to be changed by refactoring the database, hence, by invoking one of the following three methods: Refactor.nobsRowRef(java.nio.file.Path, java.lang.String, int), Refactor.nobsOutrowPtr(java.nio.file.Path, java.lang.String, int), and Refactor.nobsRefCount(java.nio.file.Path, java.lang.String, int). Note that if these values are reduced too much, the risk increases that the corresponding maximum values described above are exceeded. ACDP throws a MaximumException if the maximum values determined by these parameters are to be exceeded.

Author:
Beat Hörmann

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Setup.SetupColumn
    The @SetupColumn annotation is used by the Setup Tool to identify the column objects declared within a table class.
    static @interface 
    Setup.SetupDatabase
    The @SetupDatabase annotation is used by the Setup Tool to get the name of the database and the names of the database's tables.
    static @interface 
    Setup.SetupTable
    The @SetupTable annotation is used by the Setup Tool to get the names of the table's columns.
    static @interface 
    Setup.SetupTableDeclaration
    The @SetupTableDeclaration annotation is used by the Setup Tool to identify a table declaration within the database class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static final void
    main(String[] args)
    The main method invoking the run(java.lang.String, java.nio.file.Path) method.
    static final void
    run(String dbcn, Path dir)
    Generates the database files from a database class, hence, from a class annotated with the @SetupDatabase annotation and saves them to a given directory.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • run

      public static final void run(String dbcn, Path dir) throws IOFailureException
      Generates the database files from a database class, hence, from a class annotated with the @SetupDatabase annotation and saves them to a given directory.

      This method may throw an exception that is different from the listed exception.

      Parameters:
      dbcn - The name of the database class, for instance "com.example.MyDB". The database class is the class annotated with @SetupDatabase.
      dir - The directory where the generated database files are to be saved. If this value is null then this method takes as directory the value returned by a call to Paths.get(dbName) where dbName denotes the name of the database.
      Throws:
      IOFailureException - If saving the genereated database files fails.

    • main

      public static final void main(String[] args) throws IllegalArgumentException, IOFailureException
      The main method invoking the run(java.lang.String, java.nio.file.Path) method.

      The first element of the args array must contain the name of the database class, for instance "com.example.MyDB". If the args array contains a second element then this element is assumed to denote the directory where to save the generated database files. If the args array does not contain a second element then the generated database files are saved to the directory obtained by a call to Paths.get(dbName) where dbName denotes the name of the database.

      This method may throw an exception that is different from the listed exceptions.

      Parameters:
      args - The command-line arguments. See the method description for details.
      Throws:
      IllegalArgumentException - If args is empty or contains more than two elements.
      IOFailureException - If saving the genereated database files fails.