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

Modifier and Type	Method and Description
String	alterColumnAddCommentSQL(Column<?> column, String comment)
String	alterColumnNotNullableSQL(String tableName, Column<?> column) Return the SQL snippet to alter a column to not nullable.
String	alterTableAddCommentSQL(Table<?> table, String comment)
String	booleanTrueExpression(Column<Boolean> booleanColumn) Accommodate lack of boolean types in underlying DBMS.
boolean	canBeIndexed(Column<?> column) Whether a Column can have an SQL index applied to it.
boolean	canDropColumns() Whether this DBMS can drop columns.
<S,O> PoemType<O>	canRepresent(PoemType<S> storage, PoemType<O> other) 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) Accommodate 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) Accommodate different treatment of different sized binary data.
Connection	getConnection(String url, String user, String password) Return a connection.
String	getFixedPtSqlDefinition(int scale, int precision) Accommodate 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) Accommodate 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() Accommodate Long / Bigint deviants.
String	getPrimaryKeyDefinition(String fieldName) Return the PRIMARY KEY definition string for this dbms.
String	getQuotedName(String name) Accommodate different quoting strategies.
String	getQuotedValue(SQLType<?> sqlType, String value) Accommodate 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) Accommodate 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) Accommodate casting in placeholders.
String	selectLimit(String querySelection, int limit) Accommodate 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) Accommodate 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)

Accommodate 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)

Accommodate 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)

Accommodate casting in placeholders.

Parameters:

type - the PoemType

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)

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

Accommodate 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()

Accommodate Long / Bigint deviants.

Returns:

the keyword to use.

sqlBooleanValueOfRaw

String sqlBooleanValueOfRaw(Object raw)

Accommodate different true and false values.

Returns:

the DBMS specific truth and false values

getBinarySqlDefinition

String getBinarySqlDefinition(int size)
                       throws SQLException

Accommodate 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

Accommodate 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

<S,O> PoemType<O> canRepresent(PoemType<S> storage,
                               PoemType<O> other)

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

Parameters:

storage - the container

other - the type to store

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 corresponding name to use within Melati

getIndexLength

String getIndexLength(Column<?> column)

Accommodate 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)

Accommodate 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

alterColumnAddCommentSQL

String alterColumnAddCommentSQL(Column<?> column,
                                String comment)

Parameters:

column - the target to add a remark to

comment - the remark to add

Returns:

an update SQL command or null

alterTableAddCommentSQL

String alterTableAddCommentSQL(Table<?> table,
                               String comment)

Parameters:

table - the target to add a remark to

comment - the remark to add

Returns:

an update SQL command or null

selectLimit

String selectLimit(String querySelection,
                   int limit)

Accommodate different limiting syntax.

Parameters:

querySelection - main body of query

limit - number to limit to

Returns:

limited query

booleanTrueExpression

String booleanTrueExpression(Column<Boolean> booleanColumn)

Accommodate lack of boolean types in underlying DBMS.

Parameters:

booleanColumn - the column which should be a boolean

Returns:

an expression 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 = ?