|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.java.ao.DatabaseProvider
net.java.ao.db.HSQLDatabaseProvider
public class HSQLDatabaseProvider
Constructor Summary | |
---|---|
HSQLDatabaseProvider(String uri,
String username,
String password)
|
Method Summary | ||
---|---|---|
protected boolean |
considerPrecision(DDLField field)
Determines whether or not the database allows explicit precisions for the field in question. |
|
protected String |
convertTypeToString(DatabaseType<?> type)
Converts the specified type into the database-specific DDL String value. |
|
void |
dispose()
Frees any resources held by the database provider or delegate libraries (such as connection pools). |
|
protected
|
executeInsertReturningKey(Connection conn,
Class<T> pkType,
String pkField,
String sql,
DBParam... params)
Delegate method to execute an INSERT statement returning any auto-generated primary key values. |
|
protected String |
getDateFormat()
Returns the database-specific TIMESTAMP text format as defined by the SimpleDateFormat syntax. |
|
Class<? extends Driver> |
getDriverClass()
Returns the JDBC Driver class which corresponds to the database being abstracted. |
|
ResultSet |
getTables(Connection conn)
Returns a result set of all of the tables (and associated meta) in the database. |
|
|
insertReturningKey(Connection conn,
Class<T> pkType,
String pkField,
boolean pkIdentity,
String table,
DBParam... params)
Generates an INSERT statement to be used to create a new row in the database, returning the primary key value. |
|
Object |
parseValue(int type,
String value)
Parses the database-agnostic String value relevant to the specified SQL
type in int form (as defined by Types and returns
the Java value which corresponds. |
|
protected String |
renderAlterTableChangeColumnStatement(DDLTable table,
DDLField oldField,
DDLField field)
Generates the database-specific DDL statement only for altering a table and changing a column. |
|
protected String |
renderAlterTableDropKey(DDLForeignKey key)
Generates the database-specific DDL statement required to remove a foreign key from a table. |
|
protected String |
renderAutoIncrement()
Generates the DDL fragment required to specify an INTEGER field as auto-incremented. |
|
protected String |
renderConstraintsForTable(DDLTable table)
Renders the foreign key constraints in database-specific DDL for the table in question. |
|
protected String |
renderDropIndex(DDLIndex index)
Generates the database-specific DDL statement required to drop an index. |
|
protected String |
renderOnUpdate(DDLField field)
Renders the appropriate field suffix to allow for the OnUpdate functionality. |
|
protected String |
renderQueryLimit(Query query)
Renders the LIMIT portion of the query in the database-specific SQL dialect. |
|
protected String |
renderQuerySelect(Query query,
TableNameConverter converter,
boolean count)
Renders the SELECT portion of a given Query instance in the
manner required by the database-specific SQL implementation. |
|
protected String |
renderUnique()
Renders the UNIQUE constraint as defined by the
database-specific DDL syntax. |
|
protected String |
renderValue(Object value)
Renders the given Java instance in a database-specific way. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public HSQLDatabaseProvider(String uri, String username, String password)
Method Detail |
---|
public Class<? extends Driver> getDriverClass() throws ClassNotFoundException
DatabaseProvider
Returns the JDBC Driver class which corresponds to the database being abstracted. This should be implemented in such a way as to initialize and register the driver with JDBC. For most drivers, this requires code in the following form:
public Class<? extends Driver> getDriverClass() { return (Class<? extends Driver>) Class.forName("com.mysql.jdbc.Driver"); }
The following does not fire the driver's static initializer and thus will (usually) not work:
public Class<? extends Driver> getDriverClass() { return com.mysql.jdbc.Driver.class; }
If the driver is not on the classpath, a ClassNotFoundException
can and should be thrown (certain auto-magic configuration sections of
ActiveObjects depend upon this under certain circumstances).
getDriverClass
in class DatabaseProvider
Driver
implementation which corresponds to the
relevant database.
ClassNotFoundException
public <T> T insertReturningKey(Connection conn, Class<T> pkType, String pkField, boolean pkIdentity, String table, DBParam... params) throws SQLException
DatabaseProvider
Generates an INSERT statement to be used to create a new row in the
database, returning the primary key value. This method also invokes
the delegate method, DatabaseProvider.executeInsertReturningKey(Connection, Class, String, String, DBParam...)
passing the appropriate parameters and query. This method is required
because some databases do not support the JDBC parameter
RETURN_GENERATED_KEYS
(such as HSQLDB and PostgreSQL).
Also, some databases (such as MS SQL Server) require odd tricks to
support explicit value passing to auto-generated fields. This method
should take care of any extra queries or odd SQL generation required
to implement both auto-generated primary key returning, as well as
explicit primary key value definition.
Overriding implementations of this method should be sure to use the
Connection
instance passed to the method, not a new
instance generated using the DatabaseProvider.getConnection()
method. This is
because this method is in fact a delegate invoked by EntityManager
as part of the entity creation process and may be part of a transaction,
a bulk creation or some more complicated operation. Both optimization
and usage patterns on the API dictate that the specified connection
instance be used. Implementations may assume that the given connection
instance is never null
.
The default implementation of this method should be sufficient for any
fully compliant ANSI SQL database with a properly implemented JDBC
driver. Note that this method should not not actually execute
the SQL it generates, but pass it on to the DatabaseProvider.executeInsertReturningKey(Connection, Class, String, String, DBParam...)
method, allowing for functional delegation and better extensibility.
However, this method may execute any additional statements required to
prepare for the INSERTion (as in the case of MS SQL Server which requires
some config parameters to be set on the database itself prior to INSERT).
insertReturningKey
in class DatabaseProvider
conn
- The connection to be used in the eventual execution of the
generated SQL statement.pkType
- The Java type of the primary key value. Can be used to
perform a linear search for a specified primary key value in the
params
list. The return value of the method must be of
the same type.pkField
- The database field which is the primary key for the
table in question. Can be used to perform a linear search for a
specified primary key value in the params
list.pkIdentity
- Flag indicating whether or not the primary key field
is auto-incremented by the database (IDENTITY field).table
- The name of the table into which the row is to be INSERTed.params
- A varargs array of parameters to be passed to the
INSERT statement. This may include a specified value for the
primary key.
SQLException
- If the INSERT fails in the delegate method, or
if any additional statements fail with an exception.DatabaseProvider.executeInsertReturningKey(Connection, Class, String, String, DBParam...)
protected <T> T executeInsertReturningKey(Connection conn, Class<T> pkType, String pkField, String sql, DBParam... params) throws SQLException
DatabaseProvider
Delegate method to execute an INSERT statement returning any auto-generated
primary key values. This method is primarily designed to be called as a delegate
from the DatabaseProvider.insertReturningKey(Connection, Class, String, boolean, String, DBParam...)
method. The idea behind this method is to allow custom implementations to
override this method to potentially execute other statements (such as getting the
next value in a sequence) rather than the default implementaiton which uses the
JDBC constant, RETURN_GENERATED_KEYS
. Any database which has a
fully-implemented JDBC driver should have no problems with the default
implementation of this method.
Part of the design behind splitting insertReturningKey
and
executeInsertReturningKey
is so that logic for generating the actual
INSERT statement need not be duplicated throughout the code and in custom
implementations providing trivial changes to the default algorithm. This method
should avoid actually generating SQL if at all possible.
This method should iterate through the passed DBParam(s)
to
ensure that no primary key value was explicitly specified. If one was, it
should be used in leiu of one which is auto-generated by the database. Also,
it is this value which should be returned if specified, rather than the value
which would have been generated or null
. As such, this method
should always return exactly the value of the primary key field in the row which
was just inserted, regardless of what that value may be.
In cases where the database mechanism for getting the next primary key value
is not thread safe, this method should be declared synchronized
,
or some thread synchronization technique employed. Unfortunately, it is not
always possible to ensure that no other INSERT could (potentially) "steal" the
expected value out from under the algorithm. Such scenarios are to be avoided
when possible, but the algorithm need not take extremely escoteric concurrency
cases into account. (see the HSQLDB provider for an example of such a
less-than-thorough asynchronous algorithm)
IMPORTANT: The INSERT Statement
must use the specified
connection, rather than a new one retrieved from DatabaseProvider.getConnection()
or
equivalent. This is because the INSERT may be part of a bulk insertion, a
transaction, or possibly another such operation. It is also important to note
that this method should not close the connection. Doing so could cause the
entity creation algorithm to fail at a higher level up the stack.
executeInsertReturningKey
in class DatabaseProvider
conn
- The database connection to use in executing the INSERT statement.pkType
- The Java class type of the primary key field (for use both in
searching the params
as well as performing value conversion
of auto-generated DB values into proper Java instances).pkField
- The database field which is the primary key for the
table in question. Can be used to perform a linear search for a
specified primary key value in the params
list.params
- A varargs array of parameters to be passed to the
INSERT statement. This may include a specified value for the
primary key.
SQLException
- If the INSERT fails in the delegate method, or
if any additional statements fail with an exception.DatabaseProvider.insertReturningKey(Connection, Class, String, boolean, String, DBParam...)
public Object parseValue(int type, String value)
DatabaseProvider
Parses the database-agnostic String
value relevant to the specified SQL
type in int
form (as defined by Types
and returns
the Java value which corresponds. This method is completely database-agnostic, as are
all of all of its delegate methods.
WARNING: This method is being considered for removal to another
class (perhaps TypeManager
?) as it is not a database-specific function and thus
confuses the purpose of this class. Do not rely upon it heavily. (better yet, don't rely on it
at all from external code. It's not designed to be part of the public API)
parseValue
in class DatabaseProvider
type
- The JDBC integer type of the database field against which to parse the
value.value
- The database-agnostic String value to parse into a proper Java object
with respect to the specified SQL type.
public ResultSet getTables(Connection conn) throws SQLException
DatabaseProvider
Returns a result set of all of the tables (and associated
meta) in the database. The fields of the result set must
correspond with those specified in the
DatabaseMetaData#getTables(String, String, String, String[])
method. In fact, the default implementation meerly calls
this method passing (null, null, "", null)
.
For databases (such as PostgreSQL) where this is unsuitable,
different parameters can be specified to the getTables
method in the override, or an entirely new implementation
written, as long as the result set corresponds in fields to
the JDBC spec.
Databases which do not support this function (such as Oracle)
should not throw an exception. Instead, they should
print a warning to stderr and return null
.
ActiveObjects will interpret a null
result set
as signifying no tables in the database, usually leading to a
complete recreation of the schema (raw migration).
getTables
in class DatabaseProvider
conn
- The connection to use in retrieving the database tables.
SQLException
DatabaseMetaData.getTables(String, String, String, String[])
public void dispose()
DatabaseProvider
dispose
in class DatabaseProvider
protected String renderQuerySelect(Query query, TableNameConverter converter, boolean count)
DatabaseProvider
Renders the SELECT portion of a given Query
instance in the
manner required by the database-specific SQL implementation. Usually,
this is as simple as "SELECT id FROM table"
or "SELECT DISTINCT
* FROM table"
. However, some databases require the limit and offset
parameters to be specified as part of the SELECT clause. For example,
on HSQLDB, a Query for the "id" field limited to 10 rows would render
SELECT like this: SELECT TOP 10 id FROM table
.
There is usually no need to call this method directly. Under normal
operations it functions as a delegate for DatabaseProvider.renderQuery(Query, TableNameConverter, boolean)
.
renderQuerySelect
in class DatabaseProvider
query
- The Query instance from which to determine the SELECT properties.converter
- The name converter to allow conversion of the query entity
interface into a proper table name.count
- Whether or not the query should be rendered as a SELECT COUNT(*)
.
protected String renderQueryLimit(Query query)
DatabaseProvider
Renders the LIMIT portion of the query in the database-specific SQL
dialect. There is wide variety in database implementations of this
particular SQL clause. In fact, many database do not support it at all.
If the database in question does not support LIMIT, this method should
be overridden to return an empty String. For such databases, LIMIT
should be implemented by overriding DatabaseProvider.setQueryResultSetProperties(ResultSet, Query)
and DatabaseProvider.setQueryStatementProperties(Statement, Query)
.
An example return value: " LIMIT 10,2"
There is usually no need to call this method directly. Under normal
operations it functions as a delegate for DatabaseProvider.renderQuery(Query, TableNameConverter, boolean)
.
renderQueryLimit
in class DatabaseProvider
query
- The Query instance from which to determine the LIMIT properties.
protected String renderAutoIncrement()
DatabaseProvider
Generates the DDL fragment required to specify an INTEGER field as
auto-incremented. For databases which do not support such flags (which
is just about every database exception MySQL), ""
is an
acceptable return value. This method should never return null
as it would cause the field rendering method to throw a NullPointerException
.
This method is abstract (as opposed to the other methods which are either defined against MySQL or simply empty) because of the vast differences in rendering auto-incremented fields across different databases. Also, it seemed like a terribly good idea at the time and I haven't found a compelling reason to change it.
renderAutoIncrement
in class DatabaseProvider
protected String getDateFormat()
DatabaseProvider
SimpleDateFormat
syntax. This format should include
the time down to the second (or even more precise, if allowed by
the database). The default implementation returns the format for
MySQL, which is: yyyy-MM-dd HH:mm:ss
getDateFormat
in class DatabaseProvider
protected String renderOnUpdate(DDLField field)
DatabaseProvider
Renders the appropriate field suffix to allow for the
OnUpdate
functionality. For most databases (read:
all but MySQL) this will return an empty String. This is
because few databases provide an implicit ON UPDATE syntax for
fields. As such, most databases will be compelled to return
an empty String and implement the functionality using triggers.
renderOnUpdate
in class DatabaseProvider
field
- The field for which the ON UPDATE clause should
be rendered.
protected String renderUnique()
DatabaseProvider
UNIQUE
constraint as defined by the
database-specific DDL syntax. This method is a delegate of other, more
complex methods such as DatabaseProvider.renderField(DDLField)
. The default
implementation just returns UNIQUE
. Implementations may
override this method to return an empty String
if the database
in question does not support the constraint.
renderUnique
in class DatabaseProvider
UNIQUE
.protected String renderConstraintsForTable(DDLTable table)
DatabaseProvider
renderConstraintsForTable
in class DatabaseProvider
table
- The database-agnostic DDL representation of the table
in question.
DatabaseProvider.renderForeignKey(DDLForeignKey)
protected String convertTypeToString(DatabaseType<?> type)
DatabaseProvider
DatabaseType#getDefaultName()
method. Subclass implementations should be sure to make a super
call in order to ensure that both default naming and future special
cases are handled appropriately.
convertTypeToString
in class DatabaseProvider
type
- The type instance to convert to a DDL string.
DatabaseType.getDefaultName()
protected boolean considerPrecision(DDLField field)
DatabaseProvider
Determines whether or not the database allows explicit precisions
for the field in question. This is to support databases such as
Derby which do not support precisions for certain types. By
default, this method returns true
.
More often than not, all that is required for this determination is the type. As such, the method signature may change in a future release.
considerPrecision
in class DatabaseProvider
field
- The field for which precision should/shouldn't be rendered.
true
if precision should be rendered, otherwise
false
.protected String renderValue(Object value)
DatabaseProvider
Calendar
,
Boolean
(which is always rendered as 0/1), functions,
null
and numbers. All other values are rendered (by
default) as 'value.toString()'
(the String value
enclosed within single quotes). Implementations are encouraged to
override this method as necessary.
renderValue
in class DatabaseProvider
value
- The Java instance to be rendered as a database literal.
DatabaseProvider.renderCalendar(Calendar)
,
DatabaseProvider.renderFunction(DatabaseFunction)
protected String renderAlterTableChangeColumnStatement(DDLTable table, DDLField oldField, DDLField field)
DatabaseProvider
DatabaseProvider.renderAlterTableChangeColumn(DDLTable, DDLField, DDLField)
method,
for which it is a primary delegate. The default implementation of this
method functions according to the MySQL specification.
renderAlterTableChangeColumnStatement
in class DatabaseProvider
table
- The table containing the column to change.oldField
- The old column definition.field
- The new column definition (defining the resultant DDL).
DatabaseProvider.renderField(DDLField)
protected String renderAlterTableDropKey(DDLForeignKey key)
DatabaseProvider
null
value returned. This method assumes that the
DatabaseProvider.renderForeignKey(DDLForeignKey)
method properly names
the foreign key according to the DDLForeignKey.getFKName()
method.
renderAlterTableDropKey
in class DatabaseProvider
key
- The foreign key to be removed. As this instance contains
all necessary data (such as domestic table, field, etc), no
additional parameters are required.
null
.protected String renderDropIndex(DDLIndex index)
DatabaseProvider
null
returned.
renderDropIndex
in class DatabaseProvider
index
- The index to drop. This single instance contains all
of the data necessary to drop the index, thus no separate
parameters (such as a DDLTable
) are required.
null
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |