|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.java.ao.DatabaseProvider
public abstract class DatabaseProvider
The superclass parent of all DatabaseProvider
implementations. Various implementations allow for an abstraction
around database-specific functionality (such as DDL). DatabaseProvider(s)
also handle the creation of new Connection
instances and
fully encapsulate the raw JDBC driver. Any database-specific
code should be placed in the database provider, rather than embedded
within the API logic.
This superclass contains a base-line, default implementation of most database-specific methods, thus requiring a minimum of work to implement a new database provider. For the sake of sanity (read: mine), this base-line implementation is basically specific to MySQL. Thus any DatabaseProvider implementations are really specifying the differences between the database in question and MySQL. To fully utilize the default implementations provided in this class, this fact should be kept in mind.
This class also handles the implementation details required to ensure
that only one active Connection
instance is available per thread. This is
in fact a very basic (and naive) form of connection pooling. It should
not be relied upon for performance reasons. Instead, a third-party
connection pool should be available in the classpath, enabling the use of
one of the PoolProvider
implementations. The purpose of the
thread-locked connection pooling in this class is to satisfy transactions
with external SQL statements.
Constructor Summary | |
---|---|
protected |
DatabaseProvider(String uri,
String username,
String password)
The base constructor for DatabaseProvider . |
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. |
|
Connection |
getConnection()
Retrieves a JDBC Connection instance which corresponds
to the database represented by the provider instance. |
|
protected Connection |
getConnectionImpl()
Creates a new connection to the database prepresented by the provider instance. |
|
protected String |
getDateFormat()
Returns the database-specific TIMESTAMP text format as defined by the SimpleDateFormat syntax. |
|
abstract Class<? extends Driver> |
getDriverClass()
Returns the JDBC Driver class which corresponds to the database being abstracted. |
|
protected String |
getFunctionNameForField(DDLTable table,
DDLField field)
Retrieves the name of the function which corresponds to the field in question (if any). |
|
static DatabaseProvider |
getInstance(String uri,
String username,
String password)
Auto-magically retrieves the appropriate provider instance for the specified JDBC URI, passing it the given username and password. |
|
static DatabaseProvider |
getInstance(String uri,
String username,
String password,
boolean enablePooling)
Auto-magically retrieves the appropriate provider instance for the specified JDBC URI, passing it the given username and password. |
|
String |
getPassword()
Retrieves the password used to authenticate against the database. |
|
ResultSet |
getTables(Connection conn)
Returns a result set of all of the tables (and associated meta) in the database. |
|
protected String |
getTriggerNameForField(DDLTable table,
DDLField field)
Retrieves the name of the trigger which corresponds to the field in question (if any). |
|
String |
getURI()
Retrieves the JDBC URI in use by the provider to obtain connections when necessary. |
|
String |
getUsername()
Retrieves the username used to authenticate against 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. |
|
protected boolean |
isNumericType(int type)
Simple helper function used to determine of the specified JDBC type is representitive of a numeric type. |
|
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. |
|
void |
putNull(PreparedStatement stmt,
int index)
TODO |
|
String[] |
renderAction(DDLAction action)
Top level delegating method for the process of rendering a database-agnostic DDLAction into the database-specific DDL statement(s). |
|
protected String[] |
renderAlterTableAddColumn(DDLTable table,
DDLField field)
Generates the database-specific DDL statements required to add a column to an existing table. |
|
protected String |
renderAlterTableAddKey(DDLForeignKey key)
Generates the database-specific DDL statement required to add a foreign key to a table. |
|
protected String[] |
renderAlterTableChangeColumn(DDLTable table,
DDLField oldField,
DDLField field)
Generates the database-specific DDL statements required to change the given column from its old specification to the given DDL value. |
|
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[] |
renderAlterTableDropColumn(DDLTable table,
DDLField field)
Generates the database-specific DDL statements required to remove the specified column from the given table. |
|
protected String |
renderAlterTableDropKey(DDLForeignKey key)
Generates the database-specific DDL statement required to remove a foreign key from a table. |
|
protected String |
renderAppend()
Generates any database-specific options which must be appended to the end of a table definition. |
|
protected abstract String |
renderAutoIncrement()
Generates the DDL fragment required to specify an INTEGER field as auto-incremented. |
|
protected String |
renderCalendar(Calendar calendar)
Renders the provided Calendar instance as a TIMESTAMP literal
in the database-specific format. |
|
protected String |
renderConstraintsForTable(DDLTable table)
Renders the foreign key constraints in database-specific DDL for the table in question. |
|
protected String |
renderCreateIndex(DDLIndex index)
Generates the database-specific DDL statement required to create a new index. |
|
protected String[] |
renderDropFunctions(DDLTable table)
Generates the database-specific DDL statements required to drop all associated functions for the given table representation. |
|
protected String |
renderDropIndex(DDLIndex index)
Generates the database-specific DDL statement required to drop an index. |
|
protected String[] |
renderDropSequences(DDLTable table)
Generates the database-specific DDL statements required to drop all associated sequences for the given table representation. |
|
protected String |
renderDropTable(DDLTable table)
Generates the appropriate database-specific DDL statement to drop the specified table representation. |
|
protected String[] |
renderDropTriggers(DDLTable table)
Generates the database-specific DDL statements required to drop all associated triggers for the given table representation. |
|
protected String |
renderField(DDLField field)
Generates the database-specific DDL fragment required to render the field and its associated type. |
|
protected String |
renderFieldPrecision(DDLField field)
Renders the statement fragment for the given field representative of its precision only. |
|
protected String |
renderFieldType(DDLField field)
Renders the database-specific DDL type for the field in question. |
|
protected String |
renderForeignKey(DDLForeignKey key)
Renders the specified foreign key representation into the database-specific DDL. |
|
protected String |
renderFunction(DatabaseFunction func)
Renders the specified DatabaseFunction in its
database-specific form. |
|
protected String |
renderFunctionForField(DDLTable table,
DDLField field)
Renders the function which corresponds to the specified field, or null if none. |
|
protected String[] |
renderFunctions(DDLTable table)
Generates the database-specific DDL statements required to create all of the functions necessary for the given table. |
|
protected String |
renderOnUpdate(DDLField field)
Renders the appropriate field suffix to allow for the OnUpdate functionality. |
|
String |
renderQuery(Query query,
TableNameConverter converter,
boolean count)
Top level delegating method for rendering a database-agnostic Query object into its (potentially) database-specific
query statement. |
|
protected String |
renderQueryGroupBy(Query query)
Renders the GROUP BY portion of the query in the database-specific SQL dialect. |
|
protected String |
renderQueryJoins(Query query,
TableNameConverter converter)
Renders the JOIN portion of the query in the database-specific SQL dialect. |
|
protected String |
renderQueryLimit(Query query)
Renders the LIMIT portion of the query in the database-specific SQL dialect. |
|
protected String |
renderQueryOrderBy(Query query)
Renders the ORDER BY 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 |
renderQueryWhere(Query query)
Renders the WHERE portion of the query in the database-specific SQL dialect. |
|
protected String[] |
renderSequences(DDLTable table)
Generates the database-specific DDL statements required to create all of the sequences necessary for the given table. |
|
protected String |
renderTable(DDLTable table)
Renders the specified table representation into the corresponding database-specific DDL statement. |
|
protected String |
renderTriggerForField(DDLTable table,
DDLField field)
Renders the trigger which corresponds to the specified field, or null if none. |
|
protected String[] |
renderTriggers(DDLTable table)
Generates the database-specific DDL statements required to create all of the triggers necessary for the given table. |
|
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. |
|
protected void |
setPostConnectionProperties(Connection conn)
Called to make any post-creation modifications to a new Connection instance. |
|
void |
setQueryResultSetProperties(ResultSet res,
Query query)
Allows the provider to set database-specific options on a ResultSet instance prior to its use by the library. |
|
void |
setQueryStatementProperties(Statement stmt,
Query query)
Allows the provider to set database-specific options on a Statement instance prior to its usage in a SELECT
query. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected DatabaseProvider(String uri, String username, String password)
The base constructor for DatabaseProvider
.
Initializes the JDBC uri, username and password values as specified.
Subclasses should implement a public constructor of this form, however it is not mandatory.
uri
- The JDBC URI which corresponds to the database being abstracted.username
- The database username (note: for implementations which
do not make use of this field, null
is permitted).password
- The database password (note: for implementations which
do not make use of this field, null
is permitted).Method Detail |
---|
public abstract Class<? extends Driver> getDriverClass() throws ClassNotFoundException
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).
Driver
implementation which corresponds to the
relevant database.
ClassNotFoundException
protected abstract String renderAutoIncrement()
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.
public String[] renderAction(DDLAction action)
DDLAction
into the database-specific DDL statement(s). It is
doubtful that any implementations will have to override this method as the
default implementation is database-agnostic.
action
- The database-agnostic action to render.
renderTable(DDLTable)
,
renderFunctions(DDLTable)
,
renderTriggers(DDLTable)
,
renderSequences(DDLTable)
,
renderDropTriggers(DDLTable)
,
renderDropFunctions(DDLTable)
,
renderDropSequences(DDLTable)
,
renderDropTable(DDLTable)
,
renderAlterTableAddColumn(DDLTable, DDLField)
,
renderAlterTableChangeColumn(DDLTable, DDLField, DDLField)
,
renderAlterTableDropColumn(DDLTable, DDLField)
,
renderAlterTableAddKey(DDLForeignKey)
,
renderAlterTableDropKey(DDLForeignKey)
public String renderQuery(Query query, TableNameConverter converter, boolean count)
Top level delegating method for rendering a database-agnostic
Query
object into its (potentially) database-specific
query statement. This method invokes the various renderQuery*
methods to construct its output, thus it is doubtful that any subclasses
will have to override it. Rather, one of the delegate methods
should be considered.
An example of a database-specific query rendering would be the
following Query
:
Query.select().from(Person.class).limit(10)
On MySQL, this would render to SELECT id FROM people LIMIT 10
However, on SQL Server, this same Query would render as
SELECT TOP 10 id FROM people
query
- The database-agnostic Query object to be rendered in a
potentially database-specific way.converter
- Used to convert Entity
classes into table names.count
- If true
, render the Query as a SELECT COUNT(*)
rather than a standard field-data query.
renderQuerySelect(Query, TableNameConverter, boolean)
,
renderQueryJoins(Query, TableNameConverter)
,
renderQueryWhere(Query)
,
renderQueryGroupBy(Query)
,
renderQueryOrderBy(Query)
,
renderQueryLimit(Query)
public 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. 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)
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 void setQueryStatementProperties(Statement stmt, Query query) throws SQLException
Allows the provider to set database-specific options on a
Statement
instance prior to its usage in a SELECT
query. This is to allow things like emulation of the
LIMIT feature on databases which don't support it within
the SQL implementation.
This method is only called on SELECTs.
stmt
- The instance against which the properties
should be set.query
- The query which is being executed against
the statement instance.
SQLException
public void setQueryResultSetProperties(ResultSet res, Query query) throws SQLException
ResultSet
instance prior to its use by the library.
This allows for features such as row offsetting even on
databases that don't support it (such as Oracle, Derby,
etc).
res
- The ResultSet
to modify.query
- The query instance which was run to produce
the result set.
SQLException
public ResultSet getTables(Connection conn) throws SQLException
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).
conn
- The connection to use in retrieving the database tables.
SQLException
DatabaseMetaData.getTables(String, String, String, String[])
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. 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 renderQuery(Query, TableNameConverter, boolean)
.
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 renderQueryJoins(Query query, TableNameConverter converter)
Renders the JOIN portion of the query in the database-specific SQL dialect. Very few databases deviate from the standard in this matter, thus the default implementation is usually sufficient.
An example return value: " JOIN table1 ON table.id = table1.value"
There is usually no need to call this method directly. Under normal
operations it functions as a delegate for renderQuery(Query, TableNameConverter, boolean)
.
query
- The Query instance from which to determine the JOIN properties.converter
- The name converter to allow conversion of the query entity
interface into a proper table name.
protected String renderQueryWhere(Query query)
Renders the WHERE portion of the query in the database-specific SQL dialect. Very few databases deviate from the standard in this matter, thus the default implementation is usually sufficient.
An example return value: " WHERE name = ? OR age < 20"
There is usually no need to call this method directly. Under normal
operations it functions as a delegate for renderQuery(Query, TableNameConverter, boolean)
.
query
- The Query instance from which to determine the WHERE properties.
protected String renderQueryGroupBy(Query query)
Renders the GROUP BY portion of the query in the database-specific SQL dialect. Very few databases deviate from the standard in this matter, thus the default implementation is usually sufficient.
An example return value: " GROUP BY name"
There is usually no need to call this method directly. Under normal
operations it functions as a delegate for renderQuery(Query, TableNameConverter, boolean)
.
query
- The Query instance from which to determine the GROUP BY properties.
protected String renderQueryOrderBy(Query query)
Renders the ORDER BY portion of the query in the database-specific SQL dialect. Very few databases deviate from the standard in this matter, thus the default implementation is usually sufficient.
An example return value: " ORDER BY name ASC"
There is usually no need to call this method directly. Under normal
operations it functions as a delegate for renderQuery(Query, TableNameConverter, boolean)
.
query
- The Query instance from which to determine the ORDER BY properties.
protected String renderQueryLimit(Query query)
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 setQueryResultSetProperties(ResultSet, Query)
and 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 renderQuery(Query, TableNameConverter, boolean)
.
query
- The Query instance from which to determine the LIMIT properties.
public String getURI()
public String getUsername()
public String getPassword()
public final Connection getConnection() throws SQLException
Retrieves a JDBC Connection
instance which corresponds
to the database represented by the provider instance. This Connection
can be used to execute arbitrary JDBC operations against the database.
Also, this is the method used by the whole of ActiveObjects itself to
get database connections when required.
All Connection
instances are pooled internally by thread.
Thus, there is never more than one connection per thread. This is
necessary to allow arbitrary JDBC operations within a transaction
without breaking transaction integrity. Developers using this method
should bear this fact in mind and consider the Connection
instance immutable. The only exception is if one is absolutely
certain that the JDBC code in question is not being executed within
a transaction.
Despite the fact that there is only a single connection per thread,
the Connection
instances returned from this method should
still be treated as bona fide JDBC connections. They can and
should be closed when their usage is complete. This is
especially important when actual connection pooling is in use and
non-disposal of connections can lead to a crash as the connection
pool runs out of resources. The developer need not concern themselves
with the single-connection-per-thread issue when closing the connection
as the call to close()
will be intercepted and ignored
if necessary.
Due to the fact that this method must implement some thread-specific
operations, it is declared final
and thus is not
overridable in subclasses. Database providers which need to override
the connection fetching mechanism (such as pool providers) should
instead override the getConnectionImpl()
method.
null
if the driver could not be loaded.
SQLException
protected Connection getConnectionImpl() throws SQLException
Creates a new connection to the database prepresented by the
provider instance. This method should not attempt to do any
caching of any kind (unless implemented by a connection pool
library). Prior to creating the database connection, this
method makes a call to getDriverClass()
to ensure that
the JDBC driver has been loaded. The return value is not
checked for validity.
This method is never called directly. Instead, the
getConnection()
method should be used.
null
if the driver could not be loaded.
SQLException
public void dispose()
protected void setPostConnectionProperties(Connection conn) throws SQLException
Connection
instance. This is used for databases
such as Derby which require the schema to be set after
the connection is created.
conn
- The connection to modify according to the database
requirements.
SQLException
protected String renderConstraintsForTable(DDLTable table)
table
- The database-agnostic DDL representation of the table
in question.
renderForeignKey(DDLForeignKey)
protected String renderForeignKey(DDLForeignKey key)
DDLForeignKey#getFKName()
value otherwise migrations will no longer function appropriately.
key
- The database-agnostic foreign key representation.
protected String convertTypeToString(DatabaseType<?> type)
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.
type
- The type instance to convert to a DDL string.
DatabaseType.getDefaultName()
protected String renderTable(DDLTable table)
DatabaseProvider
methods for functions such as
field rendering, foreign key rendering, etc.
table
- The database-agnostic table representation.
protected String renderDropTable(DDLTable table)
"DROP TABLE tablename"
. This is suitable
for every database that I am aware of. Any dependant database
objects (such as triggers, functions, etc) must be rendered in
one of the other delegate methods (such as renderDropTriggers(DDLTable)
).
table
- The table representation which is to be dropped.
protected String[] renderDropFunctions(DDLTable table)
table
- The table representation against which all functions which
correspond (directly or indirectly) must be dropped.
protected String[] renderDropTriggers(DDLTable table)
@OnUpdate
function to be implemented using triggers
explicitly (rather than the implicit MySQL syntax). For such
databases, some tables will thus have triggers which are associated
directly with the table. It is these triggers which must be
dropped prior to the dropping of the table itself. For databases
which associate functions with triggers (such as PostgreSQL), these
functions will be dropped using another delegate method and need
not be dealt with in this method's implementation.
table
- The table representation against which all triggers which
correspond (directly or indirectly) must be dropped.
protected String[] renderDropSequences(DDLTable table)
table
- The table representation against which all triggers which
correspond (directly or indirectly) must be dropped.
protected String[] renderFunctions(DDLTable table)
Generates the database-specific DDL statements required to create all of the functions necessary for the given table. For most databases, this will simply return an empty array. The functionality is required for databases such as PostgreSQL which require a function to be explicitly declared and associated when a trigger is created.
Most of the work for this functionality is delegated to the
renderFunctionForField(DDLTable, DDLField)
method.
table
- The table for which the functions must be generated.
protected String[] renderTriggers(DDLTable table)
Generates the database-specific DDL statements required to create
all of the triggers necessary for the given table. For MySQL, this
will likely return an empty array. The functionality is required
for databases which do not provide an implicit syntax for the
@OnUpdate
functionality. In MySQL, it is possible to
provide this functionality with the
field TIMESTAMP ON UPDATE CURRENT_DATE
style syntax.
This syntax is not common to all databases, hence triggers must be
used to provide the functionality.
Most of the work for this functionality is delegated to the
renderTriggerForField(DDLTable, DDLField)
method.
table
- The table for which the triggers must be generated.
protected String[] renderSequences(DDLTable table)
Generates the database-specific DDL statements required to create all of the sequences necessary for the given table. This is an Oracle specific method used for primary key management
table
- The table for which the triggers must be generated.
protected String[] renderAlterTableAddColumn(DDLTable table, DDLField field)
@OnUpdate
annotation, chances are there will be a trigger and possibly a
function along with the ALTER statement. These "extra"
functions are properly ordered and will only be appended if
their values are not null
. Because of this, very
few database providers will need to override this method.
table
- The table which should receive the new column.field
- The column to add to the specified table.
renderFunctionForField(DDLTable, DDLField)
,
renderTriggerForField(DDLTable, DDLField)
protected String[] renderAlterTableChangeColumn(DDLTable table, DDLField oldField, DDLField field)
Generates the database-specific DDL statements required to change the given column from its old specification to the given DDL value. This method will also generate the appropriate statements to remove old triggers and functions, as well as add new ones according to the requirements of the new field definition.
The default implementation of this method functions in the manner specified by the MySQL database. Some databases will have to perform more complicated actions (such as dropping and re-adding the field) in order to satesfy the same use-case. Such databases should print a warning to stderr to ensure that the end-developer is aware of such restrictions.
Thus, the specification for this method allows for data loss. Nevertheless, if the database supplies a mechanism to accomplish the task without data loss, it should be applied.
For maximum flexibility, the default implementation of this method
only deals with the dropping and addition of functions and triggers.
The actual generation of the ALTER TABLE statement is done in the
renderAlterTableChangeColumnStatement(DDLTable, DDLField, DDLField)
method.
table
- The table containing the column to change.oldField
- The old column definition.field
- The new column definition (defining the resultant DDL).
getTriggerNameForField(DDLTable, DDLField)
,
getFunctionNameForField(DDLTable, DDLField)
,
renderFunctionForField(DDLTable, DDLField)
,
renderTriggerForField(DDLTable, DDLField)
protected String renderAlterTableChangeColumnStatement(DDLTable table, DDLField oldField, DDLField field)
renderAlterTableChangeColumn(DDLTable, DDLField, DDLField)
method,
for which it is a primary delegate. The default implementation of this
method functions according to the MySQL specification.
table
- The table containing the column to change.oldField
- The old column definition.field
- The new column definition (defining the resultant DDL).
renderField(DDLField)
protected String[] renderAlterTableDropColumn(DDLTable table, DDLField field)
table
- The table from which to drop the column.field
- The column definition to remove from the table.
getTriggerNameForField(DDLTable, DDLField)
,
getFunctionNameForField(DDLTable, DDLField)
protected String renderAlterTableAddKey(DDLForeignKey key)
null
value returned.
key
- The foreign key to be added. As this instance contains
all necessary data (such as domestic table, field, etc), no
additional parameters are required.
null
.renderForeignKey(DDLForeignKey)
protected String renderAlterTableDropKey(DDLForeignKey key)
null
value returned. This method assumes that the
renderForeignKey(DDLForeignKey)
method properly names
the foreign key according to the DDLForeignKey.getFKName()
method.
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 renderCreateIndex(DDLIndex index)
null
returned.
index
- The index to create. This single instance contains all
of the data necessary to create the index, thus no separate
parameters (such as a DDLTable
) are required.
null
.protected String renderDropIndex(DDLIndex index)
null
returned.
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
.protected String renderAppend()
Generates any database-specific options which must be appended to the end of a table definition. The only database I am aware of which requires this is MySQL. For example:
CREATE TABLE test ( id INTEGER NOT NULL AUTO_INCREMENT, name VARCHAR(45), PRIMARY KEY(id) ) ENGINE=InnoDB;
The "ENGINE=InnoDB
" clause is what is returned by
this method. The default implementation simply returns
null
, signifying that no append should be rendered.
null
protected String renderField(DDLField field)
Generates the database-specific DDL fragment required to render the
field and its associated type. This includes all field attributes,
such as @NotNull
, @AutoIncrement
(if
supported by the database at the field level) and so on. Sample
return value:
name VARCHAR(255) DEFAULT "Skye" NOT NULL
Certain databases don't allow defined precision for certain types
(such as Derby and INTEGER). The logic for whether or not to render
precision should not be within this method, but delegated to the
considerPrecision(DDLField)
method.
Almost all functionality within this method is delegated to other methods within the implementation. As such, it is almost never necessary to override this method directly. An exception to this would be a database like PostgreSQL which requires a different type for auto-incremented fields.
field
- The field to be rendered.
protected String renderFieldPrecision(DDLField field)
Renders the statement fragment for the given field representative of its precision only. Consider the following statement:
ALTER TABLE ADD COLUMN name VARCHAR(255)
In this statement, the bit which is rendered by this method is the
"(255)
" (without quotes). This is intended to allow
maximum flexibility in field type rendering (as required by PostgreSQL
and others which sometimes render types separately from the rest of
the field info). The default implementation should suffice for every
conceivable database. Any sort of odd functionality relating to
type precision rendering should be handled in the considerPrecision(DDLField)
method if possible.
field
- The field for which the precision must be rendered.
protected String renderValue(Object value)
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.
value
- The Java instance to be rendered as a database literal.
renderCalendar(Calendar)
,
renderFunction(DatabaseFunction)
protected String renderCalendar(Calendar calendar)
Calendar
instance as a TIMESTAMP literal
in the database-specific format. The return value should not
be enclosed within quotes, as this is accomplished within other
functions when rendering is required. This method is actually a
boiler-plate usage of the SimpleDateFormat
class, using the
date format defined within the getDateFormat()
method.
calendar
- The time instance to be rendered.
protected String renderUnique()
UNIQUE
constraint as defined by the
database-specific DDL syntax. This method is a delegate of other, more
complex methods such as 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.
UNIQUE
.protected String getDateFormat()
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
protected String renderFieldType(DDLField field)
convertTypeToString(DatabaseType)
method, passing the field type. Thus, it is rarely necessary
(if ever) to override this method. It may be deprecated in a
future release.
field
- The field which contains the type to be rendered.
protected String renderFunction(DatabaseFunction func)
Renders the specified DatabaseFunction
in its
database-specific form. For example, for MySQL the
CURRENT_DATE
enum value would be rendered as
"CURRENT_DATE
" (without the quotes). For functions
which do not have a database equivalent, a default literal value
of the appropriate type should be returned. For example, if MySQL
did not define either a CURRENT_DATE or a CURRENT_TIMESTAMP
function, the appropriate return value for both functions would
be '0000-00-00 00:00:00'
(including the quotes).
This is to prevent migrations from failing even in cases where
non-standard functions are used.
As of 1.0, no unconventional functions are allowed by the
DatabaseFunction
enum, thus no database should have any
problems with any allowed functions.
func
- The abstract function to be rendered.
protected String renderOnUpdate(DDLField field)
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.
field
- The field for which the ON UPDATE clause should
be rendered.
protected boolean considerPrecision(DDLField field)
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.
field
- The field for which precision should/shouldn't be rendered.
true
if precision should be rendered, otherwise
false
.protected String getTriggerNameForField(DDLTable table, DDLField field)
null
should be returned.
This function is to allow for databases which require the use of
triggers on a field to allow for certain functionality (like
ON UPDATE). The default implementation returns null
.
table
- The table which contains the field for which a trigger
may or may not exist.field
- The field for which a previous migration may have
created a trigger.
null
if none.renderTriggerForField(DDLTable, DDLField)
protected String renderTriggerForField(DDLTable table, DDLField field)
null
if none. This is to allow for databases which
require the use of triggers to provide functionality such as ON
UPDATE. The default implementation returns null
.
table
- The table containing the field for which a trigger
may need to be rendered.field
- The field for which the trigger should be rendered,
if any.
null
.getTriggerNameForField(DDLTable, DDLField)
protected String getFunctionNameForField(DDLTable table, DDLField field)
null
should be returned.
This method is to allow for databases which require the use of
explicitly created functions which correspond to triggers (e.g.
PostgreSQL). Few providers will need to override the default
implementation of this method, which returns null
.
table
- The table which contains the field for which a function
may or may not exist.field
- The field for which a previous migration may have
created a function.
null
if none.protected String renderFunctionForField(DDLTable table, DDLField field)
null
if none. This is to allow for databases which
require the use of triggers and explicitly created functions to
provide functionality such as ON UPDATE (e.g. PostgreSQL). The
default implementation returns null
.
table
- The table containing the field for which a function
may need to be rendered.field
- The field for which the function should be rendered,
if any.
null
.getFunctionNameForField(DDLTable, DDLField)
public <T> T insertReturningKey(Connection conn, Class<T> pkType, String pkField, boolean pkIdentity, String table, DBParam... params) throws SQLException
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, 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 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 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).
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.executeInsertReturningKey(Connection, Class, String, String, DBParam...)
protected <T> T executeInsertReturningKey(Connection conn, Class<T> pkType, String pkField, String sql, DBParam... params) throws SQLException
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 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 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.
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.insertReturningKey(Connection, Class, String, boolean, String, DBParam...)
public void putNull(PreparedStatement stmt, int index) throws SQLException
SQLException
protected boolean isNumericType(int type)
Number
. The default implementation
should be suitable for every conceivable use-case.
type
- The JDBC type which is to be tested.
true
if the specified type represents a numeric
type, otherwise false
.public static final DatabaseProvider getInstance(String uri, String username, String password)
getInstance(String, String, String, boolean)
, passing true
to enable auto-magical connection pool configuratoin by default.
uri
- The JDBC URI for which a provider must be obtained.username
- The database username (note: for implementations which
do not make use of this field, null
is permitted).password
- The database password (note: for implementations which
do not make use of this field, null
is permitted).
uri
.public static final DatabaseProvider getInstance(String uri, String username, String password, boolean enablePooling)
Auto-magically retrieves the appropriate provider instance for the
specified JDBC URI, passing it the given username and password. Depending
on the value of the enablePooling
parameter, a connection
pool library may also be auto-magically selected based on the CLASSPATH
and the appropriate PoolProvider
implementation returned, delegating
to the actual requested provider. If no pool provider can be located, the
raw provider is returned (unpooled), irregardless of the enablePooling
parameter. If no database provider can be found for the given JDBC URI
prefix, a RuntimeException
will be thrown. This should probably
be changed to something a little less drastic, like returning null
.
Technically speaking, this method doesn't perform the actual logic
to find the database and/or pool providers. Both searches are delegated
to the SupportedDBProvider
and SupportedPoolProvider
enums,
respectively. The exception to this is that the convention for determining
whether or not a pool provider is actually availalble is defined
here. The convention imposed is that all pool providers contained within
the SupportedPoolProvider
enum must define a static isAvailable
method which tests for the existance of some critical class on the CLASSPATH.
If this method is not found, the provider will be assumed to be unfound and
the search will continue. This convention isn't required for third-party
pool providers, but it is to be enforced for any pool providers supplied by
ActiveObjects itself.
uri
- The JDBC URI for which a provider must be obtained.username
- The database username (note: for implementations which
do not make use of this field, null
is permitted).password
- The database password (note: for implementations which
do not make use of this field, null
is permitted).enablePooling
- A flag indicating whether or not connection pooling
should be enabled (if possible). Note that this flag is ignored if
no connection pool library could be found on the CLASSPATH.
uri
.
RuntimeException
- If no database provider is found for the
specified URI prefix, or if the provider class could not be instantiated.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |