oracle.javatools.db
Interface Database

All Superinterfaces:

DBObjectProvider

All Known Subinterfaces:

JdbcDatabase, OracleDatabase, OracleDatabaseXE

All Known Implementing Classes:

AbstractDatabase, DDLDatabase, DictionaryDatabase

public interface Database
extends DBObjectProvider

Provides a interface for accessing a database. This extension of DBObjectProvider includes methods specific to a connection with a live database. A DBObjectProvider may connect to a different object store but a Database will always have an underlying java.sql.Connection object.

To retrieve a Database implementation for a given Connection use the DatabaseFactory.

Since:

9.0.2

See Also:

DBObjectProvider, DatabaseFactory

Field Summary

static long	FOUR_GIG Constant: size for four gigabytes
static java.lang.String	GENERIC_JDBC_DATABASE Type for a generic JDBC database.
static java.lang.String	PROVIDER_TYPE Provider type for all Databases (used by DBObjectProviderFactory.findOrCreateProvider(String,Object).
static java.lang.String	SOURCE_TYPE_BODY For source nodes with more than one type of source
static java.lang.String	SOURCE_TYPE_SPEC For source nodes with more than one type of source
static long	TWO_GIG Constant: size for two gigabytes

Fields inherited from interface oracle.javatools.db.DBObjectProvider

CREATE_PRIVILEDGE, DELETE_PRIVILEDGE, MODIFY_PRIVILEDGE, NEW_FROM_TEMPLATE_TYPE

Method Summary

boolean	canRestrictSchemaList() Whether this provider supports restricting the list of schemas to those with visible objects.
void	close() Closes the Database Connection (and the supplied JDBC Connection).
boolean	exists(java.lang.String type, java.lang.String schema, java.lang.String objectName) Checks for existance of a schema object named objectName.
java.sql.Connection	getConnection() Gets the JDBC connection associated with this database.
java.sql.Connection	getConnection(boolean reconnect) Gets the JDBC connection associated with this database.
java.lang.String	getConnectionName() Retrieves the name for the Connection associated with this Database in whichever connection store it is stored in.
java.lang.String	getConnectionStore() Retrieves the connection store the Connection associated with this Database is stored in.
java.lang.String	getDatabaseSource(java.lang.String objectType, Schema schema, java.lang.String objectName) Retrieves the source for an object in the database.
java.lang.String	getDatabaseSource(java.lang.String objectType, Schema schema, java.lang.String objectName, java.lang.String sourceType) Retrieves the source for an object in the database.
java.lang.String	getDatabaseType() Gets the type of database.
int	getDatabaseVersion() Gets the version of the database for the api implementation.
java.lang.String	getIdentifierQuoteString() Returns the String to use to quote SQL identifiers with
java.lang.String	getQualifiedName() Retrieves a qualified name containing the connection store and connection name.
java.lang.String	getUserName() Retrieves the username used to connect to the database
boolean	hasTransaction() Tests whether there is currently a "transaction" open on the underlying java.sql.Connection.
boolean	isConnectionAlive() Tests whether the connection underneath this Database is "alive" - i.e.
java.lang.Boolean	isConnectionClosed(java.sql.SQLException sqe) Tests whether the given SQLException (assumed to have come from the connection of this db) is the result of the connection being closed.
boolean	isObjectValid(java.lang.String objectType, java.lang.String schema, java.lang.String objectName) Determines whether the specified database object is in a valid state.
boolean	supportsDebugging() Whether this database instance supports JDWP debugging.
void	testSQLStatement(java.lang.String sql) Tests that the given SQL executes against the database.

Methods inherited from interface oracle.javatools.db.DBObjectProvider

addObjectListener, addObjectListener, addProviderListener, addProviderListener, canCreate, canDelete, createObject, createObjects, createSchema, deleteObject, deleteObjects, deleteSchema, getCascadeManager, getDataType, getDDLGenerator, getDefaultSchema, getDefaultTemplateForType, getDescriptor, getDiffEngine, getExternalName, getExternalName, getInternalName, getInternalName, getName, getObject, getObject, getObjectFactory, getObjectManager, getOrCreateDataType, getPropertyManager, getProviderIdentifier, getProviderType, getSchema, getTimestamp, getTimestamp, getUniqueName, hasObjectPrivilege, hasPriviledge, hasSystemPrivilege, isEditable, isNewFromTemplateType, isValidName, isValidName, listObjects, listObjects, listObjects, listObjects, listObjects, listObjectTypes, listSchemas, listSchemas, listSupportedDataTypes, quoteIdentifier, removeObjectListener, removeProviderListener, removeProviderListener, setDefaultTemplateForType, supportsObjectType, undeleteObject, undeleteObjects, updateObject, updateObjects, updateObjects, updateSchema, validateName, validateName, validateObject, validateObject, validateObject, validateObject, validateObjectProperty, validateObjectProperty, validateObjectProperty, validateObjectProperty, validateSchema, validateSchema, validateUniqueName

Field Detail

PROVIDER_TYPE

static final java.lang.String PROVIDER_TYPE

Provider type for all Databases (used by DBObjectProviderFactory.findOrCreateProvider(String,Object).

See Also:

Constant Field Values

GENERIC_JDBC_DATABASE

static final java.lang.String GENERIC_JDBC_DATABASE

Type for a generic JDBC database.

See Also:

getDatabaseType(), Constant Field Values

TWO_GIG

static final long TWO_GIG

Constant: size for two gigabytes

See Also:

Constant Field Values

FOUR_GIG

static final long FOUR_GIG

Constant: size for four gigabytes

See Also:

Constant Field Values

SOURCE_TYPE_SPEC

static final java.lang.String SOURCE_TYPE_SPEC

For source nodes with more than one type of source

See Also:

Constant Field Values

SOURCE_TYPE_BODY

static final java.lang.String SOURCE_TYPE_BODY

For source nodes with more than one type of source

See Also:

Constant Field Values

Method Detail

getConnection

java.sql.Connection getConnection()

Gets the JDBC connection associated with this database. If the Connection is closed the Database will silently try and reconnect. If reconnect fails, the original (dead) Connection will be returned.

Code should, where possible, use one of the wrapper classes in oracle.javatools.db.execute to use a Connection and not need to directly call this method.

Returns:

the Connection owned by this database object

See Also:

getConnection(boolean)

getConnection

java.sql.Connection getConnection(boolean reconnect)
                                  throws DBException

Gets the JDBC connection associated with this database. If the given connection has been closed, the Database can attempt to reconnect it if desired. Any problem with the reconnect will be thrown as a DBException. Note that if reconnect is true, a test of the connection will be performed which hits the database using isConnectionAlive().

Parameters:

reconnect - whether to try and reconnect to the db

Returns:

the Connection owned by this database object

Throws:

DBException - wrapping a SQLException if there is a problem reconnecting

isConnectionAlive

boolean isConnectionAlive()

Tests whether the connection underneath this Database is "alive" - i.e. whether it is open and working.

Note the implementation of this is database specific - a positive can be assumed true but a negative could be incorrect.

Returns:

true if the underlying jdbc connection is working

See Also:

getConnection(boolean)

isConnectionClosed

java.lang.Boolean isConnectionClosed(java.sql.SQLException sqe)

Tests whether the given SQLException (assumed to have come from the connection of this db) is the result of the connection being closed.

If the method returns null it indicates that the API cannot identify the cause of any SQLException, either because:

• it hasn't been implemented in the particular Database implementation
• the JDBC driver doesn't throw SQLExceptions with an identifiable SQL codes/state.

Implementations that can identify exception causes (e.g. Oracle) should return non-null.

If this method is called with a null parameter value, it should return null if SQLException identification isn't supported, or Boolean.FALSE if it is.

Parameters:

sqe - the exception to test (this can be null to test if SQLException identification is supported).

Returns:

true if the exception is because the "connection is closed", false if the exception is the result of a different problem, or null if the db implementation cannot determine the difference.

Since:

11.1.1.4.0

hasTransaction

boolean hasTransaction()

Tests whether there is currently a "transaction" open on the underlying java.sql.Connection.

Note the implementation of this is database specific - a positive can be assumed true but a negative could be incorrect.

Returns:

true we are able to determine that a transaction is currently open on the underlying jdbc connection.

getConnectionName

java.lang.String getConnectionName()

Retrieves the name for the Connection associated with this Database in whichever connection store it is stored in.

Returns:

a String containing the connection name

See Also:

getConnectionStore(), getQualifiedName()

getConnectionStore

java.lang.String getConnectionStore()

Retrieves the connection store the Connection associated with this Database is stored in. This is not a displayable string.

Returns:

a String containing the connection store identifier.

See Also:

getQualifiedName()

getQualifiedName

java.lang.String getQualifiedName()

Retrieves a qualified name containing the connection store and connection name. The string is encoded so that it can be used as part of a URL. This is not a displayable string.

If this connection has no connection store associated with it, this method will simply return the encoded connection name.

Returns:

a String containing the encoded, qualified name.

See Also:

getConnectionStore(), getConnectionName()

close

void close()

Closes the Database Connection (and the supplied JDBC Connection).

getUserName

java.lang.String getUserName()
                             throws DBException

Retrieves the username used to connect to the database

Throws:

DBException

getDatabaseType

java.lang.String getDatabaseType()

Gets the type of database. This method uses JDBC metadata to determine the database type.

Returns:

an String describing the type of database

See Also:

DatabaseMetaData.getDatabaseProductName()

getDatabaseVersion

int getDatabaseVersion()

Gets the version of the database for the api implementation. This will not numerically correspond to the database model number, but is an int that the Database implementation uses to identify different versions.

exists

boolean exists(java.lang.String type,
               java.lang.String schema,
               java.lang.String objectName)

Checks for existance of a schema object named objectName.

Parameters:

objectName - The name of the schema object.

Returns:

true if the object exists, false otherwise.

getIdentifierQuoteString

java.lang.String getIdentifierQuoteString()

Returns the String to use to quote SQL identifiers with

Specified by:

getIdentifierQuoteString in interface DBObjectProvider

Returns:

the String to use to quote an SQL identifier, or an empty String "", if the underlying database does not support this functionality.

See Also:

DatabaseMetaData.getIdentifierQuoteString()

isObjectValid

boolean isObjectValid(java.lang.String objectType,
                      java.lang.String schema,
                      java.lang.String objectName)

Determines whether the specified database object is in a valid state.

Parameters:

schema - the name of the schema containing the object

objectName - the name of the object

objectType - the type of the object.

supportsDebugging

boolean supportsDebugging()

Whether this database instance supports JDWP debugging. If the database does not support debugging, or only supports debugging using a custom protocol, this method should return false.

Returns:

true if JDWP debugging is supported against this database, false otherwise

getDatabaseSource

java.lang.String getDatabaseSource(java.lang.String objectType,
                                   Schema schema,
                                   java.lang.String objectName)
                                   throws DBException

Retrieves the source for an object in the database. The specified object is assumed to be of some type that represents source; non-source based objects will return null.

Parameters:

objectType - The type of object for which the source is needed

schema - The Schema containing the object

objectName - The name of the object

Returns:

The source representing the object

Throws:

DBException - if an error occurs fetching the source

getDatabaseSource

java.lang.String getDatabaseSource(java.lang.String objectType,
                                   Schema schema,
                                   java.lang.String objectName,
                                   java.lang.String sourceType)
                                   throws DBException

Retrieves the source for an object in the database. The specified object is assumed to be of some type that represents source; non-source based objects will return null. This method combines spec and body for those source types that support both.

Parameters:

objectType - The type of object for which the source is needed

schema - The Schema containing the object

objectName - The name of the object

sourceType - In the case of types that have more than one source, the type of source required. Can be Database.SOURCE_TYPE_SPEC or Database.SOURCE_TYPE_BODY. If null, the default of body is selected.

Returns:

The source representing the object

Throws:

DBException - if an error occurs fetching the source

canRestrictSchemaList

boolean canRestrictSchemaList()

Whether this provider supports restricting the list of schemas to those with visible objects. For some providers, determining this list may be significantly more expensive than just returning a raw list of schemas.

Returns:

whether this provider allows the schema list to be restricted to those schemas with visible objects

testSQLStatement

void testSQLStatement(java.lang.String sql)
                      throws InvalidSQLException,
                             DBException

Tests that the given SQL executes against the database. This is separate to the SQLQueryBuilder API and is a simple test against the database.

Parameters:

sql - the sql to test

Throws:

InvalidSQLException - if the sql doesn't execute (because the syntax is invalid etc).

DBException - for any other error in executing the sql