Provides a base implementation of the DBObjectProvider
interface. AbstractDBObjectProvider provides support for
registering DBObjectBuilder instances for building specific
types of DBObjects. The list of builders is used to determine
the types of objects supported by the DBObjectProvider
implementation, to list the available objects of a specific type, and to
retrieve the SchemaObject representations of the objects.

Subclasses are responsible for ensuring that DBObjectBuilder and
DBObjectValidator instances are registered for the types of objects
that will be supported. AbstractDBObjectProvider is abstract; sublasses
are also responsible for providing implementations of those methods that
do not have a generic implementation.

AbstractDBObjectProvider also handles caching of
DBObject instances. When new instances are created, they are
stored in a WeakHashMap. Subsequent requests for the same metadata will
result in the same DBObject instance being returned.

resetObject(SystemObject object,
SystemObject listed,
java.lang.Long timestamp)
If it has been noticed that the timestamp has changed on an object, or we
have updated it in the database, we want to turn it back into an object
that needs building again.

protected void

resetObject(SystemObject object,
SystemObject listed,
java.lang.Long timestamp,
boolean updated)
If it has been noticed that the timestamp has changed on an object, or we
have updated it in the database, we want to turn it back into an object
that needs building again.

void

resumeTimestampQueries(java.lang.String key)
Resumes the calls to get the external timestamp for a given object.

addObjectListener

Adds a listener that is notified of any updates to the given object. This
differs from SystemObject.addObjectListener(DBObjectListener)
because that listens to a specific object instance. Registering the
listener with the provider through this method ensures that events will be
received for the lifetime of the provider (as the particular object
instance could be lost - e.g. gc'd).

registerType

Registers a Builder and Validator for a specific object type. If a Builder
has already been registered for the specified type, the new builder will
replace the previous builder (same with validator). If either parameter is
null this will not remove the builder. Use unregisterBuilder() or
unregisterValidator() to do this.

listObjectsImpl

Retrieves the list of objects by using a registered builder. If no
builder has been registered for the object type, an empty array of
names will be returned. Subclasses can use this method to delegate the
list of objects to builders.

findSchema

Method for use within the provider that retrieves a schema and doesn't
check the database if the schema is found in the cache. This should only
be used withing operations where the existence of the schema is implied
or unnecessary.

resumeTimestampQueries

public final void resumeTimestampQueries(java.lang.String key)

Resumes the calls to get the external timestamp for a given object. The key
passed in must match that passed into suspendTimestampQueries and the
number of keys must reach zero before timestamping will resume.

suspendTimestampQueries

public final void suspendTimestampQueries(java.lang.String key)

Limits the call to get the external timestamp for a given object to once
until resumeTimestampQueries() is called. This means that once queried the
first time, if an object is changed in the database the API will not
notice.

putCachedTimestampKey

Checks that timestamps are suspended, and if they are caches the given
key and value in the timestamp cache. Access to the cache is only possible
while timestamps are suspended, and the cache is cleared when timestamps
are not suspended.

Parameters:

obj - the key for the timstamp cache

value - the value to put against the given key

Returns:

any existing value that was in the cache already for the given key

supportsTimestamps

public boolean supportsTimestamps(java.lang.String objectType)

Returns true if this provider supports object timestamping for the given
object type. An object's timestamp is set in the property map
( getProperties() ) under the TIMESTAMP_PROPERTY key.

getTimestamp

Retrieves the timestamp representing the last modification time of the
specified object's metadata. If the provider does not provide timestamp
information for metadata, a null value should be returned.

findByID

resetObject

If it has been noticed that the timestamp has changed on an object, or we
have updated it in the database, we want to turn it back into an object
that needs building again. This method resets an object back to a pre-built
state.

Parameters:

object - the object we want to have cached and reset

listed - an object returned by a list/find which is potentially in
the cache, and potentially has a different id.

timestamp - the timestamp for the new object (can be null)

resetObject

If it has been noticed that the timestamp has changed on an object, or we
have updated it in the database, we want to turn it back into an object
that needs building again. This method resets an object back to a pre-built
state.

Parameters:

object - the object we want to have cached and reset

listed - an object returned by a list/find which is potentially in
the cache, and potentially has a different id.

timestamp - the timestamp for the new object (can be null)

updated - whether is the reset of an existing object (true)

createObjectImpl

Uses listObjectsImpl to find or create an object with the given type,
schema and name. If an object exists in the cache it will be returned
(assuming it still exists in the underlying provider) otherwise a new
object (lazy loaded) will be created.

isRequestedObject

Returns true if SchemaObject object is of type type, owned by schema schema,
and named name. This default implementation matches name exactly. It should
be overridden when a looser name match is required, e.g. Oracle database links.

getExternalTimestampImpl

Retrieves the external timestamp for the specified object. The external
timestamp represents the last modification time for the object in the
backend store (database, file system, or whatever else this provider is
representing).

the string containing the character or characters used to quote
an identifier.

listObjectTypes

public java.lang.String[] listObjectTypes()

Returns a sorted array of the object types supported in this provider. If
overridden the returned array must be sorted by the natural ordering of
the elements (i.e. so that Arrays.binarySearch will work).

hasSystemPrivilege

Checks to see whether the user has the requisite permissions to perform the
specified operation. For example, whether the user has permission to create
a new table in a specific schema.
NB The return value should be used as guide only and is not guarenteed to
truely reflect the current set of privileges. The default implementation
will always return true, and other implementations may choose to cache the
result.

hasObjectPrivilege

Checks to see whether the user has the requisite permissions to perform the
specified operation on the given object. For example, whether the user has
permission to alter a table.
NB The return value should be used as guide only and is not guarenteed to
truely reflect the current set of privileges. The default implementation
will always return true, and other implementations may choose to cache the
result.

getPropertyManager

Gets the PropertyManager (if available) for this provider. The property
manager provides information about which properties are supported on which
objects, and what operations (create/replace/update/delete) are supported
for any particular object or property.

quoteIdentifier

Determines if internalName needs quoting to make it a valid external name,
and if so returns a quoted copy of it. If it doesn't need quoting, it
returns the name unquoted. If internalName is empty, or quoted names aren't
supported by the provider and the name isn't valid, it returns null.

getInternalName

Converts the specified name into the format used internally within
the metadata. Generally, internal names are not quoted; quoted names
have the quotes removed. Unquoted names may be converted to a single case
if the underlying provider does not support mixed case identifiers.

getInternalName

Converts the specified name into the format used internally within
the metadata. Generally, internal names are not quoted; quoted names
have the quotes removed. Unquoted names may be converted to a single case
if the underlying provider does not support mixed case identifiers.

getExternalName

Converts the specified name into the format used externally to represent
the identifier. In most case, this is equivalent to calling
quoteIdentifier, specifying false for the
force argument. Note, however, that exceptions are not thrown; rather, the
original name will be returned.

getExternalName

Converts the specified name into the format used externally to represent
the identifier. In most case, this is equivalent to calling
quoteIdentifier, specifying false for the
force argument. Note, however, that exceptions are not thrown; rather, the
original name will be returned.

validateObject

Validates the given object using the DBObjectValidator registered against
that object's type. A ValidationException is thrown if the object fails to
validate, or if no DBObjectValidator is registered for that object type.

validateObjectProperty

Checks to see if the children of a given object are valid. If the object
has no children of the given type a MissingValidatorException will be
thrown. This is a convinience method to perform validation to a specific
property on an object - all properties will be validated if
DBObjectProvider.validateObject(DBObject) is called.

ValidationException - if the object is not valid. The exception will
describe the validation failure. A MissingValidatorException is thrown if
the provider has no validator for the given object type, or property.

validateObject

Validates the given object update using the DBObjectValidator registered against
that object's type. A ValidationException is thrown if the update fails to
validate, or if no DBObjectValidator is registered for that object type.

validateObjectProperty

Checks to see if the updated children of a given object are valid. If the
object has no children of the given type a MissingValidatorException will
be thrown. This is a convinience method to perform validation to a specific
property on an object - all properties will be validated if
DBObjectProvider.validateObject(DBObject,DBObject) is called.

validateUniqueName

Validates that a name is not used within the context DBObject, and throws
NameInUseException if it is. This default implementation throws the
exception if :
1. type is a SchemaObject and name matches the name of one of
contextObject's owned objects.
2. type is an Index and name matches the name of an index of one of
contextObject's owned objects.
3. type is a Constraint and name matches the name of a contraint of one
of contextObject's owned objects.
In all cases NameInUseException.getUserObject() will return the matching
owned object.

getUniqueName

Returns a unique name for an object of given type within contextObject
using base name. This default implementation ensures that you
cannot have two SchemaObjects of any type with the same name, two indexes
with the same name or two constraints with the same name, within
contextObject.