org.melati.poem
Class JdbcTable

Package class diagram package JdbcTable
java.lang.Object
  extended by 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)


Copyright © 2000-2010 PanEris. All Rights Reserved.