net.java.ao.db

Class OracleDatabaseProvider

java.lang.Object

net.java.ao.DatabaseProvider

net.java.ao.db.OracleDatabaseProvider

public final class OracleDatabaseProvider
extends DatabaseProvider

Author:

Daniel Spiewak

Nested Class Summary

Nested classes/interfaces inherited from class net.java.ao.DatabaseProvider

DatabaseProvider.RenderFieldOptions, DatabaseProvider.SqlListener

Field Summary

Fields

Modifier and Type	Field and Description
static Set<String>	RESERVED_WORDS

Fields inherited from class net.java.ao.DatabaseProvider

logger, sqlLogger, typeManager

Constructor Summary

Constructors

Constructor and Description
OracleDatabaseProvider(DisposableDataSource dataSource)
OracleDatabaseProvider(DisposableDataSource dataSource, String schema)

Method Summary

Methods

Modifier and Type	Method and Description
protected <T extends RawEntity<K>,K> K	executeInsertReturningKey(EntityManager manager, Connection conn, Class<T> entityType, Class<K> 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.
ResultSet	getImportedKeys(Connection connection, String tableName)
ResultSet	getIndexes(Connection conn, String tableName)
protected int	getMaxIDLength() Returns the maximum length for any identifier in the underlying database.
protected Set<String>	getReservedWords() Retrieves the set of all reserved words for the underlying database.
String	getSchema()
ResultSet	getSequences(Connection conn)
ResultSet	getTables(Connection conn) Returns a result set of all of the tables (and associated meta) in the database.
void	handleUpdateError(String sql, SQLException e) Tells whether this exception should be ignored when running an updated statement.
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	putBoolean(PreparedStatement stmt, int index, boolean value) Stors an SQL BOOLEAN value in the database.
void	putNull(PreparedStatement stmt, int index) Stores an SQL NULL value in the database.
protected Iterable<SQLAction>	renderAccessoriesForField(NameConverters nameConverters, DDLTable table, DDLField field) Generates database-specific DDL statements required to create any functions, sequences, or triggers required for the given field.
protected SQLAction	renderAlterTableAddColumnStatement(NameConverters nameConverters, DDLTable table, DDLField field) Generates the database-specific DDL statement for adding a column, but not including any corresponding sequences, triggers, etc.
protected Iterable<SQLAction>	renderAlterTableChangeColumn(NameConverters nameConverters, 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 SQLAction	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 Iterable<SQLAction>	renderDropAccessoriesForField(NameConverters nameConverters, DDLTable table, DDLField field) Generates database-specific DDL statements required to drop any functions, sequences, or triggers associated with the given field.
protected SQLAction	renderDropIndex(IndexNameConverter indexNameConverter, DDLIndex index) Generates the database-specific DDL statement required to drop an index.
protected SQLAction	renderDropTableStatement(DDLTable table) Generates the appropriate database-specific DDL statement to drop the specified table representation.
protected String	renderQueryLimit(Query query) Renders the LIMIT portion of the query in the database-specific SQL dialect.
protected String	renderUnique(UniqueNameConverter uniqueNameConverter, DDLTable table, DDLField field) Renders the UNIQUE constraint as defined by the database-specific DDL syntax.
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.
protected boolean	shouldQuoteID(String id) Determines whether or not the specified identifier should be quoted before transmission to the underlying database.

Methods inherited from class net.java.ao.DatabaseProvider

_getFunctionNameForField, _getTriggerNameForField, _renderDropFunctionForField, _renderDropSequenceForField, _renderDropTriggerForField, _renderFunctionForField, _renderSequenceForField, _renderTriggerForField, addSqlListener, commitTransaction, convertTypeToString, dispose, executeUpdate, executeUpdateForAction, executeUpdatesForActions, findForeignKeysForField, getConnection, getTypeManager, handleBlob, hasIndex, insertReturningKey, isCaseSensitive, isNumericType, isSchemaNotEmpty, onSql, preparedStatement, preparedStatement, preparedStatement, processID, processOnClause, processWhereClause, querySelectFields, queryTableName, quote, removeSqlListener, renderAccessories, renderAction, renderAlterTableAddColumn, renderAlterTableAddKey, renderAlterTableChangeColumnStatement, renderAlterTableDropColumn, renderAlterTableDropColumnStatement, renderAppend, renderConstraintsForTable, renderCreateIndex, renderDate, renderDropAccessories, renderField, renderFieldDefault, renderFieldOptionsInAlterColumn, renderFields, renderFieldType, renderForeignKey, renderInsert, renderPrimaryKey, renderQuery, renderQueryGroupBy, renderQueryJoins, renderQueryOrderBy, renderQuerySelect, renderQueryWhere, renderTable, renderValue, rollbackTransaction, setPostConnectionProperties, shorten, startTransaction, withSchema

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESERVED_WORDS

public static final Set<String> RESERVED_WORDS

Constructor Detail

OracleDatabaseProvider

public OracleDatabaseProvider(DisposableDataSource dataSource)

OracleDatabaseProvider

public OracleDatabaseProvider(DisposableDataSource dataSource,
                      String schema)

Method Detail

getSchema

public String getSchema()

Overrides:

getSchema in class DatabaseProvider

setQueryStatementProperties

public void setQueryStatementProperties(Statement stmt,
                               Query query)
                                 throws SQLException

Description copied from class: DatabaseProvider

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.

Overrides:

setQueryStatementProperties in class DatabaseProvider

Parameters:

stmt - The instance against which the properties should be set.

query - The query which is being executed against the statement instance.

Throws:

SQLException

setQueryResultSetProperties

public void setQueryResultSetProperties(ResultSet res,
                               Query query)
                                 throws SQLException

Description copied from class: DatabaseProvider

Allows the provider to set database-specific options on a 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).

Overrides:

setQueryResultSetProperties in class DatabaseProvider

Parameters:

res - The ResultSet to modify.

query - The query instance which was run to produce the result set.

Throws:

SQLException

getTables

public ResultSet getTables(Connection conn)
                    throws SQLException

Description copied from class: 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 merely 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.

Overrides:

getTables in class DatabaseProvider

Parameters:

conn - The connection to use in retrieving the database tables.

Returns:

A result set of tables (and meta) corresponding in fields to the JDBC specification.

Throws:

SQLException

See Also:

DatabaseMetaData.getTables(String, String, String, String[])

getSequences

public ResultSet getSequences(Connection conn)
                       throws SQLException

Overrides:

getSequences in class DatabaseProvider

Throws:

SQLException

getIndexes

public ResultSet getIndexes(Connection conn,
                   String tableName)
                     throws SQLException

Overrides:

getIndexes in class DatabaseProvider

Throws:

SQLException

getImportedKeys

public ResultSet getImportedKeys(Connection connection,
                        String tableName)
                          throws SQLException

Overrides:

getImportedKeys in class DatabaseProvider

Throws:

SQLException

renderQueryLimit

protected String renderQueryLimit(Query query)

Description copied from class: 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).

Overrides:

renderQueryLimit in class DatabaseProvider

Parameters:

query - The Query instance from which to determine the LIMIT properties.

Returns:

The database-specific SQL rendering of the LIMIT portion of the query.

renderAutoIncrement

protected String renderAutoIncrement()

Description copied from class: 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.

Overrides:

renderAutoIncrement in class DatabaseProvider

parseValue

public Object parseValue(int type,
                String value)

Description copied from class: 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)

Overrides:

parseValue in class DatabaseProvider

Parameters:

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.

Returns:

A Java value which corresponds to the specified String.

renderUnique

protected String renderUnique(UniqueNameConverter uniqueNameConverter,
                  DDLTable table,
                  DDLField field)

Description copied from class: DatabaseProvider

Renders the UNIQUE constraint as defined by the database-specific DDL syntax. This method is a delegate of other, more complex methods such as DatabaseProvider.renderField(net.java.ao.schema.NameConverters, net.java.ao.schema.ddl.DDLTable, net.java.ao.schema.ddl.DDLField, net.java.ao.DatabaseProvider.RenderFieldOptions). 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.

Overrides:

renderUnique in class DatabaseProvider

Returns:

The database-specific rendering of UNIQUE.

getDateFormat

protected String getDateFormat()

Description copied from class: DatabaseProvider

Returns the database-specific TIMESTAMP text format as defined by the 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

Overrides:

getDateFormat in class DatabaseProvider

Returns:

The database-specific TIMESTAMP text format

renderAlterTableAddColumnStatement

protected SQLAction renderAlterTableAddColumnStatement(NameConverters nameConverters,
                                           DDLTable table,
                                           DDLField field)

Description copied from class: DatabaseProvider

Generates the database-specific DDL statement for adding a column, but not including any corresponding sequences, triggers, etc.

Overrides:

renderAlterTableAddColumnStatement in class DatabaseProvider

table - The table which should receive the new column.

field - The column to add to the specified table.

Returns:

A DDL statements to execute.

renderAlterTableChangeColumn

protected Iterable<SQLAction> renderAlterTableChangeColumn(NameConverters nameConverters,
                                               DDLTable table,
                                               DDLField oldField,
                                               DDLField field)

Description copied from class: DatabaseProvider

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 DatabaseProvider.renderAlterTableChangeColumnStatement(net.java.ao.schema.NameConverters, net.java.ao.schema.ddl.DDLTable, net.java.ao.schema.ddl.DDLField, net.java.ao.schema.ddl.DDLField, net.java.ao.DatabaseProvider.RenderFieldOptions) method.

Overrides:

renderAlterTableChangeColumn 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). @return An array of DDL statements to be executed.

See Also:

#getTriggerNameForField(net.java.ao.schema.TriggerNameConverter, net.java.ao.schema.ddl.DDLTable, net.java.ao.schema.ddl.DDLField), #getFunctionNameForField(net.java.ao.schema.TriggerNameConverter, net.java.ao.schema.ddl.DDLTable, net.java.ao.schema.ddl.DDLField), #renderFunctionForField(net.java.ao.schema.TriggerNameConverter, net.java.ao.schema.ddl.DDLTable, net.java.ao.schema.ddl.DDLField), #renderTriggerForField(net.java.ao.schema.TriggerNameConverter, net.java.ao.schema.SequenceNameConverter, net.java.ao.schema.ddl.DDLTable, net.java.ao.schema.ddl.DDLField)

renderAlterTableDropKey

protected SQLAction renderAlterTableDropKey(DDLForeignKey key)

Description copied from class: DatabaseProvider

Generates the database-specific DDL statement required to remove a foreign key from a table. For databases which do not support such a statement, a warning should be printed to stderr and a null value returned. This method assumes that the DatabaseProvider.renderForeignKey(DDLForeignKey) method properly names the foreign key according to the DDLForeignKey.getFKName() method.

Overrides:

renderAlterTableDropKey in class DatabaseProvider

Parameters:

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.

Returns:

A DDL statement to be executed, or null.

renderDropIndex

protected SQLAction renderDropIndex(IndexNameConverter indexNameConverter,
                        DDLIndex index)

Description copied from class: DatabaseProvider

Generates the database-specific DDL statement required to drop an index. The syntax for this operation is highly standardized and thus it is unlikely this method will be overridden. If the database in question does not support indexes, a warning should be printed to stderr and null returned.

Overrides:

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.

Returns:

A DDL statement to be executed, or null.

renderDropTableStatement

protected SQLAction renderDropTableStatement(DDLTable table)

Description copied from class: DatabaseProvider

Generates the appropriate database-specific DDL statement to drop the specified table representation. The default implementation is merely "DROP TABLE tablename". This is suitable for every database that I am aware of. Any dependent database objects (such as triggers, functions, etc) must be rendered in one of the other delegate methods (such as renderDropTriggers(DDLTable)).

Overrides:

renderDropTableStatement in class DatabaseProvider

Parameters:

table - The table representation which is to be dropped.

Returns:

A database-specific DDL statement which drops the specified table.

handleUpdateError

public void handleUpdateError(String sql,
                     SQLException e)
                       throws SQLException

Description copied from class: DatabaseProvider

Tells whether this exception should be ignored when running an updated statement. Typically, errors on dropping non-existing objects should be ignored.

Overrides:

handleUpdateError in class DatabaseProvider

e - the SQLException that occured.

Throws:

SQLException - throws the SQLException if it should not be ignored.

executeInsertReturningKey

protected <T extends RawEntity<K>,K> K executeInsertReturningKey(EntityManager manager,
                                                     Connection conn,
                                                     Class<T> entityType,
                                                     Class<K> pkType,
                                                     String pkField,
                                                     String sql,
                                                     DBParam... params)
                               throws SQLException

Description copied from class: 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 #insertReturningKey(EntityManager, 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.

Overrides:

executeInsertReturningKey in class DatabaseProvider

Parameters:

manager - The EntityManager which was used to dispatch the INSERT in question.

conn - The database connection to use in executing the INSERT statement.

entityType - The Java class of the entity.

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. @throws SQLException If the INSERT fails in the delegate method, or if any additional statements fail with an exception.

Throws:

SQLException

See Also:

#insertReturningKey(EntityManager, Connection, Class, String, boolean, String, DBParam...)

renderAccessoriesForField

protected Iterable<SQLAction> renderAccessoriesForField(NameConverters nameConverters,
                                            DDLTable table,
                                            DDLField field)

Description copied from class: DatabaseProvider

Generates database-specific DDL statements required to create any functions, sequences, or triggers required for the given field. Each returned SQLAction should have a corresponding undo action that deletes the corresponding function, sequence, or trigger. The default implementation returns an empty list.

Overrides:

renderAccessoriesForField in class DatabaseProvider

Returns:

an ordered list of SQLActions

renderDropAccessoriesForField

protected Iterable<SQLAction> renderDropAccessoriesForField(NameConverters nameConverters,
                                                DDLTable table,
                                                DDLField field)

Description copied from class: DatabaseProvider

Generates database-specific DDL statements required to drop any functions, sequences, or triggers associated with the given field. The default implementation returns an empty list.

Overrides:

renderDropAccessoriesForField in class DatabaseProvider

Returns:

an ordered list of SQLActions

shouldQuoteID

protected boolean shouldQuoteID(String id)

Description copied from class: DatabaseProvider

Determines whether or not the specified identifier should be quoted before transmission to the underlying database. The default implementation transforms the identifier into all-upper-case and checks the result against DatabaseProvider.getReservedWords(). Databases with more complicated rules regarding quoting should provide a custom implementation of this method.

Overrides:

shouldQuoteID in class DatabaseProvider

Parameters:

id - The identifier to check against the quoting rules.

Returns:

true if the specified identifier is invalid under the relevant quoting rules, otherwise false.

getMaxIDLength

protected int getMaxIDLength()

Description copied from class: DatabaseProvider

Returns the maximum length for any identifier in the underlying database. If the database defines different maximum lengths for different identifier types, the minimum value should be returned by this method. By default, this just returns Integer.MAX_VALUE.

Overrides:

getMaxIDLength in class DatabaseProvider

Returns:

The maximum identifier length for the database.

getReservedWords

protected Set<String> getReservedWords()

Description copied from class: DatabaseProvider

Retrieves the set of all reserved words for the underlying database. The set returns should be speculative, meaning that it should include any possible reserved words, not just those for a particular version. As an implementation guideline, the Set instance returned from this method should guarentee O(1) lookup times, otherwise ORM performance will suffer greatly.

Specified by:

getReservedWords in class DatabaseProvider

Returns:

A set of upper case reserved words specific to the database.

putNull

public void putNull(PreparedStatement stmt,
           int index)
             throws SQLException

Description copied from class: DatabaseProvider

Stores an SQL NULL value in the database. This method is required due to the fact that not all JDBC drivers handle NULLs in the same fashion. The default implementation calls PreparedStatement.setString(int, String), passing null as a value. Databases which require a different implementation (e.g. PostgreSQL) should override this method.

Overrides:

putNull in class DatabaseProvider

Parameters:

stmt - The statement in which to store the NULL value.

index - The index of the parameter which should be assigned NULL.

Throws:

SQLException

putBoolean

public void putBoolean(PreparedStatement stmt,
              int index,
              boolean value)
                throws SQLException

Description copied from class: DatabaseProvider

Stors an SQL BOOLEAN value in the database. Most databases handle differences in BOOLEAN semantics within their JDBC driver(s). However, some do not implement the PreparedStatement.setBoolean(int, boolean) method correctly. To work around this defect, any database providers for such databases should override this method to store boolean values in the relevant fashion.

Overrides:

putBoolean in class DatabaseProvider

Parameters:

stmt - The statement in which to store the BOOLEAN value.

index - The index of the parameter which should be assigned.

value - The value to be stored in the relevant field.

Throws:

SQLException