Table (POEM 0.8.0-SNAPSHOT API)

All Known Implementing Classes:

CapabilityTable, CapabilityTableBase, ColumnInfoTable, ColumnInfoTableBase, GroupCapabilityTable, GroupCapabilityTableBase, GroupMembershipTable, GroupMembershipTableBase, GroupTable, GroupTableBase, JdbcTable, PoemTable, SettingTable, SettingTableBase, TableCategoryTable, TableCategoryTableBase, TableInfoTable, TableInfoTableBase, UserTable, UserTableBase, ValueInfoTable, ValueInfoTableBase
```
public interface Table
```
A table.

Since:

14-Apr-2008

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Column<?>`	`addColumnAndCommit(ColumnInfo infoP)` Add a `Column` to the database and the `TableInfo` table.
`void`	`addListener(TableListener listener)` Add a `TableListener` to this Table.
`void`	`appendWhereClause(StringBuffer clause, Persistent persistent)` Append an SQL logical expression to the given buffer to match rows according to criteria represented by the given object.
`CachedCount`	`cachedCount()`
`CachedCount`	`cachedCount(Persistent criteria)`
`CachedCount`	`cachedCount(Persistent criteria, boolean includeDeleted, boolean excludeUnselectable)` A mechanism for caching a record count.
`CachedCount`	`cachedCount(String whereClause)` A mechanism for caching a record count.
`CachedCount`	`cachedCount(String whereClause, boolean includeDeleted)` A mechanism for caching a record count.
`CachedCount`	`cachedCount(String whereClause, boolean includeDeleted, boolean excludeUnselectable)` A mechanism for caching a record count.
`CachedExists`	`cachedExists(String whereClause)` A mechanism for caching an existance.
`CachedSelection<P>`	`cachedSelection(String whereClause, String orderByClause)` A mechanism for caching a selection of records.
`Field<?>`	`cachedSelectionField(String whereClause, String orderByClause, boolean nullable, Integer selectedTroid, String nameP)` Make up a `Field` object whose possible values are a selected subset of the records in the table.
`RestrictedReferencePoemType<?>`	`cachedSelectionType(String whereClause, String orderByClause, boolean nullable)` A mechanism for caching a record count.
`Column<Capability>`	`canDeleteColumn()`
`Column<Capability>`	`canReadColumn()`
`Column<Capability>`	`canSelectColumn()`
`Column<Capability>`	`canWriteColumn()`
`void`	`clearColumnInfoCaches()` Clear caches.
`String`	`cnfWhereClause(Enumeration<P> persistents)`
`String`	`cnfWhereClause(Enumeration<P> persistents, boolean includeDeleted, boolean excludeUnselectable)` Return a Conjunctive Normal Form (CNF) where clause.
`Enumeration<Column<?>>`	`columns()` All the table's columns.
`Column<?>`	`columnWithColumnInfoID(int columnInfoID)`
`int`	`count()`
`int`	`count(String whereClause)` It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
`int`	`count(String whereClause, boolean includeDeleted)` It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
`int`	`count(String whereClause, boolean includeDeleted, boolean excludeUnselectable)` It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
`String`	`countSQL(String whereClause)`
`String`	`countSQL(String fromClause, String whereClause, boolean includeDeleted, boolean excludeUnselectable)` Return an SQL statement to count rows put together from the arguments.
`Persistent`	`create(Initialiser initialiser)` Create a new object (record) in the table.
`void`	`create(Persistent p)` Write a new row containing the given object.
`void`	`createTableInfo()` Create the (possibly overridden) TableInfo if it has not yet been created.
`void`	`dbAddConstraints()` Constraints are not used in POEM, but you might want to use them if exporting the db or using schema visualisation tools.
`void`	`dbModifyStructure(String sql)` Use this for DDL statements, ie those which alter the structure of the db.
`Integer`	`defaultCacheLimit()`
`String`	`defaultCategory()`
`String`	`defaultDescription()`
`String`	`defaultDisplayName()`
`int`	`defaultDisplayOrder()`
`String`	`defaultOrderByClause()` If the troidColumn has yet to be set then returns an empty string.
`boolean`	`defaultRememberAllTroids()`
`void`	`defineColumn(Column<?> column)` Don't call this in your application code.
`void`	`delete_unsafe(String whereClause)` It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
`void`	`delete(Integer troid, PoemTransaction transaction)` The Transaction cannot be null, as this is trapped in #deleteLock(SessionToken).
`void`	`deleteColumnAndCommit(ColumnInfo columnInfo)`
`Column<Boolean>`	`deletedColumn()`
`Column<?>`	`displayColumn()` The table's primary display column, the Troid column if not set.
`Enumeration<Column<?>>`	`displayColumns(DisplayLevel level)` Return columns at a display level in display order.
`int`	`displayColumnsCount(DisplayLevel level)`
`void`	`dump()` Print information about the structure of the table to stdout.
`void`	`dump(PrintStream ps)` Print information to PrintStream.
`void`	`dumpCacheAnalysis()` Print some diagnostic information about the contents and consistency of POEM's cache for this table to stderr.
`boolean`	`exists(Persistent persistent)`
`boolean`	`exists(String whereClause)` It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
`int`	`extrasCount()` The number of `extra' (non-DSD-defined) columns in the table.
`Persistent`	`firstSelection(String whereClause)` Get an object satisfying the where clause.
`Cache.Info`	`getCacheInfo()`
`Capability`	`getCanCreate()` The capability required for creating records in the table.
`TableCategory`	`getCategory()` The category of this table.
`Column<?>`	`getColumn(String nameP)` The table's column with a given name.
`List<Column<?>>`	`getColumns()` A list of all the table's columns.
`int`	`getColumnsCount()`
`Database`	`getDatabase()` The database to which the table is attached.
`String`	`getDbmsTableType()`
`Capability`	`getDefaultCanDelete()` The capability required for deleting records in the table, unless overridden in the record itself.
`Capability`	`getDefaultCanRead()` The capability required for reading records from the table, unless overridden in the record itself.
`Capability`	`getDefaultCanWrite()` The capability required for updating records in the table, unless overridden in the record itself.
`String`	`getDescription()` A brief description of the table's function.
`Enumeration<Column<?>>`	`getDetailDisplayColumns()` The table's columns for detailed display in display order.
`int`	`getDetailDisplayColumnsCount()`
`String`	`getDisplayName()` The human-readable name of the table.
`TableInfo`	`getInfo()`
`int`	`getMostRecentTroid()`
`String`	`getName()` The table's programmatic name.
`int`	`getNextExtrasIndex()`
`Persistent`	`getObject(int troid)` The object from the table with a given troid.
`P`	`getObject(Integer troid)` The object from the table with a given troid.
`Enumeration<Column<?>>`	`getRecordDisplayColumns()` The table's columns designated for display in a record, in display order.
`int`	`getRecordDisplayColumnsCount()`
`Enumeration<Column<?>>`	`getSearchCriterionColumns()` The table's columns designated for use as search criteria, in display order.
`int`	`getSearchCriterionColumnsCount()`
`Enumeration<Column<?>>`	`getSummaryDisplayColumns()` The table's columns designated for display in a record summary, in display order.
`int`	`getSummaryDisplayColumnsCount()`
`TableInfo`	`getTableInfo()`
`void`	`init()` Initialise the table.
`void`	`invalidateTransactionStuffs()` When deleting a table and used in tests.
`void`	`load(PoemTransaction transaction, Persistent persistent)`
`Persistent`	`newPersistent()`
`void`	`notifyColumnInfo(ColumnInfo infoP)` Clears columnInfo caches, normally a no-op.
`void`	`notifyTouched(PoemTransaction transaction, Persistent persistent)` Notify the table that one if its records is about to be changed in a transaction.
`void`	`postInitialise()` Do stuff immediately after table initialisation.
`Column<?>`	`primaryCriterionColumn()` In a similar manner to the primary display column, each table can have one primary criterion column.
`String`	`quotedName()`
`void`	`readLock()` Lock this record.
`Enumeration<P>`	`referencesTo(Persistent object)` All the objects in the table which refer to a given object.
`Enumeration<Column<?>>`	`referencesTo(Table<?> table)` All the columns in the table which refer to the given table.
`void`	`rememberAllTroids(boolean flag)`
`Enumeration<P>`	`selection()` All the objects in the table.
`Enumeration<P>`	`selection(Persistent criteria)` Return a selection of rows given an exemplar.
`Enumeration<P>`	`selection(Persistent criteria, String orderByClause)` Return a selection of rows given arguments specifying a query.
`Enumeration<P>`	`selection(Persistent criteria, String orderByClause, boolean includeDeleted, boolean excludeUnselectable)` Return a selection of rows given arguments specifying a query.
`Enumeration<P>`	`selection(String whereClause)` A `SELECT`ion of objects from the table meeting given criteria.
`Enumeration<P>`	`selection(String whereClause, String orderByClause, boolean includeDeleted)` A `SELECT`ion of objects from the table meeting given criteria, possibly including those flagged as deleted.
`String`	`selectionSQL(String fromClause, String whereClause, String orderByClause, boolean includeDeleted, boolean excludeUnselectable)` The from clause has been added as an argument because it is inextricably linked to the when clause, but the default is `quotedName()`.
`long`	`serial(PoemTransaction transaction)`
`void`	`setCacheLimit(Integer limit)`
`void`	`setDisplayColumn(Column<?> column)`
`void`	`setSearchColumn(Column<?> column)`
`void`	`setTableInfo(TableInfo tableInfo)`
`Integer`	`tableInfoID()` The troid (`id`) of the table's entry in the `tableinfo` table.
`String`	`toString()` A concise string to stand in for the table.
`void`	`trimCache(int maxSize)`
`Column<Integer>`	`troidColumn()` The table's troid column.
`Integer`	`troidFor(Persistent persistent)`
`Enumeration<Integer>`	`troidSelection(Persistent criteria, String orderByClause, boolean includeDeleted, boolean excludeUnselectable, PoemTransaction transaction)`
`Enumeration<Integer>`	`troidSelection(String whereClause, String orderByClause, boolean includeDeleted)` A `SELECT`ion of troids of objects from the table meeting given criteria.
`Enumeration<Integer>`	`troidSelection(String whereClause, String orderByClause, boolean includeDeleted, PoemTransaction transaction)` It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
`void`	`uncache()` Invalidate table cache.
`void`	`unifyWithColumnInfo()` Match columnInfo with this Table's columns.
`void`	`unifyWithDB(ResultSet colDescs, String primaryKey)` Unify the JDBC description of this tables columns with the meta data held in the `TableInfo`
`void`	`unifyWithMetadata(ResultSet tableDescriptions)` Unify SQL REMARKS with table.description.
`String`	`whereClause(Persistent criteria)` Return an SQL WHERE clause to select rows that match the non-null fields of the given object.
`String`	`whereClause(Persistent criteria, boolean includeDeleted, boolean excludeUnselectable)` Return an SQL WHERE clause to select rows using the given object as a selection criteria and optionally deleted rows or those included rows the user is not capable of selecting.
`void`	`writeDown(PoemTransaction transaction, Persistent p)`

- Method Detail
 - getDatabase
```
Database getDatabase()
```
 The database to which the table is attached.
 
 Returns:
 
 the db
 - init
```
void init()
```
 Initialise the table.
 - postInitialise
```
void postInitialise()
```
 Do stuff immediately after table initialisation.
 This base method clears the column info caches and adds a listener to the column info table to maintain the caches.
 It may be overridden to perform other actions. For example to ensure required rows exist in tables that define numeric ID's for codes.
 
 See Also:
 
 notifyColumnInfo(ColumnInfo), clearColumnInfoCaches()
 - createTableInfo
```
void createTableInfo()
```
 Create the (possibly overridden) TableInfo if it has not yet been created.
 - getName
```
String getName()
```
 The table's programmatic name. Identical with its name in the DSD (if the table was defined there) and in its tableinfo entry. This will normally be the same as the name in the RDBMS itself, however that name may be translated to avoid DBMS specific name clashes.
 
 Returns:
 
 the table name, case as defined in the DSD
 
 See Also:
 
 Dbms.melatiName(String)
 - quotedName
```
String quotedName()
```
 Returns:
 
 table name quoted using the DBMS' specific quoting rules.
 - getDisplayName
```
String getDisplayName()
```
 The human-readable name of the table. POEM itself doesn't use this, but it's available to applications and Melati's generic admin system as a default label for the table and caption for its records.
 
 Returns:
 
 The human-readable name of the table
 - getDescription
```
String getDescription()
```
 A brief description of the table's function. POEM itself doesn't use this, but it's available to applications and Melati's generic admin system as a default label for the table and caption for its records.
 
 Returns:
 
 the brief description
 - getCategory
```
TableCategory getCategory()
```
 The category of this table. POEM itself doesn't use this, but it's available to applications and Melati's generic admin system as a default label for the table and caption for its records.
 
 Returns:
 
 the category
 - getInfo
```
TableInfo getInfo()
```
 Returns:
 
 the TableInfo for this table
 - tableInfoID
```
Integer tableInfoID()
```
 The troid (id) of the table's entry in the tableinfo table. It will always have one (except during initialisation, which the application programmer will never see).
 
 Returns:
 
 id in TableInfo metadata table
 - getColumn
```
Column<?> getColumn(String nameP)
 throws NoSuchColumnPoemException
```
 The table's column with a given name. If the table is defined in the DSD under the name foo, there will be an application-specialised Table subclass, called FooTable (and available as getFooTable from the application-specialised Database subclass) which has extra named methods for accessing the table's predefined Columns.
 
 Parameters:
 
 nameP - name of column to get
 
 Returns:
 
 column of that name
 
 Throws:
 
 NoSuchColumnPoemException - if there is no column with that name
 - columns
```
Enumeration<Column<?>> columns()
```
 All the table's columns.
 
 Returns:
 
 an Enumeration of Columns
 
 See Also:
 
 Column
 - getColumns
```
List<Column<?>> getColumns()
```
 A list of all the table's columns.
 - getColumnsCount
```
int getColumnsCount()
```
 Returns:
 
 the number of columns in this table.
 - columnWithColumnInfoID
```
Column<?> columnWithColumnInfoID(int columnInfoID)
```
 Parameters:
 
 columnInfoID - the Id for the Column table
 
 Returns:
 
 the Column with a TROID equal to columnInfoID
 - troidColumn
```
Column<Integer> troidColumn()
```
 The table's troid column. Every table in a POEM database must have a troid (table row ID, or table-unique non-nullable integer primary key), often but not necessarily called id, so that it can be conveniently `named'.
 
 Returns:
 
 the id column
 
 See Also:
 
 getObject(Integer)
 - deletedColumn
```
Column<Boolean> deletedColumn()
```
 Returns:
 
 The table's deleted-flag column, if any.
 - displayColumn
```
Column<?> displayColumn()
```
 The table's primary display column, the Troid column if not set. This is the column used to represent records from the table concisely in reports or whatever. It is determined at initialisation time by examining the Columns getPrimaryDisplay() flags.
 
 Returns:
 
 the table's display column, or null if it hasn't got one see Column#setColumnInfo
 
 See Also:
 
 ReferencePoemType._stringOfCooked(java.lang.Object, org.melati.poem.PoemLocale, int), DisplayLevel.primary
 - setDisplayColumn
```
void setDisplayColumn(Column<?> column)
```
 Parameters:
 
 column - the display column to set
 - primaryCriterionColumn
```
Column<?> primaryCriterionColumn()
```
 In a similar manner to the primary display column, each table can have one primary criterion column.
 The Primary Criterion is the main grouping field of the table, ie the most important non-unique type field.
 For example the Primary Criterion for a User table might be Nationality.
 
 Returns:
 
 the search column, if any
 
 See Also:
 
 Searchability
 - setSearchColumn
```
void setSearchColumn(Column<?> column)
```
 Parameters:
 
 column - the search column to set
 - defaultOrderByClause
```
String defaultOrderByClause()
```
 If the troidColumn has yet to be set then returns an empty string.
 
 Returns:
 
 comma separated list of the columns to order by
 - clearColumnInfoCaches
```
void clearColumnInfoCaches()
```
 Clear caches.
 - notifyColumnInfo
```
void notifyColumnInfo(ColumnInfo infoP)
```
 Clears columnInfo caches, normally a no-op.
 
 Parameters:
 
 infoP - the possibly null ColumnInfo meta-data persistent
 - displayColumns
```
Enumeration<Column<?>> displayColumns(DisplayLevel level)
```
 Return columns at a display level in display order.
 
 Parameters:
 
 level - the DisplayLevel to select
 
 Returns:
 
 an Enumeration of columns at the given level
 - displayColumnsCount
```
int displayColumnsCount(DisplayLevel level)
```
 Parameters:
 
 level - the DisplayLevel to select
 
 Returns:
 
 the number of columns at a display level.
 - getDetailDisplayColumns
```
Enumeration<Column<?>> getDetailDisplayColumns()
```
 The table's columns for detailed display in display order.
 
 Returns:
 
 an Enumeration of Columns
 
 See Also:
 
 Column, displayColumns(org.melati.poem.DisplayLevel), DisplayLevel.detail
 - getDetailDisplayColumnsCount
```
int getDetailDisplayColumnsCount()
```
 Returns:
 
 the number of columns at display level Detail
 - getRecordDisplayColumns
```
Enumeration<Column<?>> getRecordDisplayColumns()
```
 The table's columns designated for display in a record, in display order.
 
 Returns:
 
 an Enumeration of Columns
 
 See Also:
 
 Column, displayColumns(org.melati.poem.DisplayLevel), DisplayLevel.record
 - getRecordDisplayColumnsCount
```
int getRecordDisplayColumnsCount()
```
 Returns:
 
 the number of columns at display level Record
 - getSummaryDisplayColumns
```
Enumeration<Column<?>> getSummaryDisplayColumns()
```
 The table's columns designated for display in a record summary, in display order.
 
 Returns:
 
 an Enumeration of Columns
 
 See Also:
 
 Column, displayColumns(org.melati.poem.DisplayLevel), DisplayLevel.summary
 - getSummaryDisplayColumnsCount
```
int getSummaryDisplayColumnsCount()
```
 Returns:
 
 the number of columns at display level Summary
 - getSearchCriterionColumns
```
Enumeration<Column<?>> getSearchCriterionColumns()
```
 The table's columns designated for use as search criteria, in display order.
 
 Returns:
 
 an Enumeration of Columns
 
 See Also:
 
 Column
 - getSearchCriterionColumnsCount
```
int getSearchCriterionColumnsCount()
```
 Returns:
 
 the number of columns which are searchable
 - dbModifyStructure
```
void dbModifyStructure(String sql)
 throws StructuralModificationFailedPoemException
```
 Use this for DDL statements, ie those which alter the structure of the db. Postgresql in particular does not like DDL statements being executed within a transaction.
 
 Parameters:
 
 sql - the SQL DDL statement to execute
 
 Throws:
 
 StructuralModificationFailedPoemException
 - dbAddConstraints
```
void dbAddConstraints()
```
 Constraints are not used in POEM, but you might want to use them if exporting the db or using schema visualisation tools.
 - invalidateTransactionStuffs
```
void invalidateTransactionStuffs()
```
 When deleting a table and used in tests.
 - load
```
void load(PoemTransaction transaction,
 Persistent persistent)
```
 Parameters:
 
 transaction - possibly null if working with the committed transaction
 
 persistent - the Persistent to load
 - delete
```
void delete(Integer troid,
 PoemTransaction transaction)
```
 The Transaction cannot be null, as this is trapped in #deleteLock(SessionToken).
 
 Parameters:
 
 troid - id of row to delete
 
 transaction - a non-null transaction
 - writeDown
```
void writeDown(PoemTransaction transaction,
 Persistent p)
```
 Parameters:
 
 transaction - our PoemTransaction
 
 p - the Persistent to write
 - uncache
```
void uncache()
```
 Invalidate table cache. NOTE Invalidated cache elements are reloaded when next read
 - trimCache
```
void trimCache(int maxSize)
```
 Parameters:
 
 maxSize - new maximum size
 - getCacheInfo
```
Cache.Info getCacheInfo()
```
 Returns:
 
 the Cache Info object
 - addListener
```
void addListener(TableListener listener)
```
 Add a TableListener to this Table.
 - notifyTouched
```
void notifyTouched(PoemTransaction transaction,
 Persistent persistent)
```
 Notify the table that one if its records is about to be changed in a transaction. You can (with care) use this to support cacheing of frequently-used facts about the table's records.
 
 Parameters:
 
 transaction - the transaction in which the change will be made
 
 persistent - the record to be changed
 - serial
```
long serial(PoemTransaction transaction)
```
 Returns:
 
 the Transaction serial
 - readLock
```
void readLock()
```
 Lock this record.
 - getObject
```
P getObject(Integer troid)
 throws NoSuchRowPoemException
```
 The object from the table with a given troid.
 
 Parameters:
 
 troid - Every record (object) in a POEM database must have a troid (table row ID, or table-unique non-nullable integer primary key), often but not necessarily called id, so that it can be conveniently `named' for retrieval by this method.
 
 Returns:
 
 A Persistent of the record with the given troid; or, if the table was defined in the DSD under the name foo, an application-specialised subclass Foo of Persistent. In that case, there will also be an application-specialised Table subclass, called FooTable (and available as getFooTable from the application-specialised Database subclass), which has a matching method getFooObject for obtaining the specialised object under its own type. Note that no access checks are done at this stage: you may not be able to do anything with the object handle returned from this method without provoking a PoemAccessException.
 
 Throws:
 
 NoSuchRowPoemException - if there is no row in the table with the given troid
 
 See Also:
 
 Persistable.getTroid()
 - getObject
```
Persistent getObject(int troid)
 throws NoSuchRowPoemException
```
 The object from the table with a given troid. See previous.
 
 Parameters:
 
 troid - the table row id
 
 Returns:
 
 the Persistent
 
 Throws:
 
 NoSuchRowPoemException - if not found
 
 See Also:
 
 getObject(Integer)
 - selectionSQL
```
String selectionSQL(String fromClause,
 String whereClause,
 String orderByClause,
 boolean includeDeleted,
 boolean excludeUnselectable)
```
 The from clause has been added as an argument because it is inextricably linked to the when clause, but the default is quotedName(). It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 fromClause - Comma separated list of table names or null for default.
 
 whereClause - SQL fragment
 
 orderByClause - Comma separated list
 
 includeDeleted - Flag as to whether to include soft deleted records
 
 excludeUnselectable - Whether to append unselectable exclusion SQL TODO Should work within some kind of limit
 
 Returns:
 
 an SQL SELECT statement put together from the arguments and default order by clause.
 - troidSelection
```
Enumeration<Integer> troidSelection(String whereClause,
 String orderByClause,
 boolean includeDeleted,
 PoemTransaction transaction)
```
 It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Returns:
 
 an Enumeration of Troids satisfying the criteria.
 - troidSelection
```
Enumeration<Integer> troidSelection(Persistent criteria,
 String orderByClause,
 boolean includeDeleted,
 boolean excludeUnselectable,
 PoemTransaction transaction)
```
 Parameters:
 
 criteria - Represents selection criteria possibly on joined tables
 
 transaction - A transaction or null for PoemThread.transaction()
 
 Returns:
 
 a selection of troids given arguments specifying a query
 
 See Also:
 
 troidSelection(String, String, boolean, org.melati.poem.PoemTransaction)
 - rememberAllTroids
```
void rememberAllTroids(boolean flag)
```
 Parameters:
 
 flag - whether to remember or forget
 - setCacheLimit
```
void setCacheLimit(Integer limit)
```
 Parameters:
 
 limit - the limit to set
 - troidSelection
```
Enumeration<Integer> troidSelection(String whereClause,
 String orderByClause,
 boolean includeDeleted)
 throws SQLPoemException
```
 A SELECTion of troids of objects from the table meeting given criteria. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS. If the orderByClause is null, then the default order by clause is applied. If the orderByClause is an empty string, ie "", then no ordering is applied.
 
 Parameters:
 
 whereClause - an SQL snippet
 
 orderByClause - an SQL snippet
 
 includeDeleted - whether to include deleted records, if any
 
 Returns:
 
 an Enumeration of Integers, which can be mapped onto Persistent objects using getObject; or you can just use selection
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 getObject(Integer), selection(String, String, boolean)
 - selection
```
Enumeration selection()
 throws SQLPoemException
```
 All the objects in the table.
 
 Returns:
 
 An Enumeration of Persistents, or, if the table was defined in the DSD under the name foo, of application-specialised subclasses Foo. Note that no access checks are done at this stage: you may not be able to do anything with some of the object handles in the enumeration without provoking a PoemAccessException. If the table has a deleted column, the objects flagged as deleted will be passed over.
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 Selectable.selection()
 - selection
```
Enumeration selection(String whereClause)
 throws SQLPoemException
```
 A SELECTion of objects from the table meeting given criteria. This is one way to run a search against the database and return the results as a series of typed POEM objects. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - SQL SELECTion criteria for the search: the part that should appear after the WHERE keyword
 
 Returns:
 
 An Enumeration of Persistents, or, if the table was defined in the DSD under the name foo, of application-specialised subclasses Foo. Note that no access checks are done at this stage: you may not be able to do anything with some of the object handles in the enumeration without provoking a PoemAccessException. If the table has a deleted column, the objects flagged as deleted will be passed over.
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 Column.selectionWhereEq(Object)
 - firstSelection
```
Persistent firstSelection(String whereClause)
```
 Get an object satisfying the where clause. It is the programmer's responsibility to use this in a context where only one result will be found, if more than one actually exist only the first will be returned. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - SQL SELECTion criteria for the search: the part that should appear after the WHERE keyword
 
 Returns:
 
 the first item satisfying criteria
 - selection
```
Enumeration selection(String whereClause,
 String orderByClause,
 boolean includeDeleted)
 throws SQLPoemException
```
 A SELECTion of objects from the table meeting given criteria, possibly including those flagged as deleted. If the orderByClause is null, then the default order by clause is applied. If the orderByClause is an empty string, ie "", then no ordering is applied. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 includeDeleted - whether to return objects flagged as deleted (ignored if the table doesn't have a deleted column)
 
 Returns:
 
 a ResultSet as an Enumeration
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 selection(String)
 - selection
```
Enumeration selection(Persistent criteria)
 throws SQLPoemException
```
 Return a selection of rows given an exemplar.
 
 Parameters:
 
 criteria - Represents selection criteria possibly on joined tables
 
 Returns:
 
 an enumeration of like objects
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 selection(String, String, boolean)
 - selection
```
Enumeration selection(Persistent criteria,
 String orderByClause)
 throws SQLPoemException
```
 Return a selection of rows given arguments specifying a query.
 
 Parameters:
 
 criteria - Represents selection criteria possibly on joined tables
 
 orderByClause - Comma separated list
 
 Returns:
 
 an enumeration of like objects with the specified ordering
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 selection(String, String, boolean)
 - selection
```
Enumeration selection(Persistent criteria,
 String orderByClause,
 boolean includeDeleted,
 boolean excludeUnselectable)
 throws SQLPoemException
```
 Return a selection of rows given arguments specifying a query.
 
 Parameters:
 
 criteria - Represents selection criteria possibly on joined tables
 
 orderByClause - Comma separated list
 
 excludeUnselectable - Whether to append unselectable exclusion SQL
 
 Returns:
 
 an enumeration of like Persistents
 
 Throws:
 
 SQLPoemException
 
 See Also:
 
 selection(String, String, boolean)
 - countSQL
```
String countSQL(String whereClause)
```
 Parameters:
 
 whereClause - the SQL fragment to count the results of
 
 Returns:
 
 the SQL string for the current SQL dialect
 - countSQL
```
String countSQL(String fromClause,
 String whereClause,
 boolean includeDeleted,
 boolean excludeUnselectable)
```
 Return an SQL statement to count rows put together from the arguments. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 fromClause - Comma separated list of table names
 
 Returns:
 
 the SQL query
 - count
```
int count(String whereClause,
 boolean includeDeleted,
 boolean excludeUnselectable)
 throws SQLPoemException
```
 It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Returns:
 
 the number records satisfying criteria.
 
 Throws:
 
 SQLPoemException
 - count
```
int count(String whereClause,
 boolean includeDeleted)
 throws SQLPoemException
```
 It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Returns:
 
 the number records satisfying criteria.
 
 Throws:
 
 SQLPoemException
 - count
```
int count(String whereClause)
 throws SQLPoemException
```
 It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Returns:
 
 the number of records satisfying criteria.
 
 Throws:
 
 SQLPoemException
 - count
```
int count()
 throws SQLPoemException
```
 Returns:
 
 the number of records in this table.
 
 Throws:
 
 SQLPoemException
 - exists
```
boolean exists(String whereClause)
 throws SQLPoemException
```
 It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - the SQL criteria
 
 Returns:
 
 whether any records satisfy criteria.
 
 Throws:
 
 SQLPoemException
 - exists
```
boolean exists(Persistent persistent)
```
 Parameters:
 
 persistent - a Persistent with some fields filled in
 
 Returns:
 
 whether any records exist with the same fields filled
 - appendWhereClause
```
void appendWhereClause(StringBuffer clause,
 Persistent persistent)
```
 Append an SQL logical expression to the given buffer to match rows according to criteria represented by the given object.
 This default selects rows for which the non-null fields in the given object match, but subtypes may add other criteria.
 The column names are now qualified with the table name so that subtypes can append elements of a join but there is no filtering by canselect columns. TODO Add mechanism for searching for Nulls (that would be query constructs as per SQL parse tree, but efferent not afferent)
 
 See Also:
 
 notifyColumnInfo(org.melati.poem.ColumnInfo), clearColumnInfoCaches()
 - whereClause
```
String whereClause(Persistent criteria)
```
 Return an SQL WHERE clause to select rows that match the non-null fields of the given object.
 This does not filter out any rows with a capability the user does not have in a canselect column, nor did it ever filter out rows deleted according to a "deleted" column. But the caller usually gets a second chance to do both.
 
 Returns:
 
 an SQL fragment
 - whereClause
```
String whereClause(Persistent criteria,
 boolean includeDeleted,
 boolean excludeUnselectable)
```
 Return an SQL WHERE clause to select rows using the given object as a selection criteria and optionally deleted rows or those included rows the user is not capable of selecting.
 This is currently implemented in terms of appendWhereClause(StringBuffer, org.melati.poem.Persistent).
 
 Returns:
 
 an SQL fragment
 - cnfWhereClause
```
String cnfWhereClause(Enumeration persistents)
```
 Returns:
 
 an SQL fragment
 
 See Also:
 
 cnfWhereClause(java.util.Enumeration, boolean, boolean), whereClause(org.melati.poem.Persistent)
 - cnfWhereClause
```
String cnfWhereClause(Enumeration persistents,
 boolean includeDeleted,
 boolean excludeUnselectable)
```
 Return a Conjunctive Normal Form (CNF) where clause. See http://en.wikipedia.org/wiki/Conjunctive_normal_form.
 
 Returns:
 
 an SQL fragment
 - referencesTo
```
Enumeration referencesTo(Persistent object)
```
 All the objects in the table which refer to a given object. If none of the table's columns are reference columns, the Enumeration returned will obviously be empty.
 It is not guaranteed to be quick to execute!
 
 Returns:
 
 an Enumeration of Persistents
 - referencesTo
```
Enumeration<Column<?>> referencesTo(Table<?> table)
```
 All the columns in the table which refer to the given table.
 
 Parameters:
 
 table - the table to count the references within
 
 Returns:
 
 an Enumeration of Columns referring to the specified Table
 - getMostRecentTroid
```
int getMostRecentTroid()
```
 Returns:
 
 the current highest troid
 - troidFor
```
Integer troidFor(Persistent persistent)
```
 Parameters:
 
 persistent - unused parameter, but might be needed in another troid schema
 
 Returns:
 
 the next Troid
 - create
```
void create(Persistent p)
 throws AccessPoemException,
 ValidationPoemException,
 InitialisationPoemException
```
 Write a new row containing the given object.
 The given object will be assigned the next troid and its internal state will also be modified.
 
 Throws:
 
 InitialisationPoemException - The object failed validation (currently one of its field values failed).
 
 AccessPoemException
 
 ValidationPoemException
 - create
```
Persistent create(Initialiser initialiser)
 throws AccessPoemException,
 ValidationPoemException,
 InitialisationPoemException
```
 Create a new object (record) in the table.
 
 Parameters:
 
 initialiser - A piece of code for setting the new object's initial values. You'll probably want to define it as an anonymous class.
 
 Returns:
 
 A Persistent representing the new object, or, if the table was defined in the DSD under the name foo, an application-specialised subclass Foo of Persistent.
 
 Throws:
 
 AccessPoemException - if initialiser provokes one during its work (which is unlikely, since POEM's standard checks are disabled while it runs)
 
 ValidationPoemException - if initialiser provokes one during its work
 
 InitialisationPoemException - if the object is left by initialiser in a state in which not all of its fields have legal values, or in which the calling thread would not be allowed write access to the object under its AccessToken---i.e. you can't create objects you wouldn't be allowed to write to.
 
 See Also:
 
 Initialiser.init(Persistent), PoemThread.accessToken(), getCanCreate()
 - newPersistent
```
Persistent newPersistent()
```
 Returns:
 
 A freshly minted floating Persistent object for this table, ie one without a troid set
 - delete_unsafe
```
void delete_unsafe(String whereClause)
```
 It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - the criteria
 - extrasCount
```
int extrasCount()
```
 The number of `extra' (non-DSD-defined) columns in the table.
 - getDefaultCanRead
```
Capability getDefaultCanRead()
```
 The capability required for reading records from the table, unless overridden in the record itself. This simply comes from the table's record in the tableinfo table.
 
 Returns:
 
 the capability needed to read this table
 - getDefaultCanWrite
```
Capability getDefaultCanWrite()
```
 The capability required for updating records in the table, unless overridden in the record itself. This simply comes from the table's record in the tableinfo table.
 
 Returns:
 
 the default Capability required to write a Persistent, if any
 - getDefaultCanDelete
```
Capability getDefaultCanDelete()
```
 The capability required for deleting records in the table, unless overridden in the record itself. This simply comes from the table's record in the tableinfo table.
 
 Returns:
 
 the default Capability required to delete a Persistent, if any
 - getCanCreate
```
Capability getCanCreate()
```
 The capability required for creating records in the table. This simply comes from the table's record in the tableinfo table.
 
 Returns:
 
 the Capability required to write to this table
 
 See Also:
 
 create(Initialiser)
 - canReadColumn
```
Column<Capability> canReadColumn()
```
 Returns:
 
 the canReadColumn or the canSelectColumn or null
 - canSelectColumn
```
Column<Capability> canSelectColumn()
```
 Returns:
 
 the canSelectColumn or null
 - canWriteColumn
```
Column<Capability> canWriteColumn()
```
 Returns:
 
 the canWriteColumn or null
 - canDeleteColumn
```
Column<Capability> canDeleteColumn()
```
 Returns:
 
 the canDeleteColumn or null
 - addColumnAndCommit
```
Column<?> addColumnAndCommit(ColumnInfo infoP)
 throws PoemException
```
 Add a Column to the database and the TableInfo table.
 
 Parameters:
 
 infoP - the meta data about the Column
 
 Returns:
 
 the newly added column
 
 Throws:
 
 PoemException
 - deleteColumnAndCommit
```
void deleteColumnAndCommit(ColumnInfo columnInfo)
 throws PoemException
```
 Parameters:
 
 columnInfo - metadata about the column to delete, which is itself deleted
 
 Throws:
 
 PoemException
 - toString
```
String toString()
```
 A concise string to stand in for the table. The table's name and a description of where it was defined (the DSD, the metadata tables or the JDBC metadata).
 
 Overrides:
 
 toString in class Object
 
 See Also:
 
 Object.toString()
 - dumpCacheAnalysis
```
void dumpCacheAnalysis()
```
 Print some diagnostic information about the contents and consistency of POEM's cache for this table to stderr.
 - dump
```
void dump()
```
 Print information about the structure of the table to stdout.
 - dump
```
void dump(PrintStream ps)
```
 Print information to PrintStream.
 
 Parameters:
 
 ps - PrintStream to dump to
 - cachedSelection
```
CachedSelection cachedSelection(String whereClause,
 String orderByClause)
```
 A mechanism for caching a selection of records. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - raw SQL selection clause appropriate for this DBMS
 
 orderByClause - which field to order by or null
 
 Returns:
 
 the results
 - cachedCount
```
CachedCount cachedCount(String whereClause,
 boolean includeDeleted)
```
 A mechanism for caching a record count. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - raw SQL selection clause appropriate for this DBMS
 
 includeDeleted - whether to include soft deleted records
 
 Returns:
 
 a cached count
 - cachedCount
```
CachedCount cachedCount(String whereClause,
 boolean includeDeleted,
 boolean excludeUnselectable)
```
 A mechanism for caching a record count. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - raw SQL selection clause appropriate for this DBMS
 
 includeDeleted - whether to include soft deleted records
 
 excludeUnselectable - whether to exclude columns which cannot be selected
 
 Returns:
 
 a cached count
 - cachedCount
```
CachedCount cachedCount(Persistent criteria,
 boolean includeDeleted,
 boolean excludeUnselectable)
```
 A mechanism for caching a record count.
 
 Parameters:
 
 criteria - a Persistent with selection fields filled
 
 includeDeleted - whether to include soft deleted records
 
 excludeUnselectable - whether to exclude columns which cannot be selected
 
 Returns:
 
 a cached count
 - cachedCount
```
CachedCount cachedCount(Persistent criteria)
```
 Parameters:
 
 criteria - a Persistent to extract where clause from
 
 Returns:
 
 a CachedCount of records matching Criteria
 - cachedCount
```
CachedCount cachedCount(String whereClause)
```
 A mechanism for caching a record count. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - raw SQL selection clause appropriate for this DBMS
 
 Returns:
 
 a cached count
 - cachedCount
```
CachedCount cachedCount()
```
 Returns:
 
 a cached count of all records in the table, obeying includedDeleted and other exclusions
 - cachedExists
```
CachedExists cachedExists(String whereClause)
```
 A mechanism for caching an existance. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS. NOTE It is possible for the count to be written simultaneously, but the cache will end up with the same result.
 
 Parameters:
 
 whereClause - raw SQL selection clause appropriate for this DBMS
 
 Returns:
 
 a cached exists
 - cachedSelectionType
```
RestrictedReferencePoemType<?> cachedSelectionType(String whereClause,
 String orderByClause,
 boolean nullable)
```
 A mechanism for caching a record count. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 
 Parameters:
 
 whereClause - raw SQL selection clause appropriate for this DBMS
 
 orderByClause - raw SQL order clause appropriate for this DBMS
 
 nullable - whether the ReferencePoemType is nullable
 
 Returns:
 
 a RestrictedReferencePoemType
 - cachedSelectionField
```
Field<?> cachedSelectionField(String whereClause,
 String orderByClause,
 boolean nullable,
 Integer selectedTroid,
 String nameP)
```
 Make up a Field object whose possible values are a selected subset of the records in the table. You can make a "dropdown" offering a choice of your green customers by putting this in your handler
 context.put("greens", melati.getDatabase().getCustomerTable().cachedSelectionField( "colour = 'green'", null, true, null, "greens"));
 and this in your template
 Select a customer: $ml.input($greens)
 The list of member records is implicitly cached---permanently, and however big it turns out to be. So don't go mad with this. It is recomputed on demand if the contents of the table are changed. The whereClause and orderByClause you pass in are checked to see if you have asked for the same list before, so however many times you call this method, you should only trigger actual SELECTs when the table contents have changed. The list is also transaction-safe, in that it will always reflect the state of affairs within your transaction even if you haven't done a commit. It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.
 Parameters:
 
 whereClause - an SQL expression (the bit after the SELECT ... WHERE) for picking out the records you want
 
 orderByClause - a comma-separated list of column names which determine the order in which the records are presented; if this is null, the displayorderpriority attributes of the table's columns determine the order
 
 nullable - whether to allow a blank NULL option as the first possibility
 
 selectedTroid - the troid of the record to which the SELECT field should initially be set
 
 nameP - the HTML name attribute of the field, i.e. <SELECT NAME=name>
 
 Returns:
 
 a Field object
 - defineColumn
```
void defineColumn(Column<?> column)
 throws DuplicateColumnNamePoemException,
 DuplicateTroidColumnPoemException,
 DuplicateDeletedColumnPoemException
```
 Don't call this in your application code. Columns should be defined either in the DSD (in which case the boilerplate code generated by the preprocessor will call this method) or directly in the RDBMS (in which case the initialisation code will).
 
 Throws:
 
 DuplicateColumnNamePoemException
 
 DuplicateTroidColumnPoemException
 
 DuplicateDeletedColumnPoemException
 - getNextExtrasIndex
```
int getNextExtrasIndex()
```
 Returns:
 
 incremented extra columns index
 - setTableInfo
```
void setTableInfo(TableInfo tableInfo)
```
 Parameters:
 
 tableInfo - the TableInfo to set
 - getTableInfo
```
TableInfo getTableInfo()
```
 Returns:
 
 the TableInfo for this table.
 - getDbmsTableType
```
String getDbmsTableType()
```
 Returns:
 
 a DBMS table type eg TEXT
 - unifyWithColumnInfo
```
void unifyWithColumnInfo()
 throws PoemException
```
 Match columnInfo with this Table's columns. Conversely, create a ColumnInfo for any columns which don't have one.
 
 Throws:
 
 PoemException
 - unifyWithMetadata
```
void unifyWithMetadata(ResultSet tableDescriptions)
 throws SQLException
```
 Unify SQL REMARKS with table.description.
 
 Parameters:
 
 tableDescriptions - a JDBC ResultSet with cursor at current row
 
 Throws:
 
 SQLException
 - unifyWithDB
```
void unifyWithDB(ResultSet colDescs,
 String primaryKey)
 throws PoemException
```
 Unify the JDBC description of this tables columns with the meta data held in the TableInfo
 
 Parameters:
 
 colDescs - a JDBC ResultSet describing the columns with cursor at current row
 
 primaryKey - name of primary key column
 
 Throws:
 
 PoemException
 - defaultDisplayName
```
String defaultDisplayName()
```
 - defaultDescription
```
String defaultDescription()
```
 - defaultDisplayOrder
```
int defaultDisplayOrder()
```
 - defaultCacheLimit
```
Integer defaultCacheLimit()
```
 - defaultRememberAllTroids
```
boolean defaultRememberAllTroids()
```
 - defaultCategory
```
String defaultCategory()
```

Interface Table<P extends Persistent>

Method Summary

Method Detail

getDatabase

init

postInitialise

createTableInfo

getName

quotedName

getDisplayName

getDescription

getCategory

getInfo

tableInfoID

getColumn

columns

getColumns

getColumnsCount

columnWithColumnInfoID

troidColumn

deletedColumn

displayColumn

setDisplayColumn

primaryCriterionColumn

setSearchColumn

defaultOrderByClause

clearColumnInfoCaches

notifyColumnInfo

displayColumns

displayColumnsCount

getDetailDisplayColumns

getDetailDisplayColumnsCount

getRecordDisplayColumns

getRecordDisplayColumnsCount

getSummaryDisplayColumns

getSummaryDisplayColumnsCount

getSearchCriterionColumns

getSearchCriterionColumnsCount

dbModifyStructure

dbAddConstraints

invalidateTransactionStuffs

load

delete

writeDown

uncache

trimCache

getCacheInfo

addListener

notifyTouched

serial

readLock

getObject

getObject

selectionSQL

troidSelection

troidSelection

rememberAllTroids

setCacheLimit

troidSelection

selection

selection

firstSelection

selection

selection

selection

selection

countSQL

countSQL

count

count

count

count

exists

exists

appendWhereClause

whereClause

whereClause

cnfWhereClause

cnfWhereClause

referencesTo