Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.java.ao.db
Class OracleDatabaseProvider

    java.lang.Object
      net.java.ao.DatabaseProvider
          net.java.ao.db.OracleDatabaseProvider

    public class OracleDatabaseProvider

extends DatabaseProvider

Author:
  Daniel Spiewak

Field Summary

Fields inherited from class net.java.ao.DatabaseProvider
`eventManager`

Constructor Summary
`OracleDatabaseProvider(DisposableDataSource dataSource)`

Method Summary
`protected String` | `convertTypeToString(DatabaseType<?> type)` Converts the specified type into the database-specific DDL String value.
`protected
`<T> T`
` | `executeInsertReturningKey(EntityManager manager, 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.
`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.
`ResultSet` | `getSequences(Connection conn)`
`ResultSet` | `getTables(Connection conn)` Returns a result set of all of the tables (and associated meta) in the database.
`void` | `putBoolean(PreparedStatement stmt, int index, boolean value)` Stors an SQL `BOOLEAN` value in the database.
`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[]` | `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` | `renderFieldPrecision(DDLField field)` Renders the statement fragment for the given field representative of its precision only.
`protected String` | `renderFunction(DatabaseFunction func)` Renders the specified `DatabaseFunction` in its database-specific form.
`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[]` | `renderSequences(DDLTable table)` Generates the database-specific DDL statements required to create all of the sequences necessary for the given table.
`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.
`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
`considerPrecision, dispose, getConnection, getEventManager, getFunctionNameForField, getTriggerNameForField, handleBlob, handleUpdateError, insertReturningKey, isCaseSensetive, isNumericType, parseValue, processID, processWhereClause, putNull, renderAction, renderAlterTableAddColumn, renderAlterTableAddKey, renderAlterTableChangeColumn, renderAlterTableDropColumn, renderAppend, renderCalendar, renderConstraintsForTable, renderCreateIndex, renderDropFunctions, renderDropIndex, renderField, renderFieldType, renderForeignKey, renderFunctionForField, renderFunctions, renderInsert, renderQuery, renderQueryGroupBy, renderQueryJoins, renderQueryOrderBy, renderQuerySelect, renderQueryWhere, renderTable, renderUnique, renderValue, setEventManager, setPostConnectionProperties`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### OracleDatabaseProvider

    public OracleDatabaseProvider(DisposableDataSource dataSource)

Method Detail

### 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`

### convertTypeToString

    protected String convertTypeToString(DatabaseType<?> type)

  Description copied from class: `DatabaseProvider`
  Converts the specified type into the database-specific DDL String value. By default, this delegates to the `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.

  Overrides:
    `convertTypeToString` in class `DatabaseProvider`
  Parameters:
    `type` - The type instance to convert to a DDL string.
  Returns:
    The database-specific DDL representation of the type (e.g. "VARCHAR").
  See Also:
    `DatabaseType.getDefaultName()`

### renderFieldPrecision

    protected String renderFieldPrecision(DDLField field)

  Description copied from class: `DatabaseProvider`

  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 `DatabaseProvider.considerPrecision(DDLField)` method if possible.

  Overrides:
    `renderFieldPrecision` in class `DatabaseProvider`
  Parameters:
    `field` - The field for which the precision must be rendered.
  Returns:
    A DDL fragment which will be concatenated into a statement later.

### 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`

### renderOnUpdate

    protected String renderOnUpdate(DDLField field)

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

  Overrides:
    `renderOnUpdate` in class `DatabaseProvider`
  Parameters:
    `field` - The field for which the ON UPDATE clause should be rendered.
  Returns:
    The database-specific ON UPDATE field clause.

### renderFunction

    protected String renderFunction(DatabaseFunction func)

  Description copied from class: `DatabaseProvider`

  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.

  Overrides:
    `renderFunction` in class `DatabaseProvider`
  Parameters:
    `func` - The abstract function to be rendered.
  Returns:
    The database-specific DDL representation of the function in question.

### 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

### renderTriggerForField

    protected String renderTriggerForField(DDLTable table,
                                           DDLField field)

  Description copied from class: `DatabaseProvider`
  Renders the trigger which corresponds to the specified field, or `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`.

  Overrides:
    `renderTriggerForField` in class `DatabaseProvider`
  Parameters:
    `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.
  Returns:
    A database-specific DDL statement creating a trigger for the field in question, or `null`.
  See Also:
    `DatabaseProvider.getTriggerNameForField(DDLTable, DDLField)`

### renderAlterTableChangeColumnStatement

    protected String renderAlterTableChangeColumnStatement(DDLTable table,
                                                           DDLField oldField,
                                                           DDLField field)

  Description copied from class: `DatabaseProvider`
  Generates the database-specific DDL statement only for altering a table and changing a column. This method must only generate a single statement as it does not need to concern itself with functions or triggers associated with the column. This method is only to be called as a delegate for the `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.

  Overrides:
    `renderAlterTableChangeColumnStatement` in class `DatabaseProvider`
  Parameters:
    `table` - The table containing the column to change.
    `oldField` - The old column definition.
    `field` - The new column definition (defining the resultant DDL).
  Returns:
    A single DDL statement which is to be executed.
  See Also:
    `DatabaseProvider.renderField(DDLField)`

### renderAlterTableDropKey

    protected String 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`.

### renderDropTable

    protected String renderDropTable(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 dependant database objects (such as triggers, functions, etc) must be rendered in one of the other delegate methods (such as `renderDropTriggers(DDLTable)`).

  Overrides:
    `renderDropTable` in class `DatabaseProvider`
  Parameters:
    `table` - The table representation which is to be dropped.
  Returns:
    A database-specific DDL statement which drops the specified table.

### executeInsertReturningKey

    protected <T> T executeInsertReturningKey(EntityManager manager,
                                              Connection conn,
                                              Class<T> 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 `DatabaseProvider.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.
    `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.
  See Also:
    `DatabaseProvider.insertReturningKey(EntityManager, Connection, Class, String, boolean, String, DBParam...)`

### renderTriggers

    protected String[] renderTriggers(DDLTable table)

  Description copied from class: `DatabaseProvider`

  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 `DatabaseProvider.renderTriggerForField(DDLTable, DDLField)` method.

  Overrides:
    `renderTriggers` in class `DatabaseProvider`
  Parameters:
    `table` - The table for which the triggers must be generated.
  Returns:
    An array of DDL statements to execute.

### renderDropTriggers

    protected String[] renderDropTriggers(DDLTable table)

  Description copied from class: `DatabaseProvider`
  Generates the database-specific DDL statements required to drop all associated triggers for the given table representation. The default implementation is to return an empty array. Most databases require the `@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.

  Overrides:
    `renderDropTriggers` in class `DatabaseProvider`
  Parameters:
    `table` - The table representation against which all triggers which correspond (directly or indirectly) must be dropped.
  Returns:
    An array of database-specific DDL statement(s) which drop the required triggers.

### renderDropSequences

    protected String[] renderDropSequences(DDLTable table)

  Description copied from class: `DatabaseProvider`
  Generates the database-specific DDL statements required to drop all associated sequences for the given table representation. The default implementation is to return an empty array. This is an Oracle specific method used for primary key management

  Overrides:
    `renderDropSequences` in class `DatabaseProvider`
  Parameters:
    `table` - The table representation against which all triggers which correspond (directly or indirectly) must be dropped.
  Returns:
    An array of database-specific DDL statement(s) which drop the required triggers.

### renderSequences

    protected String[] renderSequences(DDLTable table)

  Description copied from class: `DatabaseProvider`

  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

  Overrides:
    `renderSequences` in class `DatabaseProvider`
  Parameters:
    `table` - The table for which the triggers must be generated.
  Returns:
    An array of DDL statements to execute.

### 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.

### 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2007-2011. All Rights Reserved.