Database (POEM 0.8.0-SNAPSHOT API)

java.lang.Object
- org.melati.poem.Database

All Implemented Interfaces:

TransactionPool

Direct Known Subclasses:

PoemDatabaseBase
```
public abstract class Database
extends Object
implements TransactionPool
```
An RDBMS database. Don't instantiate (or subclass) this class, but rather PoemDatabase, which includes the boilerplate code for the standard tables such as user and columninfo which all POEM databases must contain. If the database is predefined by a Data Structure Definition Bar.dsd, there will be an application-specialised subclass of PoemDatabase called BarDatabase which provides named methods for accessing application-specialised objects representing the predefined tables.

See Also:

PoemDatabase

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`Database.ConnectingException` Thrown when a request is made whilst the connection to the underlying database is still in progress.

Constructor Summary

Constructors
Constructor and Description

Database()
Don't subclass this, subclass PoemDatabase.

Constructors
Constructor and Description
`Database()` Don't subclass this, subclass `PoemDatabase`.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addConstraints()` Add database constraints.
`Table<?>`	`addTableAndCommit(TableInfo info, String troidName)` Add a Table to this Database and commit the Transaction.
`Capability`	`administerCapability()`
`User`	`administratorUser()`
`void`	`beginExclusiveLock()` Acquire a lock on the database.
`void`	`beginSession(AccessToken accessToken)` Start a db session.
`int`	`columnCount()`
`Enumeration<Column<?>>`	`columns()`
`void`	`connect(String nameIn, String dbmsclass, String url, String username, String password, int transactionsMaxP)` Connect to an RDBMS database.
`void`	`deleteTableAndCommit(TableInfo info)`
`void`	`disconnect()` Releases database connections.
`Enumeration<Table<?>>`	`displayTables()` All the tables in the database in DisplayOrder order, using current transaction if there is one.
`Enumeration<Table<?>>`	`displayTables(PoemTransaction transaction)` Currently all the tables in the database in DisplayOrder order.
`void`	`dump()` Print information about the structure of the database to stdout.
`void`	`dumpCacheAnalysis()` Print some diagnostic information about the contents and consistency of POEM's cache to stderr.
`void`	`endExclusiveLock()` Release lock.
`void`	`endSession()` End a db session.
`Capability`	`getCanAdminister()` By default, anyone can administer a database.
`abstract CapabilityTable<Capability>`	`getCapabilityTable()` The table of capabilities (required for reading and/or writing records) defined for the database.
`abstract ColumnInfoTable<ColumnInfo>`	`getColumnInfoTable()`
`List<Column<?>>`	`getColumns()` Wrapper around columns()
`Connection`	`getCommittedConnection()`
`Dbms`	`getDbms()`
`String`	`getDisplayName()`
`List<Table<?>>`	`getDisplayTables()` A convenience wrapper around displayTables()
`int`	`getFreeTransactionsCount()`
`abstract GroupCapabilityTable<GroupCapability>`	`getGroupCapabilityTable()` The table containing group-capability records.
`abstract GroupMembershipTable<GroupMembership>`	`getGroupMembershipTable()` A user is a member of a group iff there is a record in this table to say so.
`abstract GroupTable<Group>`	`getGroupTable()`
`String`	`getLastQuery()`
`String`	`getName()`
`int`	`getQueryCount()` Used in testing to check if the cache is being used or a new query is being issued.
`List<Persistent>`	`getReferencesTo(Persistent persistent)` Wrapper around referencesTo()
`List<Column<?>>`	`getReferencesTo(Table<?> table)` Wrapper around referencesTo()
`abstract SettingTable<Setting>`	`getSettingTable()`
`Table<?>`	`getTable(String tableName)` Retrieve the table with a given name.
`abstract TableCategoryTable<TableCategory>`	`getTableCategoryTable()`
`abstract TableInfoTable<TableInfo>`	`getTableInfoTable()`
`List<Table<?>>`	`getTables()` All the tables in the database.
`int`	`getTransactionsCount()`
`abstract UserTable<User>`	`getUserTable()`
`String`	`givesCapabilitySQL(User user, Capability capability)` Get the raw SQL statement for this database's DBMS for Capability check for a User.
`AccessToken`	`guestAccessToken()`
`User`	`guestUser()`
`boolean`	`hasCapability(User user, Capability capability)` Check if a user has the specified Capability.
`void`	`inCommittedTransaction(AccessToken accessToken, PoemTask task)` Perform a task with the database, but not in an insulated transaction.
`void`	`incrementQueryCount(String sql)` Increment query count.
`void`	`inSession(AccessToken accessToken, PoemTask task)` Perform a task with the database.
`void`	`inSessionAsRoot(PoemTask task)`
`boolean`	`isFree(PoemTransaction trans)`
`boolean`	`logCommits()`
`boolean`	`logSQL()`
`void`	`modifyStructure(String sql)` Use this for DDL statements, ie those which alter the structure of the db.
`PoemTransaction`	`poemTransaction(int index)` Find a transaction by its index.
`String`	`quotedName(String nameIn)` Quote a name in the DBMS' specific dialect.
`int`	`recordCount()`
`<P extends Persistent> Enumeration<P>`	`referencesTo(Persistent persistent)` Find all references to specified object in all tables.
`Enumeration<Column<?>>`	`referencesTo(Table<?> tableIn)`
`void`	`setCanAdminister()` Set administrator capability to default.
`void`	`setCanAdminister(String capabilityName)` Set administrator capability to named Capability.
`void`	`setDisplayName(String displayName)`
`void`	`setLogCommits(boolean value)` Toggle commit logging.
`void`	`setLogSQL(boolean value)` Toggle logging.
`void`	`setTransactionsMax(int t)` Set the maximum number of transactions.
`ResultSet`	`sqlQuery(String sql)` Run an arbitrary SQL query against the database.
`int`	`sqlUpdate(String sql)` Run an arbitrary SQL update against the database.
`int`	`tableCount()`
`Enumeration<Table<?>>`	`tables()` All the tables in the database.
`String`	`toString()` Returns the connection url.
`Transaction`	`transaction(int index)` Get a `Transaction` by its index.
`int`	`transactionsMax()` The number of transactions available for concurrent use on the database.
`void`	`trimCache(int maxSize)` Trim POEM's cache to a given size.
`void`	`uncache()` Set the contents of the cache to empty.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Database
```
public Database()
```
    Don't subclass this, subclass PoemDatabase.
    
    See Also:
    
    PoemDatabase
- Method Detail
  - connect
```
public void connect(String nameIn,
                    String dbmsclass,
                    String url,
                    String username,
                    String password,
                    int transactionsMaxP)
             throws PoemException
```
    Connect to an RDBMS database. This should be called once when the application starts up; it will
    - Open this.transactionsMax() JDBC Connections to the database for subsequent `pooling'
    - Unify (reconcile) the structural information about the database given in
      
      the Database Structure Definition (i.e. embodied in the boilerplate code generated from it), including the POEM-standard tables defined in Poem.dsd;
      the metadata tables tableinfo and columninfo;
      the actual JDBC metadata from the RDBMS.
      Any tables or columns defined in the DSD or the metadata tables, but not present in the actual database, will be created.
      Conversely, entries will be created in the metadata tables for tables and columns that don't have them. If an inconsistency is detected between any of the three information sources (such as a fundamental type incompatibility, or a string field which is narrower in the database than it was declared to be), an exception will be thrown. In that case the database will in theory be left untouched, except that in Postgres (at least) all structural updates happen immediately and irrevocably even if made from a transaction subsequently rolled back.
    Parameters:
    
    dbmsclass - The Melati DBMS class (see org/melati/poem/dbms) to use, usually specified in org.melati.LogicalDatabase.properties.
    
    url - The JDBC URL for the database; for instance jdbc:postgresql:williamc. It is the programmer's responsibility to make sure that an appropriate driver has been loaded.
    
    username - The username under which to establish JDBC connections to the database. This has nothing to do with the user/group/capability authentication performed by Melati.
    
    password - The password to go with the username.
    
    transactionsMaxP - The maximum number of concurrent Transactions allowed, usually specified in org.melati.LogicalDatabase.properties.
    
    Throws:
    
    PoemException
    
    See Also:
    
    transactionsMax()
  - disconnect
```
public void disconnect()
                throws PoemException
```
    Releases database connections.
    
    Throws:
    
    PoemException
  - addTableAndCommit
```
public Table<?> addTableAndCommit(TableInfo info,
                                  String troidName)
                           throws PoemException
```
    Add a Table to this Database and commit the Transaction.
    
    Parameters:
    
    info - Table metadata object
    
    troidName - name of troidColumn
    
    Returns:
    
    new minted Table
    
    Throws:
    
    PoemException
  - deleteTableAndCommit
```
public void deleteTableAndCommit(TableInfo info)
```
    Parameters:
    
    info - the tableInfo for the table to delete
  - addConstraints
```
public void addConstraints()
```
    Add database constraints. The only constraints POEM expects are uniqueness and nullability. POEM assumes that the db will exploit indexes where present. However if you wish to export the db to a more DB oriented application or wish to use schema interrogation or visualisation tools then constraints can be added. Whether constraints are added is controlled in org.melati.LogicalDatabase.properties.
  - transactionsMax
```
public final int transactionsMax()
```
    The number of transactions available for concurrent use on the database. This is the number of JDBC Connections opened when the database was connected, this can be set via LogicalDatabase.properties, but defaults to 8 if not set.
    
    Specified by:
    
    transactionsMax in interface TransactionPool
    
    Returns:
    
    the maximum number of Transactions we can store.
    
    See Also:
    
    TransactionPool.transactionsMax()
  - setTransactionsMax
```
public final void setTransactionsMax(int t)
```
    Set the maximum number of transactions. Note that this does not resize the transaction pool so should be called before the db is connected to. Set the maximum number of transactions in this pool.
    
    Specified by:
    
    setTransactionsMax in interface TransactionPool
    
    Parameters:
    
    t - maximum number of transactions to set
    
    See Also:
    
    TransactionPool.setTransactionsMax(int)
  - getTransactionsCount
```
public int getTransactionsCount()
```
    Specified by:
    
    getTransactionsCount in interface TransactionPool
    
    Returns:
    
    Returns the total number of transactions.
    
    See Also:
    
    TransactionPool.getTransactionsCount()
  - getFreeTransactionsCount
```
public int getFreeTransactionsCount()
```
    Specified by:
    
    getFreeTransactionsCount in interface TransactionPool
    
    Returns:
    
    the number of free transactions.
    
    See Also:
    
    TransactionPool.getFreeTransactionsCount()
  - poemTransaction
```
public PoemTransaction poemTransaction(int index)
```
    Find a transaction by its index.
    transaction(i).index() == i
    
    Parameters:
    
    index - the index of the Transaction to return
    
    Returns:
    
    the Transaction with that index
  - transaction
```
public final Transaction transaction(int index)
```
    Get a Transaction by its index.
    
    Specified by:
    
    transaction in interface TransactionPool
    
    Parameters:
    
    index - the Transaction index to retrieve
    
    Returns:
    
    the found Transaction
    
    See Also:
    
    TransactionPool.transaction(int)
  - isFree
```
public boolean isFree(PoemTransaction trans)
```
    Parameters:
    
    trans - a PoemTransaction
    
    Returns:
    
    whether the Transaction is free
  - beginExclusiveLock
```
public void beginExclusiveLock()
```
    Acquire a lock on the database.
  - endExclusiveLock
```
public void endExclusiveLock()
```
    Release lock.
  - inSession
```
public void inSession(AccessToken accessToken,
                      PoemTask task)
```
    Perform a task with the database. Every access to a POEM database must be made in the context of a `transaction' established using this method (note that Melati programmers don't have to worry about this, because the PoemServlet will have done this by the time they get control).
    
    Parameters:
    
    accessToken - A token determining the Capabilitys available to the task, which in turn determine what data it can attempt to read and write without triggering an AccessPoemException. Note that a User can be an AccessToken.
    
    task - What to do: its run() is invoked, in the current Java thread; until run() returns, all POEM accesses made by the thread are taken to be performed with the capabilities given by accessToken, and in a private transaction. No changes made to the database by other transactions will be visible to it (in the sense that once it has seen a particular version of a record, it will always subsequently see the same one), and its own changes will not be made permanent until it completes successfully or performs an explicit PoemThread.commit(). If it terminates with an exception or issues a PoemThread.rollback() its changes will be lost. (The task is allowed to continue after either a commit() or a rollback().)
    
    See Also:
    
    PoemThread, PoemThread.commit(), PoemThread.rollback(), User
  - inSessionAsRoot
```
public void inSessionAsRoot(PoemTask task)
```
    Parameters:
    
    task - the task to run
  - beginSession
```
public void beginSession(AccessToken accessToken)
```
    Start a db session. This is the very manual way of doing db work - not reccomended - use inSession.
  - endSession
```
public void endSession()
```
    End a db session.
    This is the very manual way of doing db work - not recommended - use inSession.
  - inCommittedTransaction
```
public void inCommittedTransaction(AccessToken accessToken,
                                   PoemTask task)
```
    Perform a task with the database, but not in an insulated transaction. The effect is the same as inSession, except that the task will see changes to the database made by other transactions as they are committed, and it is not allowed to make any changes of its own.
    A modification will trigger a WriteCommittedException, however a create operation will trigger a NullPointerException, as we have no Transaction.
    
    Not recommended; why exactly do you want to sidestep the Transaction handling?
    
    See Also:
    
    inSession(org.melati.poem.AccessToken, org.melati.poem.PoemTask)
  - getTable
```
public final Table<?> getTable(String tableName)
                        throws NoSuchTablePoemException
```
    Retrieve the table with a given name.
    
    Parameters:
    
    tableName - The name of the table to return, as in the RDBMS database. It's case-sensitive, and some RDBMSs such as Postgres 6.4.2 (and perhaps other versions) treat upper case letters in identifiers inconsistently, so the name is forced to lowercase.
    
    Returns:
    
    the Table of that name
    
    Throws:
    
    NoSuchTablePoemException - if no table with the given name exists in the RDBMS
  - tables
```
public final Enumeration<Table<?>> tables()
```
    All the tables in the database. NOTE This will include any deleted tables
    
    Returns:
    
    an Enumeration of Tables, in no particular order.
  - getTables
```
public final List<Table<?>> getTables()
```
    All the tables in the database. NOTE This will include any deleted tables
  - displayTables
```
public Enumeration<Table<?>> displayTables()
```
    All the tables in the database in DisplayOrder order, using current transaction if there is one.
    
    Returns:
    
    an Enumeration of Tables
  - getDisplayTables
```
public List<Table<?>> getDisplayTables()
```
    A convenience wrapper around displayTables()
  - displayTables
```
public Enumeration<Table<?>> displayTables(PoemTransaction transaction)
```
    Currently all the tables in the database in DisplayOrder order.
    
    Returns:
    
    an Enumeration of Tables
  - columns
```
public Enumeration<Column<?>> columns()
```
    Returns:
    
    All the Columns in the whole Database
  - getColumns
```
public List<Column<?>> getColumns()
```
    Wrapper around columns()
  - tableCount
```
public int tableCount()
```
  - columnCount
```
public int columnCount()
```
  - recordCount
```
public int recordCount()
```
  - getTableInfoTable
```
public abstract TableInfoTable<TableInfo> getTableInfoTable()
```
    Returns:
    
    The metadata table with information about all tables in the database.
  - getTableCategoryTable
```
public abstract TableCategoryTable<TableCategory> getTableCategoryTable()
```
    Returns:
    
    The Table Category Table.
  - getColumnInfoTable
```
public abstract ColumnInfoTable<ColumnInfo> getColumnInfoTable()
```
    Returns:
    
    The metadata table with information about all columns in all tables in the database.
  - getCapabilityTable
```
public abstract CapabilityTable<Capability> getCapabilityTable()
```
    The table of capabilities (required for reading and/or writing records) defined for the database. Users acquire capabilities in virtue of being members of groups.
    
    Returns:
    
    the CapabilityTable
    
    See Also:
    
    Persistent.assertCanRead(), Persistent.assertCanWrite(), Persistent.assertCanDelete(), JdbcTable.getDefaultCanRead(), JdbcTable.getDefaultCanWrite(), User, getUserTable(), Group, getGroupTable()
  - getUserTable
```
public abstract UserTable<User> getUserTable()
```
    Returns:
    
    the table of known users of the database
  - getGroupTable
```
public abstract GroupTable<Group> getGroupTable()
```
    Returns:
    
    the table of defined user groups for the database
  - getGroupMembershipTable
```
public abstract GroupMembershipTable<GroupMembership> getGroupMembershipTable()
```
    A user is a member of a group iff there is a record in this table to say so.
    
    Returns:
    
    the table containing group-membership records
  - getGroupCapabilityTable
```
public abstract GroupCapabilityTable<GroupCapability> getGroupCapabilityTable()
```
    The table containing group-capability records. A group has a certain capability iff there is a record in this table to say so.
    
    Returns:
    
    the GroupCapability table
  - getSettingTable
```
public abstract SettingTable<Setting> getSettingTable()
```
    Returns:
    
    the Setting Table.
  - sqlQuery
```
public ResultSet sqlQuery(String sql)
                   throws SQLPoemException
```
    Run an arbitrary SQL query against the database. This is a low-level java.sql.Statement.executeQuery, intended for fiddly queries for which the higher-level methods are too clunky or inflexible. Note that it bypasses the access control mechanism!
    
    Returns:
    
    the ResultSet resulting from running the query
    
    Throws:
    
    SQLPoemException
    
    See Also:
    
    Table.selection(), Table.selection(java.lang.String), Column.selectionWhereEq(java.lang.Object)
  - sqlUpdate
```
public int sqlUpdate(String sql)
              throws SQLPoemException
```
    Run an arbitrary SQL update against the database. This is a low-level java.sql.Statement.executeUpdate, intended for fiddly updates for which the higher-level methods are too clunky or inflexible.
    NOTE This bypasses the access control mechanism. Furthermore, the cache will be left out of sync with the database and must be cleared out (explicitly, manually) after the current transaction has been committed or completed.
    
    Returns:
    
    either the row count for INSERT, UPDATE or DELETE statements, or 0 for SQL statements that return nothing
    
    Throws:
    
    SQLPoemException
    
    See Also:
    
    Table.selection(), Table.selection(java.lang.String), Column.selectionWhereEq(java.lang.Object), uncache()
  - guestUser
```
public User guestUser()
```
    Returns:
    
    the guest
  - administratorUser
```
public User administratorUser()
```
    Returns:
    
    the administrator
  - givesCapabilitySQL
```
public String givesCapabilitySQL(User user,
                                 Capability capability)
```
    Get the raw SQL statement for this database's DBMS for Capability check for a User.
    
    Parameters:
    
    user -
    
    capability -
    
    Returns:
    
    the raw SQL appropriate for this db
  - hasCapability
```
public boolean hasCapability(User user,
                             Capability capability)
```
    Check if a user has the specified Capability.
    
    Parameters:
    
    user - the User to check
    
    capability - the Capability required
    
    Returns:
    
    whether User has Capability
  - guestAccessToken
```
public AccessToken guestAccessToken()
```
    Returns:
    
    the guest token.
  - administerCapability
```
public Capability administerCapability()
```
    Returns:
    
    the Capability required to administer this db.
  - getCanAdminister
```
public Capability getCanAdminister()
```
    By default, anyone can administer a database.
    
    Returns:
    
    the required Capability to administer the db (null unless overridden)
  - setCanAdminister
```
public void setCanAdminister(String capabilityName)
```
    Set administrator capability to named Capability.
    
    Parameters:
    
    capabilityName - name of Capability
  - setCanAdminister
```
public void setCanAdminister()
```
    Set administrator capability to default.
    NOTE Once a database has had its canAdminister capability set there is no mechanism to set it back to null.
  - trimCache
```
public void trimCache(int maxSize)
```
    Trim POEM's cache to a given size.
    
    Parameters:
    
    maxSize - The data for all but this many records per table will be dropped from POEM's cache, on a least-recently-used basis.
  - uncache
```
public void uncache()
```
    Set the contents of the cache to empty.
  - referencesTo
```
public <P extends Persistent> Enumeration<P> referencesTo(Persistent persistent)
```
    Find all references to specified object in all tables.
    
    Parameters:
    
    persistent - the object being referred to
    
    Returns:
    
    an Enumeration of Persistents
  - getReferencesTo
```
public List<Persistent> getReferencesTo(Persistent persistent)
```
    Wrapper around referencesTo()
    
    Returns:
    
    a List of Columns referring to given Table
  - referencesTo
```
public Enumeration<Column<?>> referencesTo(Table<?> tableIn)
```
    Returns:
    
    An Enumeration of Columns referring to the specified Table.
  - getReferencesTo
```
public List<Column<?>> getReferencesTo(Table<?> table)
```
    Wrapper around referencesTo()
    
    Returns:
    
    a List of Columns referring to given Table
  - dumpCacheAnalysis
```
public void dumpCacheAnalysis()
```
    Print some diagnostic information about the contents and consistency of POEM's cache to stderr.
  - dump
```
public void dump()
```
    Print information about the structure of the database to stdout.
  - getDbms
```
public Dbms getDbms()
```
    Returns:
    
    the Database Management System class of this db
  - quotedName
```
public final String quotedName(String nameIn)
```
    Quote a name in the DBMS' specific dialect.
    
    Parameters:
    
    nameIn -
    
    Returns:
    
    name quoted.
  - toString
```
public String toString()
```
    Returns the connection url. If you want a simple name see LogicalDatabase.
    
    Overrides:
    
    toString in class Object
    
    See Also:
    
    Object.toString()
  - getCommittedConnection
```
public Connection getCommittedConnection()
```
    Returns:
    
    the non-transactioned jdbc Connection
  - logSQL
```
public boolean logSQL()
```
    Returns:
    
    whether logging is switched on
  - setLogSQL
```
public void setLogSQL(boolean value)
```
    Toggle logging.
  - logCommits
```
public boolean logCommits()
```
    Returns:
    
    whether database commits should be logged
  - setLogCommits
```
public void setLogCommits(boolean value)
```
    Toggle commit logging.
  - getQueryCount
```
public int getQueryCount()
```
    Used in testing to check if the cache is being used or a new query is being issued.
    
    Returns:
    
    Returns the queryCount.
  - incrementQueryCount
```
public void incrementQueryCount(String sql)
```
    Increment query count.
  - getLastQuery
```
public String getLastQuery()
```
    Returns:
    
    the most recent query
  - getName
```
public String getName()
```
    Returns:
    
    the name
  - getDisplayName
```
public String getDisplayName()
```
    Returns:
    
    the displayName
  - setDisplayName
```
public void setDisplayName(String displayName)
```
    Parameters:
    
    displayName - the displayName to set
  - modifyStructure
```
public void modifyStructure(String sql)
                     throws StructuralModificationFailedPoemException
```
    Use this for DDL statements, ie those which alter the structure of the db. Postgresql in particular does not like DDL statements being executed within a transaction.
    
    Parameters:
    
    sql - the SQL DDL statement to execute
    
    Throws:
    
    StructuralModificationFailedPoemException

Class Database

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Database

Method Detail

connect

disconnect

addTableAndCommit

deleteTableAndCommit

addConstraints

transactionsMax

setTransactionsMax

getTransactionsCount

getFreeTransactionsCount

poemTransaction

transaction

isFree

beginExclusiveLock

endExclusiveLock

inSession

inSessionAsRoot

beginSession

endSession

inCommittedTransaction

getTable

tables

getTables

displayTables

getDisplayTables

displayTables

columns

getColumns

tableCount

columnCount

recordCount

getTableInfoTable

getTableCategoryTable

getColumnInfoTable

getCapabilityTable

getUserTable

getGroupTable

getGroupMembershipTable

getGroupCapabilityTable

getSettingTable

sqlQuery

sqlUpdate

guestUser

administratorUser

givesCapabilitySQL

hasCapability

guestAccessToken

administerCapability

getCanAdminister

setCanAdminister

setCanAdminister

trimCache

uncache

referencesTo

getReferencesTo

referencesTo

getReferencesTo

dumpCacheAnalysis

dump

getDbms

quotedName

toString

getCommittedConnection

logSQL

setLogSQL

logCommits

setLogCommits

getQueryCount

incrementQueryCount

getLastQuery

getName

getDisplayName

setDisplayName