org.melati.poem.dbms
Interface Dbms

All Known Implementing Classes:

AnsiStandard, FirstSQL, Hsqldb, HsqldbText, Interbase, Mckoi, Mimer, MSAccess, MySQL, Oracle, Postgresql, SQLServer

public interface Dbms

A Database Management System.

Method Summary

String	alterColumnNotNullableSQL(String tableName, Column column) Return the SQL snippet to alter a column to not nullable.
String	booleanTrueExpression(Column booleanColumn) Accomodate lack of boolean types.
boolean	canBeIndexed(Column column) Whether a Column can have an SQL index applied to it.
boolean	canDropColumns() Whether this DBMS can drop columns.
PoemType<?>	canRepresent(PoemType<?> storage, PoemType<?> type) Enable one PoemType to represent another, for example a bit to represent a boolean.
boolean	canStoreBlobs() Whether this DBMS can store binary data.
String	caseInsensitiveRegExpSQL(String term1, String term2) Accomodate the variety of ways of ignoring case.
String	createTableOptionsSql() Accomodate MySQL table creation options.
String	createTableSql(Table table)
String	createTableTypeQualifierSql(Table table) Allow Hsqldb to have a different create table syntax.
SQLPoemType	defaultPoemTypeOfColumnMetaData(ResultSet rs) The simplest POEM type corresponding to a JDBC description from the database.
SQLPoemException	exceptionForUpdate(Table table, PreparedStatement ps, boolean insert, SQLException e) Version of previous method for PreparedStatements.
SQLPoemException	exceptionForUpdate(Table table, String sql, boolean insert, SQLException e) An exception appropriate for expressing what really went wrong during a write to the db.
String	getBinarySqlDefinition(int size) Accomodate different treatment of different sized binary data.
Connection	getConnection(String url, String user, String password) Return a connection.
String	getFixedPtSqlDefinition(int scale, int precision) Accomodate differing Fixed Point notations.
String	getForeignKeyDefinition(String tableName, String fieldName, String targetTableName, String targetTableFieldName, String fixName) If Foreign key definitions are part of field definitions, otherwise blank (silently unsupported).
String	getIndexLength(Column column) Accomodate DBMS which require a length for BLOBS.
String	getJdbcMetadataName(String name) Some DBMSen (HSQLDB) use canonical uppercased names in the metadata but not in normal use.
String	getLongSqlDefinition() Accomodate Long / Bigint deviants.
String	getPrimaryKeyDefinition(String fieldName) Return the PRIMARY KEY definition string for this dbms.
String	getQuotedName(String name) Accomodate different quoting strategies.
String	getQuotedValue(SQLType sqlType, String value) Accomodate different quoting strategies for values.
String	getSchema() The db schema name to use, if any.
String	getSqlDefaultValue(SQLType type) Used to set a not null value when creating a non nullable column.
String	getSqlDefinition(String sqlTypeName) Retrieve a SQL type keyword used by the DBMS for the given Melati type name.
String	getStringSqlDefinition(int size) Accomodate String / Text distinction.
String	givesCapabilitySQL(Integer userTroid, String capabilityExpr) SQL string to get a Capability.
String	melatiName(String name) Reverse the mapping in unreservedName.
String	preparedStatementPlaceholder(PoemType<?> type) Accomodate casting in placeholders.
String	selectLimit(String querySelection, int limit) Accomodate different limiting syntax.
void	shutdown(Connection connection) A no-op for all but hsqldb, where the db needs to be shutdown when the servlet container or jvm is destroyed.
String	sqlBooleanValueOfRaw(Object raw) Accomodate different true and false values.
String	tableInitialisationSql(Table table)
String	toString() A string to represent this DBMS.
void	unloadDriver() Used in tests to allow multiple dbmsen to be loaded and unloaded.
String	unreservedName(String name) Translate special names to non special ones.

Method Detail

unloadDriver

void unloadDriver()

Used in tests to allow multiple dbmsen to be loaded and unloaded.

getConnection

Connection getConnection(String url,
                         String user,
                         String password)
                         throws ConnectionFailurePoemException

Return a connection.

Parameters:

url - the jdbc URL

user - the user to connect as, may be null

password - the password for user, may be null

Returns:

the connection

Throws:

ConnectionFailurePoemException - is we cannot connect

getSchema

String getSchema()

The db schema name to use, if any. This is typically the JDBC connection URL User string.

Returns:

the schema to use or null if not required

shutdown

void shutdown(Connection connection)
              throws SQLException

A no-op for all but hsqldb, where the db needs to be shutdown when the servlet container or jvm is destroyed.

Throws:

SQLException

getQuotedName

String getQuotedName(String name)

Accomodate different quoting strategies.

Parameters:

name - the unquoted name

Returns:

the name quoted (or not) appropriate for this Dbms

getQuotedValue

String getQuotedValue(SQLType sqlType,
                      String value)

Accomodate different quoting strategies for values.

Parameters:

sqlType - the SQLType of the value

value - the value

Returns:

a String quoted appropriately

getJdbcMetadataName

String getJdbcMetadataName(String name)

Some DBMSen (HSQLDB) use canonical uppercased names in the metadata but not in normal use. see org.melati.poem.Table#unifyWithDB

Parameters:

name - entity name such as tableinfo

Returns:

the (un)quoted name

preparedStatementPlaceholder

String preparedStatementPlaceholder(PoemType<?> type)

Accomodate casting in placeholders.

Parameters:

type -

Returns:

the place holder

See Also:

Postgresql

createTableSql

String createTableSql(Table table)

Returns:

The appropriate SQL string to create a table

createTableTypeQualifierSql

String createTableTypeQualifierSql(Table table)

Allow Hsqldb to have a different create table syntax. Should have trailing space if not empty String

createTableOptionsSql

String createTableOptionsSql()

Accomodate MySQL table creation options.

Returns:

DMBS specific table creation options or empty String

tableInitialisationSql

String tableInitialisationSql(Table table)

Parameters:

table -

Returns:

SQL to be run after creation or null

getSqlDefinition

String getSqlDefinition(String sqlTypeName)

Retrieve a SQL type keyword used by the DBMS for the given Melati type name. Override this in non-Ansi standard dbms to handle variants.

Parameters:

sqlTypeName - the Melati internal type name

Returns:

this dbms specific type keyword

getStringSqlDefinition

String getStringSqlDefinition(int size)
                              throws SQLException

Accomodate String / Text distinction.

Parameters:

size - the string length (-1 means no limit)

Returns:

the SQL definition for a string of this size

Throws:

SQLException

getLongSqlDefinition

String getLongSqlDefinition()

Accomodate Long / Bigint deviants.

Returns:

the keyword to use.

sqlBooleanValueOfRaw

String sqlBooleanValueOfRaw(Object raw)

Accomodate different true and false values.

Returns:

the DBMS specific truth and false values

getBinarySqlDefinition

String getBinarySqlDefinition(int size)
                              throws SQLException

Accomodate different treatment of different sized binary data.

Parameters:

size - how big the field is

Returns:

the keyword to use

Throws:

SQLException

getFixedPtSqlDefinition

String getFixedPtSqlDefinition(int scale,
                               int precision)
                               throws SQLException

Accomodate differing Fixed Point notations.

Parameters:

scale - the number of places to right of decimal point

precision - how many digits in total

Returns:

the keywords to use

Throws:

SQLException - potentially

canRepresent

PoemType<?> canRepresent(PoemType<?> storage,
                         PoemType<?> type)

Enable one PoemType to represent another, for example a bit to represent a boolean.

Parameters:

storage - the POEM native type

type - the current type

Returns:

the PoemType to use

defaultPoemTypeOfColumnMetaData

SQLPoemType defaultPoemTypeOfColumnMetaData(ResultSet rs)
                                            throws SQLException

The simplest POEM type corresponding to a JDBC description from the database.

Parameters:

rs - the JDBC metadata

Returns:

the PoemType to use

Throws:

SQLException - potentially

canDropColumns

boolean canDropColumns()

Whether this DBMS can drop columns.

Returns:

true if we can

canStoreBlobs

boolean canStoreBlobs()

Whether this DBMS can store binary data.

Returns:

true if we can

exceptionForUpdate

SQLPoemException exceptionForUpdate(Table table,
                                    String sql,
                                    boolean insert,
                                    SQLException e)

An exception appropriate for expressing what really went wrong during a write to the db. This gives the opportunity to try to interpret the getMessage text returned by the underlying driver, so that a more friendly error page can be put together for the user. Canonically, this is used to separate out "duplicate key" errors from more serious problems.

Parameters:

table - The table on which the update was affected

sql - The operation attempted, or possibly null

insert - Whether the operation was an INSERT as opposed to an UPDATE

e - The raw SQL exception: the routine is meant to try to interpret e.getMessage if it can

Returns:

an appropriate exception

See Also:

Postgresql.exceptionForUpdate(org.melati.poem.Table, java.lang.String, boolean, java.sql.SQLException)

exceptionForUpdate

SQLPoemException exceptionForUpdate(Table table,
                                    PreparedStatement ps,
                                    boolean insert,
                                    SQLException e)

Version of previous method for PreparedStatements. By default (in the AnsiStandard implementation of Dbms) this simply invokes PreparedStatement.toString() and calls the String version.

Parameters:

table - The table on which the update was affected

ps - The operation attempted, or possibly null

insert - Whether the operation was an INSERT as opposed to an UPDATE

e - The raw SQL exception: the routine is meant to try to interpret e.getMessage if it can

Returns:

an appropriate exception

See Also:

AnsiStandard.exceptionForUpdate(org.melati.poem.Table, java.lang.String, boolean, java.sql.SQLException)

unreservedName

String unreservedName(String name)

Translate special names to non special ones.

Parameters:

name - the field or table name

Returns:

the name translated if necessary

melatiName

String melatiName(String name)

Reverse the mapping in unreservedName.

Parameters:

name - an SQL name

Returns:

the coresponding name to use within Melati

getIndexLength

String getIndexLength(Column column)

Accomodate DBMS which require a length for BLOBS.

Parameters:

column - the POEM Column we are dealing with

Returns:

SQL length string

canBeIndexed

boolean canBeIndexed(Column column)

Whether a Column can have an SQL index applied to it.

Parameters:

column - the POEM Column we are dealing with

Returns:

true if it can, false otherwise.

givesCapabilitySQL

String givesCapabilitySQL(Integer userTroid,
                          String capabilityExpr)

SQL string to get a Capability.

Parameters:

userTroid - the troid of the User to use in the query

capabilityExpr - the capability troid we need

Returns:

the SQL query to use

caseInsensitiveRegExpSQL

String caseInsensitiveRegExpSQL(String term1,
                                String term2)

Accomodate the variety of ways of ignoring case.

Parameters:

term1 - the term to find in

term2 - the quoted term to find

Returns:

the SQL query to use

toString

String toString()

A string to represent this DBMS.

Overrides:

toString in class Object

Returns:

the class name.

getForeignKeyDefinition

String getForeignKeyDefinition(String tableName,
                               String fieldName,
                               String targetTableName,
                               String targetTableFieldName,
                               String fixName)

If Foreign key definitions are part of field definitions, otherwise blank (silently unsupported).

Parameters:

tableName - the table that this column is in, unquoted

fieldName - often the name of the foreign table, unquoted

targetTableName - the table that this is a foreign key into, unquoted

targetTableFieldName - name of the primary key field of the foreign table, often id, unquoted

fixName - name of the IntegrityFix

Returns:

The definition string

getPrimaryKeyDefinition

String getPrimaryKeyDefinition(String fieldName)

Return the PRIMARY KEY definition string for this dbms.

Parameters:

fieldName - the table Troid column, often id, unquoted

Returns:

The definition string

alterColumnNotNullableSQL

String alterColumnNotNullableSQL(String tableName,
                                 Column column)

Return the SQL snippet to alter a column to not nullable.

Parameters:

tableName -

column -

Returns:

SQL snippet to set a column not nullable

selectLimit

String selectLimit(String querySelection,
                   int limit)

Accomodate different limiting syntax.

Parameters:

querySelection - main body of query

limit - number to limit to

Returns:

limited query

booleanTrueExpression

String booleanTrueExpression(Column booleanColumn)

Accomodate lack of boolean types.

Parameters:

booleanColumn -

Returns:

an expresion that evaluates to True ie the column name or column name = 1

getSqlDefaultValue

String getSqlDefaultValue(SQLType type)

Used to set a not null value when creating a non nullable column.

Parameters:

type - the type name

Returns:

a String suitable for substitution in UPDATE table SET field = ?