Package acdp

Interface Table

All Superinterfaces:
Iterable<Row>
public interface Table extends Iterable<Row>
The table of a database.

A table has columns and rows. A column defines the type of the values a row can store in that column. The configuration of a table is contained in the table layout which is part of the database layout.

Some important differences between an ACDP table and a relation of a relational database are

  • The collection of rows in a table is a sequence rather than a set. The same holds for the columns of a table.
  • ACDP tables natively persist arrays of values, rendering extra joins over join relations obsolete.
  • A row of an ACDP table can reference a row of the same or another ACDP table in direct analogy to an object referencing another object in main memory.

A row of a table can be viewed as a container housing the persisted data of a particular object.

Weakly and Strongly Typed

An instance of this class is called a weakly typed table because the first access to a specific column of the table can only be done by the name of the column or by its position within the table definition, see the getColumn(String) and getColumns() methods. (The expression "table definition" is explained in section "Structure" below.) Changing the name of the column or changing the position of the column within the table definition, without adapting the code on the client side, breaks the client code. Even worse, the compiler has no chance to detect such inconsistencies. Another drawback is that there is no type safety at compile time regarding the type of the values stored in a particular column of the table's rows.

In contrast to this, a strongly typed table is an instance of a class extending the CustomTable class. An elaborated custom table class can provide tailor-made methods for dealing with all kinds of aspects of entity-specific persistence management. A strongly typed table requires its columns to be instances of a class implementing the Column interface which is parametrized with the type of the column values. Doing something with a particular column is simply doing it with the appropriate column instance.

A weakly typed table is created from the information saved in the table layout only. Therefore, ACDP does not need to know of a custom table class in order to create a weakly typed table. Typically, a database is opened as a weakly typed database, that is, all tables of the database are created as weakly typed tables, if there is no need to make a reference to the concrete entities the tables represent, for example, in a generic tool which displays the content of an arbitrary table.

Structure

The structure of a table comprises the names and types of its columns as well as the characteristic sequence of its columns. The characteristic sequence of columns is sometimes called the table definition.

Name

The name of a table is saved in the table layout and is therefore not part of the table structure. Thus, it is possible to reuse the table's structure for a different content. For instance, think of the entity "screw" and assume that we want to store the diameter and length of all screws in stock. Suppose we want to store this information separately for metal and wood screws. For this purpose we just define the table structure once and reuse it for both screw types.

Store

Each table has a store. A store implements various read/write database operations for reading data from and writing data to the backing files of the store. There are two types of stores: a writable WR store and a read-only RO store. The last one does not support any operations that modify the content of the table. Furthermore, data in the RO stores reside in a single compressed file and can be loaded into main memory, provided that there is enough main memory available. All tables of the database have the same type of store. Store specific parameters are saved in the store layout which is part of the table layout.

Compacting the WR Store

Inserting, deleting and updating table data sooner or later fragments the file spaces of the WR store. A WR store has two file spaces: An FL file space for the fixed length data of the rows and a VL file space for the outrow data of the rows. Typically, compacting the FL file space, which can be done by invoking the compactFL() method, is not necessary because unused memory blocks of the FL file space, or short "row gaps", can be reused by the ACDP file space management. See the description of the Ref interface for further explanations. In contrast to this, deallocated outrow data can't be reused and the total size of unused memory blocks within the VL file space typically grows fast if there are many write operations on outrow values. This is why it makes sense to invoke the compactVL() method from time to time. To find out if it's worth doing so, consult the values returned by the Information.WRStoreInfo.vlUnused() and the Information.WRStoreInfo.vlUsed() methods.

References

Let u and v be two rows of the tables U and V, respectively. Furthermore, assume that u references v by storing in column c of table U a reference. The type of column c declares a reference to be a legal value for this column. However, the type does not specify the referenced table (V in our example). This kind of information is stored in the layout of table U, more precisely, in the layout of column c. (The layouts of the columns are part of the table layout.) Note that cyclic references and even self references are allowed: If table T1 references table T2, that is, there is a column of table T1 referencing a column of table T2, and table T2 references table T3 then T3 is perfectly allowed to reference T1 or T2 or even itself.

There should be no need for clients to implement this interface.

Author:
Beat Hörmann

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Table.TableIterator
    Defines an iterator over the rows of a given table.
    static interface 
    Table.ValueChanger<T>
    Provides a new value that depends on the stored value.
    static interface 
    Table.ValueSupplier<T>
    Provides a new value that does not depend on the stored value.
    static interface 
    Table.ValueSwitcher<T>
    Provides a new value that depends on the untyped stored value.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    compactFL()
    Eliminates the unused memory blocks within the FL file space of this table and truncates the corresponding data file.
    void
    compactVL()
    Eliminates the unused memory blocks within the VL file space of this table and truncates the corresponding data file.
    void
    delete(Ref ref)
    Deletes the referenced row from this table.
    Row
    get(Ref ref, Column<?>... columns)
    Returns the referenced row of this table.
    Column<?>
    getColumn(String name)
    Returns the column with the specified name.
    Column<?>[]
    getColumns()
    Returns all columns of this table.
    Database
    getDatabase()
    Returns the database.
    boolean
    hasColumn(String name)
    Tests if this table has a column with the specified name.
    Information.TableInfo
    info()
    Returns the information object of this table.
    Ref
    insert(Object... values)
    Inserts the specified values into this table and returns the reference to the newly created row.
    Table.TableIterator
    iterator()
    Returns an iterator over the rows of this table, semantically identical to the iterator(Column<?>...) method invoked with no arguments.
    Table.TableIterator
    iterator(Column<?>... columns)
    Returns an iterator over the rows of this table.
    Table.TableIterator
    iterator(Ref ref, Column<?>... columns)
    Returns an iterator over the rows of this table starting with the first row that comes after the referenced row.
    String
    name()
    Returns the name of this table.
    long
    numberOfRows()
    Returns the number of rows in this table.
    long
    refCount(Ref ref)
    Returns the value of the reference counter of the referenced row.
    Stream<Row>
    rows(Column<?>... columns)
    Returns a Stream of this table's rows.
    String
    toString()
    As the name() method, returns the name of this table.
    void
    truncate()
    Deletes all rows of this table and truncates the corresponding data files.
    void
    update(Ref ref, ColVal<?>... colVals)
    Updates the values of the specified columns of the referenced row with the specified new values.
    void
    updateAll(ColVal<?>... colVals)
    For each row of this table updates the values stored in the specified columns with the specified new values.
    <T> void
    updateAllChangeValues(Column<T> column, Table.ValueChanger<T> valueChanger)
    For each row of this table updates the value stored in the specified column with a value obtained from the specified value changer.
    <T> void
    updateAllSupplyValues(Column<T> column, Table.ValueSupplier<T> valueSupplier)
    For each row of this table updates the value stored in the specified column with a value obtained from the specified value supplier.

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Method Details

    • name

      String name()
      Returns the name of this table.
      Returns:
      The name of this table, never null and never an empty string.

    • info

      Information.TableInfo info()
      Returns the information object of this table.
      Returns:
      The information object of this table, never null.

    • getDatabase

      Database getDatabase()
      Returns the database.
      Returns:
      The database, never null.

    • hasColumn

      boolean hasColumn(String name)
      Tests if this table has a column with the specified name.
      Parameters:
      name - The name.
      Returns:
      The boolean value true if and only if this table has a column with the specified name.

    • getColumn

      Column<?> getColumn(String name) throws IllegalArgumentException
      Returns the column with the specified name.
      Parameters:
      name - The name of the column as written in the table layout.
      Returns:
      The column with the specified name, never null.
      Throws:
      IllegalArgumentException - If this table has no column with the specified name.

    • getColumns

      Column<?>[] getColumns()
      Returns all columns of this table.
      Returns:
      An array of the columns of this table, never null and never empty. The columns appear in the same order in which they appear in the table definition.

    • numberOfRows

      long numberOfRows()
      Returns the number of rows in this table.

      In case of table data corruption this read-only operation may return a wrong result. If the database is a writable database then temporary table data corruption may be due to concurrent writes. Invoke this read-only operation inside a read zone or a unit to ensure that no concurrent writes are taken place in the database while this operation is being executed.

      Returns:
      The number of rows in this table.

    • insert

      Ref insert(Object... values) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, MaximumException, CryptoException, ShutdownException, ACDPException, UnitBrokenException, IOFailureException
      Inserts the specified values into this table and returns the reference to the newly created row.

      The argument must be non-null and must satisfy the following conditions:

      • The number of values is equal to the number of columns of the table.
      • If vi denotes the i-th value then vi is compatible with the type of the i-th column of this table.

      This method does not explicitly check this precondition. In any case, if this precondition is not satisfied then this method throws an exception, however, this may be an exception of a type not listed below.

      Parameters:
      values - The values to insert into the row.
      Returns:
      The reference to the inserted row.
      Throws:
      UnsupportedOperationException - If the database is read-only.
      NullPointerException - If values is null.
      IllegalArgumentException - If the number of values is not equal to the number of columns of this table. This exception also happens if for at least one value the length of the byte representation of the 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 for at least one value the value is a reference and the reference points to a row that does not exist within the referenced table or if the reference points to a row gap or if the value is an array of references and this condition is satisfied for at least one of the references contained in the array.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position or if the maximum value of the reference counter of a referenced row is exceeded or if the maximum number of rows for this table is exceeded.
      CryptoException - If encryption fails. This exception never happens if the WR database does not apply encryption.
      ShutdownException - If this insert operation is a Kamikaze write and the database is closed.
      ACDPException - If this insert operation is called within a read zone.
      UnitBrokenException - If recording before data fails or if the unit was broken before.
      IOFailureException - If an I/O error occurs.

    • update

      void update(Ref ref, ColVal<?>... colVals) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, IllegalReferenceException, MaximumException, CryptoException, ShutdownException, ACDPException, UnitBrokenException, IOFailureException
      Updates the values of the specified columns of the referenced row with the specified new values.

      The new values must be compatible with the type of their columns. This method does not explicitly check this precondition. In any case, if this precondition is not satisfied then this method throws an exception, however, this may be an exception of a type not listed below.

      Parameters:
      ref - The reference to the row to update.
      colVals - The array of column values.
      Throws:
      UnsupportedOperationException - If the database is read-only.
      NullPointerException - If one of the arguments is equal to null or if the array of column values contains an element equal to null.
      IllegalArgumentException - If the array of column values contains at least one column that is not a column of this table. This exception also happens if for at least one value the length of the byte representation of the value (or one of the elements if the value is an array value) exceeds the maximum length allowed by this type. Furthermore, this exception happens if for at least one value the value is a reference and the reference points to a row that does not exist within the referenced table or if the reference points to a row gap or if the value is an array of references and this condition is satisfied for at least one of the references contained in the array.
      IllegalReferenceException - If the specified reference points to a row that does not exist within this table or if the reference points to a row gap. Such a situation cannot occur if ref is a valid reference.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position or if the maximum value of the reference counter of a referenced row is exceeded.
      CryptoException - If encryption fails. This exception never happens if encryption is not applied.
      ShutdownException - If this update operation is a Kamikaze write and the database is closed.
      ACDPException - If this update operation is called within a read zone.
      UnitBrokenException - If recording before data fails or if the unit was broken before.
      IOFailureException - If an I/O error occurs.

    • updateAll

      void updateAll(ColVal<?>... colVals) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, MaximumException, CryptoException, ShutdownException, ACDPException, UnitBrokenException, IOFailureException
      For each row of this table updates the values stored in the specified columns with the specified new values.

      The new values must be compatible with the type of their columns. This method does not explicitly check this precondition. In any case, if this precondition is not satisfied then this method throws an exception, however, this may be an exception of a type not listed below.

      Within a column, all rows are updated with the same value. Use the updateAllSupplyValues(acdp.Column<T>, acdp.Table.ValueSupplier<T>) or the updateAllChangeValues(acdp.Column<T>, acdp.Table.ValueChanger<T>) methods to update each row with a different value.

      Parameters:
      colVals - The array of column values.
      Throws:
      UnsupportedOperationException - If the database is read-only.
      NullPointerException - If the array of column values is equal to null or contains an element equal to null.
      IllegalArgumentException - If the array of column values contains at least one column that is not a column of this table. This exception also happens if for at least one value the length of the byte representation of the value (or one of the elements if the value is an array value) exceeds the maximum length allowed by this type. Furthermore, this exception happens if for at least one value the value is a reference and the reference points to a row that does not exist within the referenced table or if the reference points to a row gap or if the value is an array of references and this condition is satisfied for at least one of the references contained in the array.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position or if the maximum value of the reference counter of a referenced row is exceeded.
      CryptoException - If encryption fails. This exception never happens if encryption is not applied.
      ShutdownException - If this update operation is a Kamikaze write and the database is closed.
      ACDPException - If this update operation is called within a read zone.
      UnitBrokenException - If recording before data fails or if the unit was broken before.
      IOFailureException - If an I/O error occurs.

    • updateAllSupplyValues

      <T> void updateAllSupplyValues(Column<T> column, Table.ValueSupplier<T> valueSupplier) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, ImplementationRestrictionException, MaximumException, CryptoException, ShutdownException, ACDPException, UnitBrokenException, IOFailureException
      For each row of this table updates the value stored in the specified column with a value obtained from the specified value supplier.

      If a value returned by the value supplier is not compatible with the type of the column then this method throws an exception, however, this may be an exception of a type not listed below.

      Depending on the concrete implementation of the value supplier, this method may throw an exception that is different from the listed exceptions.

      To update all rows of a column with the same value, the updateAll(acdp.ColVal<?>...) method can be used instead of this method.

      Type Parameters:
      T - The type of the column's values.
      Parameters:
      column - The column to be updated.
      valueSupplier - The value supplier.
      Throws:
      UnsupportedOperationException - If the database is read-only.
      NullPointerException - If one of the arguments is equal to null.
      IllegalArgumentException - If the column is not a column of the table. This exception also happens if for a value returned by the value supplier the length of the byte representation of the value (or one of the elements if the value is an array value) exceeds the maximum length allowed by this type. Furthermore, this exception happens if the value is a reference and the reference points to a row that does not exist within the referenced table or if the reference points to a row gap or if the value is an array of references and this condition is satisfied for at least one of the references contained in the array.
      ImplementationRestrictionException - If the number of row gaps is greater than Integer.MAX_VALUE.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position or if the maximum value of the reference counter of a referenced row is exceeded.
      CryptoException - If encryption fails. This exception never happens if encryption is not applied.
      ShutdownException - If this update operation is a Kamikaze write and the database is closed.
      ACDPException - If this update operation is called within a read zone.
      UnitBrokenException - If recording before data fails or if the unit was broken before.
      IOFailureException - If an I/O error occurs.

    • updateAllChangeValues

      <T> void updateAllChangeValues(Column<T> column, Table.ValueChanger<T> valueChanger) throws UnsupportedOperationException, NullPointerException, IllegalArgumentException, ImplementationRestrictionException, MaximumException, CryptoException, ShutdownException, ACDPException, UnitBrokenException, IOFailureException
      For each row of this table updates the value stored in the specified column with a value obtained from the specified value changer.

      If a value returned by the value changer is not compatible with the type of the column then this method throws an exception, however, this may be an exception of a type not listed below.

      Depending on the concrete implementation of the value changer, this method may throw an exception that is different from the listed exceptions.

      To update all rows of a column with the same value, the updateAll(acdp.ColVal<?>...) method can be used instead of this method.

      Type Parameters:
      T - The type of the column's values.
      Parameters:
      column - The column to be updated.
      valueChanger - The value changer.
      Throws:
      UnsupportedOperationException - If the database is read-only.
      NullPointerException - If one of the arguments is equal to null.
      IllegalArgumentException - If the column is not a column of the table. This exception also happens if for a value returned by the value changer the length of the byte representation of the value (or one of the elements if the value is an array value) exceeds the maximum length allowed by this type. Furthermore, this exception happens if the value is a reference and the reference points to a row that does not exist within the referenced table or if the reference points to a row gap or if the value is an array of references and this condition is satisfied for at least one of the references contained in the array.
      ImplementationRestrictionException - If the number of row gaps is greater than Integer.MAX_VALUE.
      MaximumException - If a new memory block in the VL file space must be allocated and its file position exceeds the maximum allowed position or if the maximum value of the reference counter of a referenced row is exceeded.
      CryptoException - If encryption or decryption fails. This exception never happens if encryption is not applied.
      ShutdownException - If this update operation is a Kamikaze write and the database is closed.
      ACDPException - If this update operation is called within a read zone.
      UnitBrokenException - If recording before data fails or if the unit was broken before.
      IOFailureException - If an I/O error occurs.

    • delete

      void delete(Ref ref) throws UnsupportedOperationException, NullPointerException, DeleteConstraintException, IllegalReferenceException, ShutdownException, ACDPException, UnitBrokenException, IOFailureException
      Deletes the referenced row from this table.

      Note that if the row is referenced by at least one foreign row than this method raises an exception. To test this precondition, invoke the refCount(acdp.Ref) method and check if the returned value is greater than zero.

      Note also that deleting a non-existing row raises an exception. If there is any uncertainty about whether the row has already been deleted then this situation can be solved as follows: 

       try {
    delete(ref);
 } catch (IllegalReferenceException e) {
    if (!e.rowGap()) {
       throw e;
    }
 }
      In contrast to the isolated invocation of the delete method this code snippet has the effect that it does not raise an exception if the reference points to a row gap. (Consult the description of the Ref interface to learn about row gaps.)
      Parameters:
      ref - The reference to the row to delete from this table. The value must be a valid reference.
      Throws:
      UnsupportedOperationException - If the database is read-only.
      NullPointerException - If ref is null.
      DeleteConstraintException - If the row to delete is referenced by at least one foreign row.
      IllegalReferenceException - If the specified reference points to a row that does not exist within this table or if the reference points to a row gap. This exception never occurs if the reference is a valid reference.
      ShutdownException - If this delete operation is a Kamikaze write and the database is closed.
      ACDPException - If this delete operation is called within a read zone.
      UnitBrokenException - If recording before data fails or if the unit was broken before.
      IOFailureException - If an I/O error occurs.

    • truncate

      void truncate() throws UnsupportedOperationException, DeleteConstraintException, ACDPException, ShutdownException, IOFailureException
      Deletes all rows of this table and truncates the corresponding data files.

      Note that if this table contains at least one row which is referenced by a foreign row then this method throws a DeleteConstraintException. No changes are made to the database in such a situation.

      Note also that the database must be a writable database.

      Since the effects of this method on this table and on any other tables referenced by this table cannot be undone, you may want to backup the database before executing this method.

      The implementation of this method is such that any access to table data is blocked while this method is running. It is therefore safe to invoke this service operation anytime during a session. (Service operations are described in section "Service Operations" of the Database interface description.)

      Throws:
      UnsupportedOperationException - If this table has an RO store. This can only be the case if the database is an RO database.
      DeleteConstraintException - If this table contains at least one row which is referenced by a foreign row. This exception never happens if none of the tables in the database reference this table.
      ACDPException - If the WR database is read-only or if this method is invoked within a read zone.
      ShutdownException - If the database is closed.
      IOFailureException - If an I/O error occurs.

    • get

      Row get(Ref ref, Column<?>... columns) throws NullPointerException, IllegalArgumentException, IllegalReferenceException, CryptoException, ShutdownException, IOFailureException
      Returns the referenced row of this table.

      In case of table data corruption this read-only operation may throw an exception of a type not listed below. If the database is a writable database then temporary table data corruption may be due to concurrent writes. Invoke this read-only operation inside a read zone or a unit to ensure that no concurrent writes are taken place in the database while this operation is being executed.

      Parameters:
      ref - The reference to the row, not allowed to be null. The value must be a valid reference.
      columns - The array of columns, not allowed to be null. The columns must be columns of this table. If the array of columns is empty then this method behaves as if the array of columns is identical to the value returned by the getColumns() method.
      Returns:
      The row, never null.
      Throws:
      NullPointerException - If one of the arguments is equal to null.
      IllegalArgumentException - If at least one column in the specified array of columns is not a column of this table.
      IllegalReferenceException - If the specified reference points to a row that does not exist within this table or if the reference points to a row gap. This exception never occurs if the reference is a valid reference.
      CryptoException - If decryption fails. This exception never happens if the database does not apply encryption or if the database is an RO database.
      ShutdownException - If the database is closed. This exception never happens if this get operation is executed within a read zone or a unit or if the database is an RO database and the operating mode is "memory packed" (-2) or "memory unpacked" (-3).
      IOFailureException - If an I/O error occurs. This exception never happens if the database is an RO database and the operating mode is "memory unpacked" (-3).

    • iterator

      Table.TableIterator iterator(Column<?>... columns) throws NullPointerException, IllegalArgumentException
      Returns an iterator over the rows of this table.

      In case of table data corruption this method may throw an exception of a type not listed below. If the database is a writable database then temporary table data corruption may be due to concurrent writes. Execute this method and the whole iteration inside a read zone or a unit to ensure that no concurrent writes take place in the database while the iteration is being executed.

      Executing the insert(java.lang.Object...), the delete(acdp.Ref) and the update(acdp.Ref, acdp.ColVal<?>...) operations within the same thread can be done without damaging the internal state of the iterator, although the effects of such write operations may not be seen as the iteration continous due to caching effects. (Recall that a write operation cannot be executed within a read zone.)

      Consider using one of the updateAll perations if you want to update each row of this table in a single step. Furthermore, if you want to delete all rows of a table in a single step, consider using the truncate() operation.

      Parameters:
      columns - The array of columns, not allowed to be null. The columns must be columns of this table. If the array of columns is empty then the iterator behaves as if the array of columns is identical to the value returned by the getColumns() method.
      Returns:
      The iterator, never null.
      Throws:
      NullPointerException - If the array of columns is equal to null.
      IllegalArgumentException - If at least one column in the specified array of columns is not a column of this table.

    • iterator

      Table.TableIterator iterator(Ref ref, Column<?>... columns) throws NullPointerException, IllegalArgumentException, IllegalReferenceException
      Returns an iterator over the rows of this table starting with the first row that comes after the referenced row.

      If the reference is equal to null then the first row returned by the iterator will be equal to the first row of this table, provided that this table is not empty. Otherwise, the first row returned by the iterator will be equal to the row that immediately follows the referenced row, provided that the reference does not point to the last row of this table. (If the reference is null and this table is empty or if the reference points to the last row of this table then invoking the iterator's hasNext method returns false.)

      This method can be used to split an iteration from one large iteration into several smaller ones.

      The remarks in the iterator(Column<T>...) method description also apply for this iterator method.

      Parameters:
      ref - The row reference, may be null. The value must be a valid reference.
      columns - The array of columns, not allowed to be null. The columns must be columns of this table. If the array of columns is empty then the iterator behaves as if the array of columns is identical to the value returned by the getColumns() method.
      Returns:
      The iterator, never null.
      Throws:
      NullPointerException - If one of the arguments is equal to null.
      IllegalArgumentException - If at least one column in the specified array of columns is not a column of this table.
      IllegalReferenceException - If the specified reference points to a row that does not exist within this table. (The reference does not point to a row gap.) Such a situation cannot occur if ref is a valid reference.

    • iterator

      Table.TableIterator iterator()
      Returns an iterator over the rows of this table, semantically identical to the iterator(Column<?>...) method invoked with no arguments.

      The sequence of columns of the rows returned by this iterator is identical to the table definition.

      The remarks in the iterator(Column<T>...) method description also apply for this iterator method.

      Specified by:
      iterator in interface Iterable<Row>
      Returns:
      The iterator, never null.

    • rows

      Stream<Row> rows(Column<?>... columns) throws NullPointerException, IllegalArgumentException
      Returns a Stream of this table's rows.

      The returned stream is a sequential, ordered stream which may be turned into a parallel, unordered stream by invoking the stream's parallel() and/or unordered() methods, as explained in the description of the Stream class. Furthermore, the stream's underlying Spliterator is late-binding.

      For a writable database that is operated in an environment that allows concurrent writes, at least the terminal operation of the stream pipeline must be executed inside a read zone or a unit.

      Parameters:
      columns - The array of columns, not allowed to be null. The columns must be columns of this table. If the array of columns is empty then the stream behaves as if the array of columns is identical to the value returned by the getColumns() method.
      Returns:
      The stream of this table's rows, never null. All elements of the stream are non-null.
      Throws:
      NullPointerException - If the array of columns is equal to null.
      IllegalArgumentException - If at least one column in the specified array of columns is not a column of this table.

    • refCount

      long refCount(Ref ref) throws UnsupportedOperationException, NullPointerException, IllegalReferenceException, ShutdownException, IOFailureException
      Returns the value of the reference counter of the referenced row.

      Use this method to find out if the delete(acdp.Ref) method can be run without raising a DeleteConstraintException.

      Note that the database must be a WR database.

      In case of table data corruption this read-only operation may throw an exception of a type not listed below. If the database is a writable database then temporary table data corruption may be due to concurrent writes. Invoke this read-only operation inside a read zone or a unit to ensure that no concurrent writes are taken place in the database while this operation is being executed.

      Parameters:
      ref - The reference to the row, not allowed to be null. The value must be a valid reference.
      Returns:
      The value of the reference counter or -1 if the row has no reference counter because the table is unreferenced.
      Throws:
      UnsupportedOperationException - If this table has an RO store. This can only be the case if the database is an RO database.
      NullPointerException - If ref is equal to null.
      IllegalReferenceException - If the specified reference points to a row that does not exist within this table or if the reference points to a row gap. This exception never occurs if the reference is a valid reference.
      ShutdownException - If the database is closed. This exception never happens if this read-only operation is executed within a read zone or a unit.
      IOFailureException - If an I/O error occurs.

    • compactVL

      void compactVL() throws UnsupportedOperationException, ACDPException, ShutdownException, IOFailureException
      Eliminates the unused memory blocks within the VL file space of this table and truncates the corresponding data file.

      Note that the database must be a writable database. Note also that this method has no effect if this table's WR store has no VL file space.

      Since the effects of this method cannot be undone, you may want to backup the database before executing this method.

      The implementation of this method is such that any access to table data is blocked while this method is running. It is therefore safe to invoke this service operation anytime during a session. (Service operations are described in section "Service Operations" of the Database interface description.)

      Throws:
      UnsupportedOperationException - If this table has an RO store. This can only be the case if the database is an RO database.
      ACDPException - If the WR database is read-only or if this method is invoked within a read zone.
      ShutdownException - If the database is closed.
      IOFailureException - If an I/O error occurs.

    • compactFL

      void compactFL() throws UnsupportedOperationException, ImplementationRestrictionException, ACDPException, ShutdownException, IOFailureException
      Eliminates the unused memory blocks within the FL file space of this table and truncates the corresponding data file.

      Note that the database must be a writable WR database.

      Since the effects of this method on this table and on any other tables referencing this table cannot be undone, you may want to backup the database before executing this method.

      The implementation of this method is such that any access to table data is blocked while this method is running. It is therefore safe to invoke this service operation anytime during a session. (Service operations are described in section "Service Operations" of the Database interface description.)

      As mentioned under "Compacting the WR Store" in the interface description compacting the FL file space is usually not necessary.

      Note that existing references may be invalidated by compacting the FL file space of a table.

      Throws:
      UnsupportedOperationException - If this table has an RO store. This can only be the case if the database is an RO database.
      ImplementationRestrictionException - If the number of unused memory blocks in this table or in at least one of the tables referencing that table is greater than Integer.MAX_VALUE.
      ACDPException - If the WR database is read-only or if this method is invoked within a read zone.
      ShutdownException - If the database is closed.
      IOFailureException - If an I/O error occurs.

    • toString

      String toString()
      As the name() method, returns the name of this table.
      Overrides:
      toString in class Object
      Returns:
      The name of this table, never null and never an empty string.