oracle.javatools.db
Class DatabaseDescriptor<T extends Database>

java.lang.Object
  oracle.javatools.db.DatabaseDescriptor<T>

public abstract class DatabaseDescriptor<T extends Database>
extends java.lang.Object

Interface used to describe the behaviour of a Database. This class abstracts out any behaviour from Database that does not require a physical connection.

Since:

11

See Also:

DatabaseFactory.getDatabaseDescriptor(Class), DBObjectProvider.getDescriptor()

Field Summary

static java.lang.String	BUILT_IN_OBJECT Object property to indicate that a given DBObject is "built-in" to the provider it was listed from.
static java.lang.String	FEATURE_BITMAP_INDEXING
static java.lang.String	FEATURE_COLUMN_SEQUENCES
static java.lang.String	FEATURE_GLOBAL_HASH_INDEX_PARTITIONING
static java.lang.String	FEATURE_LOB_PARAMETERS
static java.lang.String	FEATURE_MAXTRANS
static java.lang.String	FEATURE_STORAGE_OPTIONS
static java.lang.String	FEATURE_TABLE_PARTITIONING
static java.lang.String	FEATURE_XMLTYPE_COL_PROPS

Constructor Summary

protected	DatabaseDescriptor(java.lang.Class<? extends T> clz)
protected	DatabaseDescriptor(DatabaseDescriptor base)

Method Summary

DataTypeUsage	createDefaultTypeUsage() Creates a default usage of a data type for use in a new Column, PlSqlMethod etc.
protected java.lang.String	escapeQuoteCharacter(java.lang.String quote) Escapes the quote character.
protected DatabaseDescriptor	getBaseDescriptor() If this descriptor is a customisation of a base descriptor, this method returns that base descriptor.
abstract int	getCasePolicy() Returns the case policy for unquoted names of the Database being described
protected java.lang.Class<? extends T>	getDatabaseClass() Implementations must return the database class they are describing here for the data type support to work.
abstract java.lang.String	getDatabaseType() Gets a String representing the type of database.
abstract int	getDatabaseVersion() Gets an int representing the version of the database type.
DataType	getDataType(java.lang.String typeName) Gets the datatype with given name.
DDLGenerator	getDDLGenerator(DBObjectProvider pro) Gets a DDLGenerator that will generate DDL for the type of Database represented by this descriptor, setup to work with the given provider.
java.lang.String	getExternalName(java.lang.String name, java.lang.String objectType) Converts the specified name into the format used externally to represent the identifier.
abstract java.util.List<PropertyInitializer>	getExternalPropertyDefaulters(DBObjectProvider pro) Gets a list of PropertyInitializers responsible for defining the default value for properties when generated to an external database represented by the given provider.
java.nio.charset.Charset	getIdeCharset()
abstract java.lang.String	getIdentifierQuoteString() Returns the identifier quote string for the Database being described.
java.lang.String	getInternalName(java.lang.String name, java.lang.String objectType) Converts the specified name into the format used internally within the metadata.
abstract int	getMaxNameLength(java.lang.String type) Returns the maximum length for a name of the given type.
abstract java.util.List<PropertyInitializer>	getPropertyInitializers(DBObjectProvider pro) Gets a list of PropertyInitializers responsible for defining the initial value for properties in the given provider.
int	getQuotedNameCasePolicy() Returns the case policy for quoted names of the Database being described.
java.util.Collection<java.lang.String>	getReservedWords() Returns a collection of the reserved words for the database being described
abstract SqlAliasExpander	getSqlAliasExpander(DBObjectProvider pro)
SQLQueryBuilderFactory	getSQLQueryBuilderFactory() Gets the SQLQueryBuilderFactory implementation for creating a SQLQueryBuilder for this database type.
abstract java.util.Map<java.lang.String,DBObjectValidator>	getValidators(DBObjectProvider pro) Gets a map of object type (e.g.
protected void	initialiseBuiltInObject(SystemObject obj) Called on every object returned by listBuiltInObjects to set any specific properties that mark the object as "built-in".
abstract boolean	isCompatibleUpgrade(java.lang.Class<? extends Database> dbClz, java.lang.Class<? extends Database> testClz) Returns true if the given testClz is a compatible upgrade path for a user of the given dbClz.
boolean	isValidFKDataType(DataType fktype, DataType reftype) Assesses if the datatype of a foreign key column is valid given the datatype of the column which it references.
protected boolean	isValidFKDataTypeImpl(DataType fktype, DataType reftype)
boolean	isValidName(java.lang.String type, java.lang.String name) Checks to see whether a name is valid.
<T extends SystemObject> java.util.Collection<T>	listBuiltInObjects(DBObjectCriteria<T> criteria) A built-in object is a SystemObject definition that we define in the database descriptor for well-known objects.
protected <T extends SystemObject> java.util.Collection<T>	listBuiltInObjectsImpl(DBObjectCriteria<T> criteria) Implementation for listing built-in objects.
java.util.Collection<java.lang.String>	listPreferredDataTypeNames() Override to provide the names of the prefered types for the described database.
java.util.Collection<DataType>	listPreferredDataTypes() Lists the preferred datatypes of this provider.
java.util.Collection<DataType>	listSupportedDataTypes() Lists the datatypes supported by the described database type.
abstract void	makeNameValidAndUnique(DBObject object, DBObjectProvider pro) Attempts to set a valid unique name for the given object.
protected boolean	needsQuoting(java.lang.String internalName) Determines whether internalName needs quoting to make it a valid external name.
java.lang.String	quoteIdentifier(java.lang.String internalName, boolean force) Determines if internalName needs quoting to make it a valid external name, and if so returns a quoted copy of it.
void	setIdeCharset(java.nio.charset.Charset charSet)
boolean	supportsFeature(java.lang.String feature) Returns true if feature is supported by the Database described by this DatabaseDescriptor.
void	validateEncoding(java.lang.String string, java.lang.Object property) Tests whether the given string is encoded property for the given property.
static void	validateIdentifier(java.lang.String identifier, char quoter, int maxLength, java.lang.String allowedChars, boolean alphaStart, java.util.Set reservedWords, int casePolicy) Validates that name is a valid external name such that : If the name is unquoted (does not start with quoter), it only contains alphanumeric and allowedChars characters. If the name is unquoted, and alphaStart is true, it starts with a letter. If the name is unquoted, it does not contain any reservedWords. If the name is quoted (starts with quoter), it is correctly quoted, and does not include any excludedChars. If the name is quoted, and quoter is not in excludedChars, that any occurences of quoter are escaped (doubled-up). The name does not exceed maxLength, taking quotes into account. Used by the more specific validate*Identifier() methods on the Database implementations.
static void	validateIdentifier(java.lang.String identifier, char quoter, int maxLength, java.lang.String allowedChars, java.lang.String excludedChars, boolean alphaStart, java.util.Set reservedWords, int casePolicy) Validates that name is a valid external name such that : If the name is unquoted (does not start with quoter), it only contains alphanumeric and allowedChars characters. If the name is unquoted, and alphaStart is true, it starts with a letter. If the name is unquoted, it does not contain any reservedWords. If the name is quoted (starts with quoter), it is correctly quoted, and does not include any excludedChars. If the name is quoted, and quoter is not in excludedChars, that any occurences of quoter are escaped (doubled-up). The name does not exceed maxLength, taking quotes into account. Used by the more specific validate*Identifier() methods on the Database implementations.
abstract void	validateName(java.lang.String type, java.lang.String name) Validates the given object name and throws an InvalidNameExcpetion if it isn't valid for the Database being described.

Methods inherited from class java.lang.Object

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

Field Detail

FEATURE_TABLE_PARTITIONING

public static final java.lang.String FEATURE_TABLE_PARTITIONING

See Also:

Constant Field Values

FEATURE_GLOBAL_HASH_INDEX_PARTITIONING

public static final java.lang.String FEATURE_GLOBAL_HASH_INDEX_PARTITIONING

See Also:

Constant Field Values

FEATURE_COLUMN_SEQUENCES

public static final java.lang.String FEATURE_COLUMN_SEQUENCES

See Also:

Constant Field Values

FEATURE_STORAGE_OPTIONS

public static final java.lang.String FEATURE_STORAGE_OPTIONS

See Also:

Constant Field Values

FEATURE_BITMAP_INDEXING

public static final java.lang.String FEATURE_BITMAP_INDEXING

See Also:

Constant Field Values

FEATURE_LOB_PARAMETERS

public static final java.lang.String FEATURE_LOB_PARAMETERS

See Also:

Constant Field Values

FEATURE_MAXTRANS

public static final java.lang.String FEATURE_MAXTRANS

See Also:

Constant Field Values

FEATURE_XMLTYPE_COL_PROPS

public static final java.lang.String FEATURE_XMLTYPE_COL_PROPS

See Also:

Constant Field Values

BUILT_IN_OBJECT

public static final java.lang.String BUILT_IN_OBJECT

Object property to indicate that a given DBObject is "built-in" to the provider it was listed from.

See Also:

listBuiltInObjects(oracle.javatools.db.DBObjectCriteria), Constant Field Values

Constructor Detail

DatabaseDescriptor

protected DatabaseDescriptor(java.lang.Class<? extends T> clz)

DatabaseDescriptor

protected DatabaseDescriptor(DatabaseDescriptor base)

Method Detail

getDatabaseClass

protected final java.lang.Class<? extends T> getDatabaseClass()

Implementations must return the database class they are describing here for the data type support to work.

getDatabaseType

public abstract java.lang.String getDatabaseType()

Gets a String representing the type of database. This is usually a constant defined on an extension of the Database interface for a specific database type (e.g. oracle.javatools.db.ora.OracleDatabase).

getDatabaseVersion

public abstract int getDatabaseVersion()

Gets an int representing the version of the database type. This is not necessarily the version number corresponding to a published version, rather an integer used by the api implementation - i.e. it is for comparison only, and not display.

getBaseDescriptor

protected DatabaseDescriptor getBaseDescriptor()

If this descriptor is a customisation of a base descriptor, this method returns that base descriptor.

setIdeCharset

public void setIdeCharset(java.nio.charset.Charset charSet)

getIdeCharset

public java.nio.charset.Charset getIdeCharset()

isCompatibleUpgrade

public abstract boolean isCompatibleUpgrade(java.lang.Class<? extends Database> dbClz,
                                            java.lang.Class<? extends Database> testClz)

Returns true if the given testClz is a compatible upgrade path for a user of the given dbClz.

e.g. if testClz is Oracle9i and dbClz is Oracle11g this will return true because 11g is an upgrade to 9i.

This will only work reliably if called on the descriptor appropriate to dbClz (i.e. returned by DatabaseFactory.getDatabaseDescriptor(Class);

Parameters:

dbClz - the current database class

testClz - the class to test as a compatible upgrade

Returns:

true if testClz is an upgraded version of dbClz

isValidName

public final boolean isValidName(java.lang.String type,
                                 java.lang.String name)

Checks to see whether a name is valid. Note that a valid name does not guarantee uniqueness. The default implementation is allow all names.

Parameters:

name - the name to check

Returns:

whether the name is valid

validateName

public abstract void validateName(java.lang.String type,
                                  java.lang.String name)
                           throws InvalidNameException

Validates the given object name and throws an InvalidNameExcpetion if it isn't valid for the Database being described. The type parameter is optional and gives the type of the object whose name is being validated. The name expected is a "external name" i.e. one that is quoted if necessary.

Throws:

InvalidNameException

See Also:

DBObjectProvider.getExternalName(java.lang.String), DBObjectProvider.getInternalName(java.lang.String)

getCasePolicy

public abstract int getCasePolicy()

Returns the case policy for unquoted names of the Database being described

Returns:

the Database's case policy for unquoted names

See Also:

AbstractDBObjectProvider.LOWER_CASE_NAME_POLICY, AbstractDBObjectProvider.MIXED_CASE_NAME_POLICY, AbstractDBObjectProvider.UPPER_CASE_NAME_POLICY, AbstractDBObjectProvider.CASE_SENSITIVE_NAME_POLICY

getQuotedNameCasePolicy

public int getQuotedNameCasePolicy()

Returns the case policy for quoted names of the Database being described. This default implementation assumes that quoted names are case sensitive and returns CASE_SENSITIVE_NAME_POLICY. Override where this isn't true, e.g SQLServer.

Returns:

the Database's case policy for quoted names

See Also:

AbstractDBObjectProvider.LOWER_CASE_NAME_POLICY, AbstractDBObjectProvider.MIXED_CASE_NAME_POLICY, AbstractDBObjectProvider.UPPER_CASE_NAME_POLICY, AbstractDBObjectProvider.CASE_SENSITIVE_NAME_POLICY

getIdentifierQuoteString

public abstract java.lang.String getIdentifierQuoteString()

Returns the identifier quote string for the Database being described.

getMaxNameLength

public abstract int getMaxNameLength(java.lang.String type)

Returns the maximum length for a name of the given type.

supportsFeature

public boolean supportsFeature(java.lang.String feature)

Returns true if feature is supported by the Database described by this DatabaseDescriptor. This default implementation returns false. It should be overridden where the feature is supported.

Parameters:

feature - : name of feature

Returns:

true if feature supported otherwise false

validateEncoding

public void validateEncoding(java.lang.String string,
                             java.lang.Object property)
                      throws ValidationException

Tests whether the given string is encoded property for the given property.

Parameters:

string - the string to test

property - the property identifier that the string is a value for

Throws:

ValidationException - if the encoding is invalid

needsQuoting

protected boolean needsQuoting(java.lang.String internalName)

Determines whether internalName needs quoting to make it a valid external name. A name will need quoting if it contains non standard characters, or if the database defines a case policy and internalName is in a different case, e.g Oracle converts lower and mixed case names to upper case unless they are quoted. Therefore, if the internal name is lower or mixed case, it will need quoting to make it a valid external name.

Parameters:

internalName -

Returns:

true if internalName needs quoting

quoteIdentifier

public java.lang.String quoteIdentifier(java.lang.String internalName,
                                        boolean force)
                                 throws DBException

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.

Parameters:

internalName -

force - Always quote the name

Returns:

the quoted name

Throws:

DBException

escapeQuoteCharacter

protected java.lang.String escapeQuoteCharacter(java.lang.String quote)

Escapes the quote character. Used to escape quote characters that occur in a quoted String. By default ' becomes '', this happens for all quote characters apart from " which is escaped by default with a \ . Override when this is not appropriate.

getInternalName

public java.lang.String getInternalName(java.lang.String name,
                                        java.lang.String objectType)

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.

Parameters:

name - a String containing the name to convert

objectType - the type of object the name is for

Returns:

the internal version of the name

getExternalName

public java.lang.String getExternalName(java.lang.String name,
                                        java.lang.String objectType)

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.

Parameters:

name - a String containing the name to externalize

Returns:

a String containing the externalized name

getValidators

public abstract java.util.Map<java.lang.String,DBObjectValidator> getValidators(DBObjectProvider pro)

Gets a map of object type (e.g. Table.TYPE) to DBObjectValidator responsible for validating that type for the described database type. The given provider is used on construction of the validator, but not to determine which validators to return, that is governed by this descriptor.

getPropertyInitializers

public abstract java.util.List<PropertyInitializer> getPropertyInitializers(DBObjectProvider pro)

Gets a list of PropertyInitializers responsible for defining the initial value for properties in the given provider. The given provider is used on construction of the PropertyInitializer, but not to determine which to return, that is governed by this descriptor.

getExternalPropertyDefaulters

public abstract java.util.List<PropertyInitializer> getExternalPropertyDefaulters(DBObjectProvider pro)

Gets a list of PropertyInitializers responsible for defining the default value for properties when generated to an external database represented by the given provider. The given provider is used on construction of the PropertyInitializer, but not to determine which to return, that is governed by this descriptor.

getDDLGenerator

public DDLGenerator getDDLGenerator(DBObjectProvider pro)

Gets a DDLGenerator that will generate DDL for the type of Database represented by this descriptor, setup to work with the given provider. Can return null if there is no DDLGenerator for this descriptor's database type.

Note the parameter is a DBObjectProvider. All DDLGenerator implementations must be instantiable with a DBObjectProvider so that generic features (like the offline database) can leverage DDL generation for all supported databases.

Parameters:

pro - the provider to initialise the DDLGenerator with

Returns:

a DDLGenerator for this descriptor's DDL flavour.

getSQLQueryBuilderFactory

public SQLQueryBuilderFactory getSQLQueryBuilderFactory()

Gets the SQLQueryBuilderFactory implementation for creating a SQLQueryBuilder for this database type.

Returns:

a SQLQueryBuilderFactory, used to a createSQLQueryBuilder. Returns null if SQL isn't supported for this database type.

listSupportedDataTypes

public java.util.Collection<DataType> listSupportedDataTypes()

Lists the datatypes supported by the described database type.

listPreferredDataTypes

public final java.util.Collection<DataType> listPreferredDataTypes()

Lists the preferred datatypes of this provider. This is an optional method to implement that will drive the preference of the returned types in parts of the UI where datatypes are selected.

listPreferredDataTypeNames

public java.util.Collection<java.lang.String> listPreferredDataTypeNames()

Override to provide the names of the prefered types for the described database.

See Also:

listPreferredDataTypes()

createDefaultTypeUsage

public DataTypeUsage createDefaultTypeUsage()

Creates a default usage of a data type for use in a new Column, PlSqlMethod etc. If listPreferredDataTypes() returns any types, this will be a usage of the first type in that list. Otherwise a VARCHAR or CHAR type will be searched for and a usage of that returned.

Returns:

the default datatype usage for this database. This can be null.

getDataType

public DataType getDataType(java.lang.String typeName)

Gets the datatype with given name. Will return null if the given datatype is not supported by the described database type.

Parameters:

typeName - the type to get

Returns:

the corresponding DataType object, or null if the given type name isn't supported.

listBuiltInObjects

public final <T extends SystemObject> java.util.Collection<T> listBuiltInObjects(DBObjectCriteria<T> criteria)

A built-in object is a SystemObject definition that we define in the database descriptor for well-known objects. For example in Oracle this includes the Types in MDSYS, the XMLTYPE support etc.

listBuiltInObjectsImpl

protected <T extends SystemObject> java.util.Collection<T> listBuiltInObjectsImpl(DBObjectCriteria<T> criteria)

Implementation for listing built-in objects. Override as appropriate, the default is no built-in objects.

initialiseBuiltInObject

protected void initialiseBuiltInObject(SystemObject obj)

Called on every object returned by listBuiltInObjects to set any specific properties that mark the object as "built-in".

Parameters:

obj -

isValidFKDataType

public final boolean isValidFKDataType(DataType fktype,
                                       DataType reftype)

Assesses if the datatype of a foreign key column is valid given the datatype of the column which it references.

Parameters:

fktype - the datatype of the column in the foreign key

reftype - the datatype of the column in the parent table's referenced constraint

Returns:

true if the reference datatype is valid for the target datatype, false otherwise.

isValidFKDataTypeImpl

protected boolean isValidFKDataTypeImpl(DataType fktype,
                                        DataType reftype)

validateIdentifier

public static void validateIdentifier(java.lang.String identifier,
                                      char quoter,
                                      int maxLength,
                                      java.lang.String allowedChars,
                                      java.lang.String excludedChars,
                                      boolean alphaStart,
                                      java.util.Set reservedWords,
                                      int casePolicy)
                               throws InvalidNameException

Validates that name is a valid external name such that :

1. If the name is unquoted (does not start with quoter), it only contains alphanumeric and allowedChars characters.
2. If the name is unquoted, and alphaStart is true, it starts with a letter.
3. If the name is unquoted, it does not contain any reservedWords.
4. If the name is quoted (starts with quoter), it is correctly quoted, and does not include any excludedChars.
5. If the name is quoted, and quoter is not in excludedChars, that any occurences of quoter are escaped (doubled-up).
6. The name does not exceed maxLength, taking quotes into account.

Used by the more specific validate*Identifier() methods on the Database implementations.

Parameters:

identifier - the external name to check

quoter - the quote string (e.g. " )

maxLength - the maximum length a name can be (not including quotes)

allowedChars - characters that are allowed in an unquoted identifier (aswell as alphanumerics)

excludedChars - characters that are not allowed in quoted identifiers.

alphaStart - whether to enforce that the unquoted identifiers must start with an alphabet character.

reservedWords - Set of words that are reserved in the database

casePolicy - the case policy to use

Throws:

InvalidNameException - with an appropriate message if the identifier isn't valid.

validateIdentifier

public static void validateIdentifier(java.lang.String identifier,
                                      char quoter,
                                      int maxLength,
                                      java.lang.String allowedChars,
                                      boolean alphaStart,
                                      java.util.Set reservedWords,
                                      int casePolicy)
                               throws InvalidNameException

Validates that name is a valid external name such that :

1. If the name is unquoted (does not start with quoter), it only contains alphanumeric and allowedChars characters.
2. If the name is unquoted, and alphaStart is true, it starts with a letter.
3. If the name is unquoted, it does not contain any reservedWords.
4. If the name is quoted (starts with quoter), it is correctly quoted, and does not include any excludedChars.
5. If the name is quoted, and quoter is not in excludedChars, that any occurences of quoter are escaped (doubled-up).
6. The name does not exceed maxLength, taking quotes into account.

Used by the more specific validate*Identifier() methods on the Database implementations.

Parameters:

identifier - the external name to check

quoter - the quote string (e.g. " )

maxLength - the maximum length a name can be (not including quotes)

allowedChars - characters that are allowed in an unquoted identifier (aswell as alphanumerics)

alphaStart - whether to enforce that the unquoted identifiers must start with an alphabet character.

reservedWords - Set of words that are reserved in the database

casePolicy - the case policy to use

Throws:

InvalidNameException - with an appropraite message if the identifier isn't valid.

makeNameValidAndUnique

public abstract void makeNameValidAndUnique(DBObject object,
                                            DBObjectProvider pro)
                                     throws InvalidNameException

Attempts to set a valid unique name for the given object. If this is not possible, throws InvalidNameException.

Throws:

InvalidNameException

getReservedWords

public java.util.Collection<java.lang.String> getReservedWords()

Returns a collection of the reserved words for the database being described

getSqlAliasExpander

public abstract SqlAliasExpander getSqlAliasExpander(DBObjectProvider pro)