org.melati.poem
Class JdbcTable

java.lang.Object
  org.melati.poem.JdbcTable

All Implemented Interfaces:

Selectable, Table

Direct Known Subclasses:

ContactsTable, OdmgTable, PoemTable

public class JdbcTable
extends Object
implements Selectable, Table

A Table.

Since:

14 April 2008

Constructor Summary

JdbcTable(Database database, String name, DefinitionSource definitionSource)
Constructor.

Method Summary

protected Column	_getColumn(String nameP)
protected JdbcPersistent	_newPersistent() A freshly minted, and uninitialised, Persistent object for the table.
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 persistents)
String	cnfWhereClause(Enumeration 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.
protected Integer	defaultCacheLimit()
protected String	defaultCategory()
protected String	defaultDescription() The `factory-default' description for the table, or null if it doesn't have one.
protected String	defaultDisplayName() The `factory-default' display name for the table.
protected int	defaultDisplayOrder()
String	defaultOrderByClause() If the troidColumn has yet to be set then returns an empty string.
protected 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	deletedColumn()
Column	displayColumn() The table's primary display column, the Troid column if not set.
Enumeration	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	equals(Object t) Make sure that two equal table objects have the same name.
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() Enable reporting of the status of the cache.
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	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	getRecordDisplayColumns() The table's columns designated for display in a record, in display order.
int	getRecordDisplayColumnsCount()
Enumeration	getSearchCriterionColumns() The table's columns designated for use as search criteria, in display order.
int	getSearchCriterionColumnsCount()
Enumeration	getSummaryDisplayColumns() The table's columns designated for display in a record summary, in display order.
int	getSummaryDisplayColumnsCount()
TableInfo	getTableInfo()
int	hashCode() Ensure tables can be used as hashtable keys.
void	init() Override this to perform pre-unification initialisation.
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	referencesTo(Persistent object) All the objects in the table which refer to a given object.
Enumeration	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	selection(Persistent criteria) Return a selection of rows given an exemplar.
Enumeration	selection(Persistent criteria, String orderByClause) Return a selection of rows given arguments specifying a query.
Enumeration	selection(Persistent criteria, String orderByClause, boolean includeDeleted, boolean excludeUnselectable) Return a selection of rows given arguments specifying a query.
Enumeration	selection(String whereClause) A SELECTion of objects from the table meeting given criteria.
Enumeration<Persistent>	selection(String whereClause, String orderByClause, boolean includeDeleted) A SELECTion 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 where 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	troidSelection(Persistent criteria, String orderByClause, boolean includeDeleted, boolean excludeUnselectable, PoemTransaction transaction)
Enumeration<Integer>	troidSelection(String whereClause, String orderByClause, boolean includeDeleted) A SELECTion 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)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JdbcTable

public JdbcTable(Database database,
                 String name,
                 DefinitionSource definitionSource)

Constructor.

Method Detail

postInitialise

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

Specified by:

postInitialise in interface Table

See Also:

notifyColumnInfo(ColumnInfo), clearColumnInfoCaches()

getDatabase

public final Database getDatabase()

The database to which the table is attached.

Specified by:

getDatabase in interface Table

Returns:

the db

getName

public final 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.

Specified by:

getName in interface Table

Returns:

the table name, case as defined in the DSD

See Also:

Dbms.melatiName(String)

quotedName

public final String quotedName()

Specified by:

quotedName in interface Table

Returns:

table name quoted using the DBMS' specific quoting rules.

getDisplayName

public final 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.

Specified by:

getDisplayName in interface Table

Returns:

The human-readable name of the table

getDescription

public final 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.

Specified by:

getDescription in interface Table

Returns:

the brief description

getCategory

public final 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.

Specified by:

getCategory in interface Table

Returns:

the category

getInfo

public final TableInfo getInfo()

Specified by:

getInfo in interface Table

Returns:

the TableInfo for this table

tableInfoID

public final 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).

Specified by:

tableInfoID in interface Table

Returns:

id in TableInfo metadata table

getColumn

public final 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.

Specified by:

getColumn in interface Table

Parameters:

nameP - name of column to get

Returns:

column of that name

Throws:

NoSuchColumnPoemException - if there is no column with that name

_getColumn

protected final Column _getColumn(String nameP)

columns

public final Enumeration<Column> columns()

All the table's columns.

Specified by:

columns in interface Table

Returns:

an Enumeration of Columns

See Also:

Column

getColumnsCount

public final int getColumnsCount()

Specified by:

getColumnsCount in interface Table

Returns:

the number of columns in this table.

columnWithColumnInfoID

public Column columnWithColumnInfoID(int columnInfoID)

Specified by:

columnWithColumnInfoID in interface Table

Parameters:

columnInfoID -

Returns:

the Column with a TROID equal to columnInfoID

troidColumn

public final 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'.

Specified by:

troidColumn in interface Table

Returns:

the id column

See Also:

getObject(java.lang.Integer)

deletedColumn

public final Column deletedColumn()

Specified by:

deletedColumn in interface Table

Returns:

The table's deleted-flag column, if any.

displayColumn

public final 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.

Specified by:

displayColumn in interface Table

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

public final void setDisplayColumn(Column column)

Specified by:

setDisplayColumn in interface Table

Parameters:

column - the display column to set

primaryCriterionColumn

public final 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.

Specified by:

primaryCriterionColumn in interface Table

Returns:

the search column, if any

See Also:

Searchability

setSearchColumn

public void setSearchColumn(Column column)

Specified by:

setSearchColumn in interface Table

Parameters:

column - the search column to set

defaultOrderByClause

public String defaultOrderByClause()

If the troidColumn has yet to be set then returns an empty string.

Specified by:

defaultOrderByClause in interface Table

Returns:

comma separated list of the columns to order by

clearColumnInfoCaches

public void clearColumnInfoCaches()

Clear caches.

Specified by:

clearColumnInfoCaches in interface Table

notifyColumnInfo

public void notifyColumnInfo(ColumnInfo infoP)

Clears columnInfo caches, normally a no-op.

Specified by:

notifyColumnInfo in interface Table

Parameters:

infoP - the possibly null ColumnInfo meta-data persistent

displayColumns

public final Enumeration displayColumns(DisplayLevel level)

Return columns at a display level in display order.

Specified by:

displayColumns in interface Table

Parameters:

level - the DisplayLevel to select

Returns:

an Enumeration of columns at the given level

displayColumnsCount

public final int displayColumnsCount(DisplayLevel level)

Specified by:

displayColumnsCount in interface Table

Parameters:

level - the DisplayLevel to select

Returns:

the number of columns at a display level.

getDetailDisplayColumns

public final Enumeration getDetailDisplayColumns()

The table's columns for detailed display in display order.

Specified by:

getDetailDisplayColumns in interface Table

Returns:

an Enumeration of Columns

See Also:

Column, displayColumns(DisplayLevel), DisplayLevel.detail

getDetailDisplayColumnsCount

public final int getDetailDisplayColumnsCount()

Specified by:

getDetailDisplayColumnsCount in interface Table

Returns:

the number of columns at display level Detail

getRecordDisplayColumns

public final Enumeration getRecordDisplayColumns()

The table's columns designated for display in a record, in display order.

Specified by:

getRecordDisplayColumns in interface Table

Returns:

an Enumeration of Columns

See Also:

Column, displayColumns(DisplayLevel), DisplayLevel.record

getRecordDisplayColumnsCount

public final int getRecordDisplayColumnsCount()

Specified by:

getRecordDisplayColumnsCount in interface Table

Returns:

the number of columns at display level Record

getSummaryDisplayColumns

public final Enumeration getSummaryDisplayColumns()

The table's columns designated for display in a record summary, in display order.

Specified by:

getSummaryDisplayColumns in interface Table

Returns:

an Enumeration of Columns

See Also:

Column, displayColumns(DisplayLevel), DisplayLevel.summary

getSummaryDisplayColumnsCount

public final int getSummaryDisplayColumnsCount()

Specified by:

getSummaryDisplayColumnsCount in interface Table

Returns:

the number of columns at display level Summary

getSearchCriterionColumns

public final Enumeration getSearchCriterionColumns()

The table's columns designated for use as search criteria, in display order.

Specified by:

getSearchCriterionColumns in interface Table

Returns:

an Enumeration of Columns

See Also:

Column

getSearchCriterionColumnsCount

public final int getSearchCriterionColumnsCount()

Specified by:

getSearchCriterionColumnsCount in interface Table

Returns:

the number of columns which are searchable

dbModifyStructure

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

Specified by:

dbModifyStructure in interface Table

Parameters:

sql - the SQL DDL statement to execute

Throws:

StructuralModificationFailedPoemException

getDbmsTableType

public String getDbmsTableType()

Specified by:

getDbmsTableType in interface Table

Returns:

A type string eg "TEXT"

See Also:

org.melati.poem.dbms.Hsqldb}

dbAddConstraints

public void dbAddConstraints()

Constraints are not used in POEM, but you might want to use them if exporting the db or using schema visualisation tools.

Specified by:

dbAddConstraints in interface Table

invalidateTransactionStuffs

public void invalidateTransactionStuffs()

When deleting a table and used in tests.

Specified by:

invalidateTransactionStuffs in interface Table

load

public void load(PoemTransaction transaction,
                 Persistent persistent)

Specified by:

load in interface Table

Parameters:

transaction - possibly null if working with the committed transaction

persistent - the Persistent to load

delete

public void delete(Integer troid,
                   PoemTransaction transaction)

The Transaction cannot be null, as this is trapped in #deleteLock(SessionToken).

Specified by:

delete in interface Table

Parameters:

troid - id of row to delete

transaction - a non-null transaction

writeDown

public void writeDown(PoemTransaction transaction,
                      Persistent p)

Specified by:

writeDown in interface Table

Parameters:

transaction - our PoemTransaction

p - the Persistent to write

uncache

public void uncache()

Invalidate table cache. NOTE Invalidated cache elements are reloaded when next read

Specified by:

uncache in interface Table

trimCache

public void trimCache(int maxSize)

Specified by:

trimCache in interface Table

Parameters:

maxSize - new maximum size

getCacheInfo

public Cache.Info getCacheInfo()

Enable reporting of the status of the cache.

Specified by:

getCacheInfo in interface Table

Returns:

the Cache Info object

addListener

public void addListener(TableListener listener)

Add a TableListener to this Table.

Specified by:

addListener in interface Table

notifyTouched

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

Specified by:

notifyTouched in interface Table

Parameters:

transaction - the transaction in which the change will be made

persistent - the record to be changed

serial

public long serial(PoemTransaction transaction)

Specified by:

serial in interface Table

Returns:

the Transaction serial

readLock

public void readLock()

Lock this record.

Specified by:

readLock in interface Table

getObject

public Persistent getObject(Integer troid)
                     throws NoSuchRowPoemException

The object from the table with a given troid.

Specified by:

getObject in interface Selectable

Specified by:

getObject in interface Table

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

public Persistent getObject(int troid)
                     throws NoSuchRowPoemException

The object from the table with a given troid. See previous.

Specified by:

getObject in interface Table

Parameters:

troid - the table row id

Returns:

the Persistent

Throws:

NoSuchRowPoemException - if not found

See Also:

getObject(java.lang.Integer)

selectionSQL

public 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 where clause, but the default is quotedName(). It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.

Specified by:

selectionSQL in interface Table

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

Returns:

an SQL SELECT statement put together from the arguments and default order by clause.

To do something:

Should work within some kind of limit

troidSelection

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

Specified by:

troidSelection in interface Table

Returns:

an Enumeration of Troids satisfying the criteria.

troidSelection

public Enumeration troidSelection(Persistent criteria,
                                  String orderByClause,
                                  boolean includeDeleted,
                                  boolean excludeUnselectable,
                                  PoemTransaction transaction)

Specified by:

troidSelection in interface Table

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, PoemTransaction)

rememberAllTroids

public void rememberAllTroids(boolean flag)

Specified by:

rememberAllTroids in interface Table

Parameters:

flag - whether to remember or forget

setCacheLimit

public void setCacheLimit(Integer limit)

Specified by:

setCacheLimit in interface Table

Parameters:

limit - the limit to set

troidSelection

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

Specified by:

troidSelection in interface Table

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(java.lang.Integer), selection(java.lang.String, java.lang.String, boolean)

selection

public Enumeration<Persistent> selection()
                                  throws SQLPoemException

All the objects in the table.

Specified by:

selection in interface Selectable

Specified by:

selection in interface 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. an Enumeration of all Objects held

Throws:

SQLPoemException

See Also:

Selectable.selection()

selection

public final 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.

Specified by:

selection in interface Table

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(java.lang.Object)

firstSelection

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

Specified by:

firstSelection in interface Table

Parameters:

whereClause - SQL SELECTion criteria for the search: the part that should appear after the WHERE keyword

Returns:

the first item satisfying criteria

selection

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

Specified by:

selection in interface Table

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(java.lang.String)

selection

public Enumeration selection(Persistent criteria)
                      throws SQLPoemException

Return a selection of rows given an exemplar.

Specified by:

selection in interface Table

Parameters:

criteria - Represents selection criteria possibly on joined tables

Returns:

an enumeration of like objects

Throws:

SQLPoemException

See Also:

selection(String, String, boolean)

selection

public Enumeration selection(Persistent criteria,
                             String orderByClause)
                      throws SQLPoemException

Return a selection of rows given arguments specifying a query.

Specified by:

selection in interface Table

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

public Enumeration selection(Persistent criteria,
                             String orderByClause,
                             boolean includeDeleted,
                             boolean excludeUnselectable)
                      throws SQLPoemException

Return a selection of rows given arguments specifying a query.

Specified by:

selection in interface Table

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

public String countSQL(String whereClause)

Specified by:

countSQL in interface Table

Parameters:

whereClause -

Returns:

the SQL string for the current SQL dialect

countSQL

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

Specified by:

countSQL in interface Table

Parameters:

fromClause - Comma separated list of table names

Returns:

the SQL query

count

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

Specified by:

count in interface Table

Returns:

the number records satisfying criteria.

Throws:

SQLPoemException

count

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

Specified by:

count in interface Table

Returns:

the number records satisfying criteria.

Throws:

SQLPoemException

count

public int count(String whereClause)
          throws SQLPoemException

It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.

Specified by:

count in interface Table

Returns:

the number of records satisfying criteria.

Throws:

SQLPoemException

count

public int count()
          throws SQLPoemException

Specified by:

count in interface Table

Returns:

the number records in this table.

Throws:

SQLPoemException

exists

public boolean exists(String whereClause)
               throws SQLPoemException

It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.

Specified by:

exists in interface Table

Parameters:

whereClause - the SQL criteria

Returns:

whether any records satisfy criteria.

Throws:

SQLPoemException

exists

public boolean exists(Persistent persistent)

Specified by:

exists in interface Table

Parameters:

persistent - a Persistent with some fields filled in

Returns:

whether any records exist with the same fields filled

appendWhereClause

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

Specified by:

appendWhereClause in interface Table

See Also:

notifyColumnInfo(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

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

Specified by:

whereClause in interface Table

Returns:

an SQL fragment

whereClause

public 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, Persistent).

Specified by:

whereClause in interface Table

Returns:

an SQL fragment

cnfWhereClause

public String cnfWhereClause(Enumeration persistents)

Specified by:

cnfWhereClause in interface Table

Returns:

an SQL fragment

See Also:

cnfWhereClause(Enumeration, boolean, boolean), whereClause(Persistent)

cnfWhereClause

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

Specified by:

cnfWhereClause in interface Table

Returns:

an SQL fragment

referencesTo

public 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!

Specified by:

referencesTo in interface Table

Returns:

an Enumeration of Persistents

referencesTo

public Enumeration referencesTo(Table table)

All the columns in the table which refer to the given table.

Specified by:

referencesTo in interface Table

Parameters:

table -

Returns:

an Enumeration of Columns referring to the specified Table

getMostRecentTroid

public int getMostRecentTroid()

Specified by:

getMostRecentTroid in interface Table

Returns:

the current highest troid

troidFor

public Integer troidFor(Persistent persistent)

Specified by:

troidFor in interface Table

Parameters:

persistent - unused parameter, but might be needed in another troid schema

Returns:

the next Troid

create

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

Specified by:

create in interface Table

Throws:

InitialisationPoemException - The object failed validation

AccessPoemException

ValidationPoemException

create

public Persistent create(Initialiser initialiser)
                  throws AccessPoemException,
                         ValidationPoemException,
                         InitialisationPoemException

Create a new object (record) in the table.

Specified by:

create in interface 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(org.melati.poem.Persistent), PoemThread.accessToken(), getCanCreate()

newPersistent

public Persistent newPersistent()

Specified by:

newPersistent in interface Table

Returns:

A freshly minted floating Persistent object for this table, ie one without a troid set

_newPersistent

protected JdbcPersistent _newPersistent()

A freshly minted, and uninitialised, Persistent object for the table. You don't ever have to call this and there is no point in doing so This method is overridden in application-specialised Table subclasses derived from the Data Structure Definition.

delete_unsafe

public void delete_unsafe(String whereClause)

It is the programmer's responsibility to ensure that the where clause is suitable for the target DBMS.

Specified by:

delete_unsafe in interface Table

Parameters:

whereClause - the criteria

extrasCount

public int extrasCount()

The number of `extra' (non-DSD-defined) columns in the table.

Specified by:

extrasCount in interface Table

getDefaultCanRead

public final 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.

Specified by:

getDefaultCanRead in interface Table

Returns:

the capability needed to read this table

getDefaultCanWrite

public final 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.

Specified by:

getDefaultCanWrite in interface Table

Returns:

the default Capability required to write a Persistent, if any

getDefaultCanDelete

public final 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.

Specified by:

getDefaultCanDelete in interface Table

Returns:

the default Capability required to delete a Persistent, if any

getCanCreate

public final Capability getCanCreate()

The capability required for creating records in the table. This simply comes from the table's record in the tableinfo table.

Specified by:

getCanCreate in interface Table

Returns:

the Capability required to write to this table

See Also:

create(org.melati.poem.Initialiser)

canReadColumn

public final Column canReadColumn()

Specified by:

canReadColumn in interface Table

Returns:

the canReadColumn or the canSelectColumn or null

canSelectColumn

public final Column canSelectColumn()

Specified by:

canSelectColumn in interface Table

Returns:

the canSelectColumn or null

canWriteColumn

public final Column canWriteColumn()

Specified by:

canWriteColumn in interface Table

Returns:

the canWriteColumn or null

canDeleteColumn

public final Column canDeleteColumn()

Specified by:

canDeleteColumn in interface Table

Returns:

the canDeleteColumn or null

addColumnAndCommit

public Column addColumnAndCommit(ColumnInfo infoP)
                          throws PoemException

Add a Column to the database and the TableInfo table.

Specified by:

addColumnAndCommit in interface Table

Parameters:

infoP - the meta data about the Column

Returns:

the newly added column

Throws:

PoemException

deleteColumnAndCommit

public void deleteColumnAndCommit(ColumnInfo columnInfo)
                           throws PoemException

Specified by:

deleteColumnAndCommit in interface Table

Parameters:

columnInfo - metadata about the column to delete, which is itself deleted

Throws:

PoemException

toString

public 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). 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).

Specified by:

toString in interface Table

Overrides:

toString in class Object

See Also:

Object.toString()

dumpCacheAnalysis

public void dumpCacheAnalysis()

Print some diagnostic information about the contents and consistency of POEM's cache for this table to stderr.

Specified by:

dumpCacheAnalysis in interface Table

dump

public void dump()

Print information about the structure of the table to stdout.

Specified by:

dump in interface Table

dump

public void dump(PrintStream ps)

Print information to PrintStream.

Specified by:

dump in interface Table

Parameters:

ps - PrintStream to dump to

cachedSelection

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

Specified by:

cachedSelection in interface Table

Parameters:

whereClause - raw SQL selection clause appropriate for this DBMS

orderByClause - which field to order by or null

Returns:

the results

cachedCount

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

Specified by:

cachedCount in interface Table

Parameters:

whereClause - raw SQL selection clause appropriate for this DBMS

includeDeleted - whether to include soft deleted records

Returns:

a cached count

cachedCount

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

Specified by:

cachedCount in interface Table

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

public CachedCount cachedCount(Persistent criteria,
                               boolean includeDeleted,
                               boolean excludeUnselectable)

A mechanism for caching a record count.

Specified by:

cachedCount in interface Table

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

public CachedCount cachedCount(Persistent criteria)

Specified by:

cachedCount in interface Table

Parameters:

criteria - a Persistent to extract where clause from

Returns:

a CachedCount of records matching Criteria

cachedCount

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

Specified by:

cachedCount in interface Table

Parameters:

whereClause - raw SQL selection clause appropriate for this DBMS

Returns:

a cached count

cachedExists

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

Specified by:

cachedExists in interface Table

Parameters:

whereClause - raw SQL selection clause appropriate for this DBMS

Returns:

a cached exists

cachedSelectionType

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

Specified by:

cachedSelectionType in interface Table

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

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

Specified by:

cachedSelectionField in interface Table

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

public final 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).

Specified by:

defineColumn in interface Table

Throws:

DuplicateColumnNamePoemException

DuplicateTroidColumnPoemException

DuplicateDeletedColumnPoemException

getNextExtrasIndex

public int getNextExtrasIndex()

Specified by:

getNextExtrasIndex in interface Table

Returns:

incremented extra columns index

setTableInfo

public void setTableInfo(TableInfo tableInfo)

Specified by:

setTableInfo in interface Table

Parameters:

tableInfo - the TableInfo to set

getTableInfo

public TableInfo getTableInfo()

Specified by:

getTableInfo in interface Table

Returns:

the TableInfo for this table.

defaultDisplayName

protected String defaultDisplayName()

The `factory-default' display name for the table. By default this is the table's programmatic name, capitalised. Application-specialised tables override this to return any (displayname = ...) provided in the DSD. This is only ever used at startup time when creating columninfo records for tables that don't have them.

getDsdName

public String getDsdName()

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

Specified by:

getDsdName in interface Table

Returns:

the capitalised name

defaultDisplayOrder

protected int defaultDisplayOrder()

defaultDescription

protected String defaultDescription()

The `factory-default' description for the table, or null if it doesn't have one. Application-specialised tables override this to return any (description = ...) provided in the DSD. This is only ever used at startup time when creating columninfo records for tables that don't have them.

defaultCacheLimit

protected Integer defaultCacheLimit()

defaultRememberAllTroids

protected boolean defaultRememberAllTroids()

defaultCategory

protected String defaultCategory()

createTableInfo

public void createTableInfo()
                     throws PoemException

Create the (possibly overridden) TableInfo if it has not yet been created.

Specified by:

createTableInfo in interface Table

Throws:

PoemException

unifyWithColumnInfo

public void unifyWithColumnInfo()
                         throws PoemException

Match columnInfo with this Table's columns. Conversely, create a ColumnInfo for any columns which don't have one.

Specified by:

unifyWithColumnInfo in interface Table

Throws:

PoemException

unifyWithDB

public void unifyWithDB(ResultSet colDescs)
                 throws PoemException

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

Specified by:

unifyWithDB in interface Table

Parameters:

colDescs - a JDBC ResultSet describing the columns

Throws:

PoemException

init

public void init()

Override this to perform pre-unification initialisation.

Specified by:

init in interface Table

hashCode

public final int hashCode()

Ensure tables can be used as hashtable keys.

Persistent#hashCode() is defined in terms of this but not used at the time of writing.

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

equals

public boolean equals(Object t)

Make sure that two equal table objects have the same name.

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)