Table (Melati Home 0.7.8-RC3-SNAPSHOT API)

Method Summary
`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(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`	`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`	`canDeleteColumn()`
`Column`	`canReadColumn()`
`Column`	`canSelectColumn()`
`Column`	`canWriteColumn()`
`void`	`clearColumnInfoCaches()` Clear caches.
`String`	`cnfWhereClause(Enumeration<Persistent> persistents)`
`String`	`cnfWhereClause(Enumeration<Persistent> 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.
`String`	`defaultOrderByClause()` If the troidColumn has yet to be set then returns an empty string.
`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`	`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.
`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.
`String`	`getDsdName()` Public method used in DSD.wm.
`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.
`Persistent`	`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<Persistent>`	`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<Persistent>`	`selection()` All the objects in the table.
`Enumeration<Persistent>`	`selection(Persistent criteria)` Return a selection of rows given an exemplar.
`Enumeration<Persistent>`	`selection(Persistent criteria, String orderByClause)` Return a selection of rows given arguments specifying a query.
`Enumeration<Persistent>`	`selection(Persistent criteria, String orderByClause, boolean includeDeleted, boolean excludeUnselectable)` Return a selection of rows given arguments specifying a query.
`Enumeration<Persistent>`	`selection(String whereClause)` A `SELECT`ion of objects from the table meeting given criteria.
`Enumeration<Persistent>`	`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`	`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)` Unify the JDBC description of this table with the meta data held in the `TableInfo`
`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

getColumnsCount

int getColumnsCount()

Returns:: the number of columns in this table.

columnWithColumnInfoID

Column columnWithColumnInfoID(int columnInfoID)

Parameters:: columnInfoID -
Returns:: the Column with a TROID equal to columnInfoID

troidColumn

Column 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 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

Persistent 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<Persistent> 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<Persistent> 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<Persistent> 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<Persistent> 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<Persistent> 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<Persistent> 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 -
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 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.

See Also:: notifyColumnInfo(org.melati.poem.ColumnInfo), clearColumnInfoCaches()
To do something:: Add mechanism for searching for Nulls (that would be query constructs as per SQL parse tree, but efferent not afferent)

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<Persistent> persistents)

Returns:: an SQL fragment
See Also:: cnfWhereClause(java.util.Enumeration, boolean, boolean), whereClause(org.melati.poem.Persistent)

cnfWhereClause

String cnfWhereClause(Enumeration<Persistent> 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<Persistent> 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 -
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 canReadColumn()

Returns:: the canReadColumn or the canSelectColumn or null

canSelectColumn

Column canSelectColumn()

Returns:: the canSelectColumn or null

canWriteColumn

Column canWriteColumn()

Returns:: the canWriteColumn or null

canDeleteColumn

Column 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

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

getDsdName

String getDsdName()

Public method used in DSD.wm. Duplicated because defaultDisplayName() above is overwritten.

Returns:: the capitalised name

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

unifyWithDB

void unifyWithDB(ResultSet colDescs)
                 throws PoemException

Unify the JDBC description of this table with the meta data held in the TableInfo

Parameters:: colDescs - a JDBC ResultSet describing the columns
Throws:: PoemException

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.melati.poem Interface Table

getDatabase

init

postInitialise

createTableInfo

getName

quotedName

getDisplayName

getDescription

getCategory

getInfo

tableInfoID

getColumn

columns

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

referencesTo

getMostRecentTroid

troidFor

org.melati.poem
Interface Table