Package acdp.tools

Class Refactor

java.lang.Object
acdp.tools.Refactor
public final class Refactor extends Object
Provides methods for changing the structure of a WR database as well as methods for changing some fundamental table parameters which involve the modification of the internal format of one or more backing files.

The methods assume that the database is closed. They can be applied no matter if the database is empty or houses some persisted data. The methods change the database layout.

Check the Settings class in case you miss a method.

Author:
Beat Hörmann

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Refactor.Names
    Declares methods for fluently creating a list where each element is equal to a column name and, provided that the column references a table, the name of the referenced table.

  • Method Summary

    Modifier and Type
    Method
    Description
    static final void
    addTable(Path layoutFile, String tableName, CustomTable table, Refactor.Names names)
    Adds the specified table to the specified WR database.
    static final double
    dropColumn(Path layoutFile, String tableName, String columnName)
    Removes the specified column from the specified table.
    static final void
    dropTable(Path layoutFile, String tableName)
    Removes the specified table from the specified WR database.
    static final <T> void
    insertColumn(Path layoutFile, ICipherFactory cipherFactory, String tableName, String columnName, Column<T> column, String refdTableName, int index, T initialValue)
    Inserts the specified column into the table definition of the specified table at the position given by the index argument.
    static final <T> double
    modifyColumn(Path layoutFile, ICipherFactory cipherFactory, String tableName, String columnName, Column<T> column, Table.ValueSwitcher<T> valueSwitcher)
    Modifies the specified column of the specified table by replacing that column with the specified new column.
    static final Refactor.Names
    names()
    Creates an instance of a class implementing the Refactor.Names interface.
    static final void
    nobsOutrowPtr(Path layoutFile, String tableName, int value)
    Changes the value of the nobsOutrowPtr property of the specified table to the specified value.
    static final void
    nobsRefCount(Path layoutFile, String tableName, int value)
    Changes the value of the nobsRefCount property of the specified table to the specified value.
    static final void
    nobsRowRef(Path layoutFile, String tableName, int value)
    Changes the value of the nobsRowRef property of the specified table to the specified value.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • names

      public static final Refactor.Names names()
      Creates an instance of a class implementing the Refactor.Names interface.
      Returns:
      The created instance, never null.

    • addTable

      public static final void addTable(Path layoutFile, String tableName, CustomTable table, Refactor.Names names) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, OverlappingFileLockException, CreationException, IOFailureException
      Adds the specified table to the specified WR database.

      The table definition of the newly added table is given by the specified custom table. To provide names for the columns and the referenced tables for the first, second, etc. column in the table definition apply method chaining like this: 

       Refactor.names().add("c1").add("c2", "t").add("c3")
      where "c1", "c2" and "c3" are the desired names of the first, second and third column and "t" is the name of the table referenced by column "c2". (It is assumed that only the second column references a table.)

      Adding a table includes adding a new table layout to the database layout. Moreover, if the new table references some other tables which are not yet referenced then the nobsRefCount field is added to the table layouts of these newly referenced tables and the tables are refactored accordingly. As described in the Setup Tool, you may want to review the new fields in the database layout and customize them to suit your personal needs.

      Don't forget to insert the custom table in your custom database at the end of the list containing the custom tables.

      This method fails if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      tableName - The name of the table to be added to the database, not allowed to be null and not allowed to be an empty string and not allowed to start with the number sign ('#') character. This method fails if a table with this name already exists in the database.
      table - The custom table, not allowed to be null.
      names - The column names and the names of the referenced tables, not allowed to be null.
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If at least one of layoutFile, table, and names is null.
      IllegalArgumentException - If tableName is null or an empty string or starts with the number sign character ('#') or if a table with this name already exists in the database or if the table definition of the specified custom table is null or if names is null or returns an empty list or contains a name of a referenced table that is not equal to the tableName argument and that is not the name of a table in the database or if the table definition and the list of names do not correspond to each other.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If the layout file does not exist or if one of the backing files of the new table already exists or if another I/O error occurs.

    • dropTable

      public static final void dropTable(Path layoutFile, String tableName) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, OverlappingFileLockException, CreationException, IOFailureException
      Removes the specified table from the specified WR database.

      Removing a table includes removing the table layout of the table from the database layout. Moreover, if the table references some other tables and no other tables reference these tables then the nobsRefCount field is removed from the table layouts of these tables and the tables are refactored accordingly.

      Don't forget to remove the corresponding custom table from your custom database.

      This method fails if the specified table is the only table in the database or if the table is referenced by another table or if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      tableName - The name of the table to be dropped from the database, not allowed to be null.
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If layoutFile is null.
      IllegalArgumentException - If tableName is null or if the database has no table with this name or if this table is the only table in the database or if there exists another table that references this table.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If the layout file does not exist or if another I/O error occurs.

    • insertColumn

      public static final <T> void insertColumn(Path layoutFile, ICipherFactory cipherFactory, String tableName, String columnName, Column<T> column, String refdTableName, int index, T initialValue) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, MaximumException, CryptoException, ImplementationRestrictionException, OverlappingFileLockException, CreationException, IOFailureException
      Inserts the specified column into the table definition of the specified table at the position given by the index argument. The new column will have an index equal to the value of index while columns with an index greater than or equal to the value of index will have their index incremented by one.

      Inserting a new column includes inserting a new column layout into the table layout. Moreover, if the column is a column storing its values in the VL file space and no other column of the table stores its values in the VL file space yet then this method creates the VL data file and adds the fields vlDataFile and nobsOutrowPtr to the layout of the table. Furthermore, if the column references a table that is not yet referenced, then the nobsRefCount field is added to the layout of the newly referenced table and the table is refactored accordingly. As described in the Setup Tool, you may want to review these new fields in the database layout and customize them to suit your personal needs. (Use the nobsOutrowPtr(java.nio.file.Path, java.lang.String, int) and nobsRefCount(java.nio.file.Path, java.lang.String, int) methods if you want to reduce the values of the nobsOutrowPtr and nobsRefCount fields, respectively.)

      The following restrictions with respect to the specified initial value apply if the new column is a reference column. (A reference column is a column with a type equal to RefType or ArrayOfRefType.)

      • If the new column has a type equal to RefType then the specified initial value must be null.
      • If the new column has a type equal to ArrayOfRefType then the specified initial value must either be null, an empty array or the references contained in the array must all be null.

      Don't forget to create and insert the new column within your corresponding custom table.

      This method fails if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Type Parameters:
      T - The value type of the new column.
      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      cipherFactory - The cipher factory or null if no encryption is required.
      tableName - The name of the table, not allowed to be null.
      columnName - The name of the column to be inserted into the table, not allowed to be null.
      column - The column to be inserted, not allowed to be null.
      refdTableName - The name of the referenced table. This value is not allowed to be null if the column is a reference column. This value is ignored if the column is not a reference column.
      index - The index within the table definition where the column is to be inserted, must satisfy 0 ≤ index ≤ n, where n denotes the number of columns in the table.
      initialValue - The initial value. Existing rows of the table are filled with this value in the new column. Note the restrictions mentioned in the method description if the new column is a reference column.
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If layoutFile or column is null.
      IllegalArgumentException - If the database has no table equal to tableName or if columnName is null or an empty string or if the table already has a column with such a name. This exception also happens if the insertion index is negative or greater than the number of columns in the table or if the column to be inserted is a reference column but the database has no table equal to the refdTableName argument or the column to be inserted is a reference column but the initial value violates the restrictions mentioned in the method description. The exception also happens if the length of the byte representation of the initial value (or one of the elements if the initial value is an array value) exceeds the maximum length allowed by the simple column type.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position
      CryptoException - If encryption fails. This exception never happens if the database does not apply encryption.
      ImplementationRestrictionException - If the Null-info must be expanded by a single bit but the bitmap is too large for being expanded or if the new size of the FL data blocks exceeds Integer.MAX_VALUE.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If an I/O error occurs.

    • dropColumn

      public static final double dropColumn(Path layoutFile, String tableName, String columnName) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, OverlappingFileLockException, CreationException, IOFailureException
      Removes the specified column from the specified table.

      Removing a column includes removing the column layout of the column from the table layout. Moreover, if the column is a column storing its values in the VL file space and no other column of the table stores its values in the VL file space then this method deletes the VL data file and removes the fields vlDataFile and nobsOutrowPtr from the layout of the table. Furthermore, if the column references a table and no other column of any table references that table then the nobsRefCount field is removed from the layout of that table and the table is refactored accordingly.

      Don't forget to remove the column from your corresponding custom table.

      This method fails if the specified column is the only column of the table or if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      tableName - The name of the table, not allowed to be null.
      columnName - The name of the column to be dropped from the table, not allowed to be null.
      Returns:
      The size of the unused VL file space in relation to its total size. For instance, a value equal to 0.9 means that 9 out of 10 bytes of the VL file space are unused. If there is no unused VL file space then this method returns 0. If the VL file space was removed by this method or if this store never had a VL file space than this method returns -1.0. The returned value may be used to decide whether it is appropriate to compact the VL file space or not. (Removing a VL column may significantly increase the amount of unused VL file space.)
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If layoutFile is null.
      IllegalArgumentException - If the database has no table equal to tableName or if the table has no column equal to columnName or if the specified column is the only column of the table.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If an I/O error occurs.

    • modifyColumn

      public static final <T> double modifyColumn(Path layoutFile, ICipherFactory cipherFactory, String tableName, String columnName, Column<T> column, Table.ValueSwitcher<T> valueSwitcher) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, MaximumException, CryptoException, ImplementationRestrictionException, OverlappingFileLockException, CreationException, IOFailureException
      Modifies the specified column of the specified table by replacing that column with the specified new column.

      All kinds of modifications are allowed with the following two exceptions:

      Modifying the value type of a column type, be it the value type of a SimpleType or the value type of the component type of an ArrayType, requires that the user provides a value switcher which converts the stored values into new values that must be compatible with the new value type. (If the value switcher returns a value that is not compatible with the new value type then this method throws an exception, however, this may be an exception of a type not listed below.) If the value type remains unchanged then the valueSwitcher argument may be equal to null which means that the values remain unchanged (identity conversion). This method may be invoked in such a way that the column type remains unchanged. If a value switcher is specified at the same time, this method internally executes the Table.updateAllChangeValues(acdp.Column<T>, acdp.Table.ValueChanger<T>) method, otherwise the valueSwitcher argument is equal to null and this method does nothing.

      Modifying a column includes changing the column layout of the column to be modified. Moreover, if the column replacing the column to be modified is a column storing its values in the VL file space and no column of the table stores its values in the VL file space yet then this method creates the VL data file and adds the fields vlDataFile and nobsOutrowPtr to the layout of the table. As described in the Setup Tool, you may want to review these new fields in the database layout and customize them to suit your personal needs. (Use the nobsOutrowPtr(java.nio.file.Path, java.lang.String, int) method if you want to reduce the value of the nobsOutrowPtr field.) Conversely, if the column to be modified is a column storing its values in the VL file space and no other column of the table stores its values in the VL file space and the column replacing the column to be modified stores its values in the FL file space then this method deletes the VL data file and removes the vlDataFile and nobsOutrowPtr fields from the layout of the table.

      Don't forget to modify the column accordingly within your corresponding custom table.

      This method fails if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Type Parameters:
      T - The value type of the new column.
      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      cipherFactory - The cipher factory or null if no encryption is required.
      tableName - The name of the table, not allowed to be null.
      columnName - The name of the column to be modified, not allowed to be null.
      column - The column replacing the column to be modified, not allowed to be null.
      valueSwitcher - The value switcher, may be null in some cases. This value is ignored if the table is an empty table or if the type of the column replacing the column to be modified is an array of references.
      Returns:
      The size of the unused VL file space in relation to its total size. For instance, a value equal to 0.9 means that 9 out of 10 bytes of the VL file space are unused. If there is no unused VL file space then this method returns 0. If the VL file space was removed by this method or if this store never had a VL file space than this method returns -1.0. The returned value may be used to decide whether it is appropriate to compact the VL file space or not. (Modifying a VL column may significantly increase the amount of unused VL file space.)
      Throws:
      UnsupportedOperationException - If the database is an RO database or if the modification requires an unsupported modification involving reference columns.
      NullPointerException - If one of the arguments not allowed to be null is null or if a value of a simple column type is set equal to null but the column type forbids the null value or if the value is an array value and this condition is satisfied for at least one element contained in the array.
      IllegalArgumentException - If the database has no table equal to tableName or if the table has no column equal to columnName or if valueSwitcher is null but is not allowed to be null in combination with the other arguments. This exception also happens if the length of the byte representation of a value (or one of the elements if the value is an array value) exceeds the maximum length allowed by the simple column type. Furthermore, this exception happens if the value is an array value and the size of the array exceeds the maximum length allowed by the array column type.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position.
      CryptoException - If encryption or decryption fails. This exception never happens if the WR database does not apply encryption or if the column type is an array of references.
      ImplementationRestrictionException - If the Null-info must be expanded by a single bit but the bitmap is too large for being expanded or if the byte representation stored in the VL file space is too large to fit into the inrow column section or if the number of bytes needed to persist a value of an array type exceeds Java's maximum array size or, provided that this method invokes the Table.updateAllChangeValues(acdp.Column<T>, acdp.Table.ValueChanger<T>) method, it turns out that the number of row gaps in the table is greater than Integer.MAX_VALUE or if the new size of the FL data blocks exceeds Integer.MAX_VALUE.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If an I/O error occurs.

    • nobsRowRef

      public static final void nobsRowRef(Path layoutFile, String tableName, int value) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, MaximumException, ImplementationRestrictionException, OverlappingFileLockException, CreationException, IOFailureException
      Changes the value of the nobsRowRef property of the specified table to the specified value. (See the section "Explanation of the nobsRowRef, nobsOutrowPtr and nobsRefCount Settings" in the description of the Setup Tool to learn about this property.)

      The amount of unused VL file space may significantly increase in tables with columns that have an outrow storage scheme and store values being array of references to rows of the specified table. (For a particular table t of a WR database you can get the amount of unused VL file space by executing ((WRStoreInfo) t.info()).storeInfo()).vlUnused().)

      This method fails if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      tableName - The name of the table, not allowed to be null.
      value - The new value of the nobsRowRef table property, must be greater than or equal to 1 and less than or equal to 8. The new value is allowed to be equal to the current value.
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If layoutFile or tableName is null.
      IllegalArgumentException - If the database has no table equal to tableName or if the specified value is less than 1 or greater than 8 or if the specified value is too small with respect to the number of rows and row gaps in the table.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position.
      ImplementationRestrictionException - If the number of bytes needed to persist an array of references in an inrow column exceeds Java's maximum array size.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If an I/O error occurs.

    • nobsOutrowPtr

      public static final void nobsOutrowPtr(Path layoutFile, String tableName, int value) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, ImplementationRestrictionException, OverlappingFileLockException, CreationException, IOFailureException
      Changes the value of the nobsOutrowPtr property of the specified table to the specified value. (See the section "Explanation of the nobsRowRef, nobsOutrowPtr and nobsRefCount Setinngs" in the description of the Setup Tool to learn about this property.)

      This method fails if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      tableName - The name of the table, not allowed to be null.
      value - The new value of the nobsOutrowPtr table property, must be greater than or equal to 1 and less than or equal to 8. The new value is allowed to be equal to the current value.
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If layoutFile or tableName is null.
      IllegalArgumentException - If the database has no table equal to tableName or if the table has no VL file space or if the specified value is less than 1 or greater than 8 or if the specified value is too small with respect to the size of the VL file space.
      ImplementationRestrictionException - If the new size of the FL data blocks exceeds Integer.MAX_VALUE.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If an I/O error occurs.

    • nobsRefCount

      public static final void nobsRefCount(Path layoutFile, String tableName, int value) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, ImplementationRestrictionException, OverlappingFileLockException, CreationException, IOFailureException
      Changes the value of the nobsRefCount property of the specified table to the specified value. (See the section "Explanation of the nobsRowRef, nobsOutrowPtr and nobsRefCount Settings" in the description of the Setup Tool to learn about this property.)

      This method fails if the database is not a WR database or if the database is currently open.

      If the specified file does not contain a valid layout for a WR database then this method may throw an exception that is different from the listed exceptions.

      Caveat: If this method throws an exception then there is a risk that the database is broken. You may want to backup the database before executing this method.

      Parameters:
      layoutFile - The WR database layout file, not allowed to be null.
      tableName - The name of the table, not allowed to be null.
      value - The new value of the nobsRefCount table property, must be greater than or equal to 1 and less than or equal to 8.. The new value is allowed to be equal to the current value.
      Throws:
      UnsupportedOperationException - If the database is an RO database.
      NullPointerException - If layoutFile or tableName is null.
      IllegalArgumentException - If the database has no table equal to tableName or if the table is not referenced by any table of the database or if the specified value is less than 1 or greater than 8 or if the specified value is too small with respect to the row having the highest value of the reference counter.
      ImplementationRestrictionException - If the new size of the FL data blocks exceeds Integer.MAX_VALUE.
      OverlappingFileLockException - If the WR database is currently open.
      CreationException - If the database can't be opened due to any other reason.
      IOFailureException - If an I/O error occurs.