planetj.database
Class DBSystem

java.lang.Object
  planetj.database.DBSystem

All Implemented Interfaces:

java.util.EventListener, IDBObject, ITaskListener, IXMLObject, java.io.Serializable

Direct Known Subclasses:

AS400DBSystem, DB2DBSystem, MSAccessDBSystem, MySQLDBSystem, OracleDBSystem, PostgreSQLDBSystem, SQLServerDBSystem

public class DBSystem

extends java.lang.Object

implements IDBObject, java.io.Serializable, IXMLObject, ITaskListener

Represents a relational database which can be referenced by a URL. A DBSystem object is created whenever the DatabaseManager opens a connection to a database. One DBSystem object exists for each alias used to create a connection pool

See Also:

Serialized Form

Field Summary

static byte	LIBRARIES_NOT_SUPPORTED This DB System does not support libraries
static byte	LIBRARIES_REQUIRED This DB System requries libraries in SQL statements
static byte	LIBRARIES_SUPPORTED This DB System supports libraries
static java.lang.String	METADATA_CATALOG_NAME_FIELD
static java.lang.String	METADATA_COLUMN_NAME_FIELD
static int	METADATA_COLUMN_NAME_OPERATION
static int	METADATA_COLUMN_NAME_OPERATION_FOR_CATALOGS
static java.lang.String	METADATA_LIBRARY_NAME
static java.lang.String	METADATA_LIBRARY_NAME_FIELD
static java.lang.String	METADATA_SYSTEM_NAME_FIELD
static java.lang.String	METADATA_TABLE_NAME_FIELD
static java.lang.String	METADATA_TABLE_NAME_FOR_COLUMNS
static java.lang.String	METADATA_TABLE_NAME_FOR_LIBRARIES
static java.lang.String	METADATA_TABLE_NAME_FOR_TABLES
static int	METADATA_TABLE_NAME_OPERATION
static int	METADATA_TABLE_NAME_OPERATION_FOR_CATALOGS

Constructor Summary

protected	DBSystem() Creates a new System object and sets its url and alias name.
protected	DBSystem(java.lang.String url) Creates a new System object and sets its url and alias name.
protected	DBSystem(java.lang.String pURL, java.lang.String pAlias) Creates a new System object and sets its url and alias name.

Method Summary

protected static void	addSQLTypeName(java.lang.String name, java.lang.Class c)
java.lang.Object	correctDatabaseObject(java.lang.Object object, int datatype) Returns an object of the appropriate type for insertion into the database.
void	correctOperation(Operation op) Corrects the operation to account for syntax differences of different DB systems.
java.lang.String	correctOperationSQL(java.lang.String originalSQL) Deprecated. Use correctOperation(Operation) instead
java.lang.String	correctSQLLiteral(java.lang.String value) Corrects the given SQL literal by adding additional escape characters to allow the value to be as is.
Library	createLibrary(java.lang.String pLibraryName) Gets the Library with the given name.
static DBSystem	createSystem(java.lang.String systemURL) Deprecated. removed (11/29/2002 1:48:58 PM) - driver is no required to create the DBSystem
static DBSystem	createSystem(java.lang.String url, java.lang.String alias) Creates and returns a new DBSystem using the given system url and alias
static DBSystem	createSystem(java.lang.String url, java.lang.String alias, java.lang.Class dbSystem) Creates and returns a new DBSystem using the given system url and alias
static DBSystem	createSystem(java.lang.String url, java.lang.String alias, java.lang.String driver) Creates and returns a new DBSystem using the given system url and alias
java.lang.String	getAlias() Returns the alias of the system.
java.util.Map	getAllLibraries() Returns a Map of all the Libraries (keyed by name) in this system.
DataEngineCache	getCache(AbstractContext context) Gets the cache which holds RC's read from this system
java.lang.String	getColumnDataTypeName(FieldDescriptorRow oldFD) Gets the correct column data type name for the FD on this system.
java.lang.String	getColumnIndicationCharacter() Returns the character that needs to be used during an insert.
java.lang.String	getColumnPrimaryKeyName(FieldDescriptorRow oldFD) Gets the correct column name which a primary key on this system should refer to for the FD.
int	getDataType(IParameter param) Gets the correct data type for the parameter for this DBSystem.
java.lang.String	getDBLibraryName(Library library) Returns the database name of the given library in the database.
java.lang.String	getDefaultDateFormat()
java.lang.String	getDefaultLibraryName() Gets the name of the default library specified in the connection URL.
java.lang.String	getDefaultTimeFormat()
java.lang.String	getDefaultTimestampFormat()
static java.lang.Class	getFieldClassForSQLTypeName(java.lang.String pTypeName) Gets the Field subclass that is representative of this SQL type name.
byte[]	getIPAddress() Gets the IP Address of this system
java.util.Map	getLibraries() Gets a Map of the libraries in this system.
Library	getLibrary(java.lang.String pLibraryName) Gets one of this system's libraries
Library	getLibrary(java.lang.String pLibraryName, boolean pCreate) Get the DBSystem's Library with the given name.
byte	getLibrarySupportLevel() Gets the level of library support; this is one of the constants defined in the class.
java.lang.String	getLibraryTableSeparator() Get the separator that should be placed between a library and a table for the system.
java.lang.String	getMetaDataAlias() Gets the alias of the system containing additional meta data (FD's, PV's, etc) for this system.
java.sql.ResultSet	getMetadataColumns(SQLContext context) Return a ResultSet of Columns
java.sql.ResultSet	getMetadataLibraries(SQLContext context) Return a ResultSet of libraries (schemas)
static DBSystem	getMetaDataSystem() Gets the metadata system
java.sql.ResultSet	getMetadataTables(SQLContext context) Return a ResultSet of Tables
java.lang.String	getName()
java.lang.String	getProperties() Gets the connection JDBC properties of the system.
static java.util.List	getSQLTypeNames() Gets a List of SQL type names.
int	getSupportedDataType(int datatype) Returns the equivalent supported datatype name for a specified datatype.
static DBSystem	getSystem(java.lang.String systemAlias) Gets the DBSystem for the given system alias.
java.lang.String	getURL() Returns the url of the system.
java.lang.StringBuffer	getXMLData(java.lang.StringBuffer pXMLData) This returns a StringBuffer containing all necessary XML data for this object.
void	handleConnectionEvent(ConnectionEvent event) Invoked when a ConnectionEvent occurs.
boolean	isAS400() Returns whether or not this DBSystem is an AS400 DB system KGetting (07/13/2005)
boolean	isBackgroundThreadsSupported() Override this method to return false if this system does not support background threads
boolean	isDB2() Returns whether or not this DBSystem is a DB2 DB system KGetting (07/13/2005)
boolean	isDefaultLibraryOmitted() Tests if the default library should be included in SQL statements sent to the DB (if the statement operates on the default library).
boolean	isDelegateToPersonal() Tests if this DBSystem is a placeholder for multiple personal DBSystems which should be used to connect to the DB in lieu of using this one.
boolean	isHasAllLibraries() Returns whether or not this DBSystem has all the libraries in the database.
boolean	isMSAccess() Returns whether or not this DBSystem is an MS Access DB system KGetting (07/13/2005)
boolean	isMySQL() Returns whether or not this DBSystem is a MySQL DB system KGetting (07/13/2005)
boolean	isOracle() Returns whether or not this DBSystem is an Oracle DB system KGetting (07/13/2005)
boolean	isSQLServer() Returns whether or not this DBSystem is a MS SQL Server DB system KGetting (07/13/2005)
Library	removeLibrary(java.lang.String pLibraryName) Removes the Library with the given name.
protected void	setAlias(java.lang.String pAlias) Sets the url of the system.
void	setDelegateToPersonal(boolean newDelegateToPersonal) Sets if this DBSystem is a placeholder for multiple personal DBSystems which should be used to connect to the DB in lieu of using this one.
protected void	setMetaDataAlias(java.lang.String pMetaDataAlias) Sets the alias of the system containing additional meta data (FD's, PV's, etc) for this system.
void	setProperties(java.lang.String pProperties) Sets the connection JDBC properties of the system.
protected void	setURL(java.lang.String pURL) Sets the url of the system.
protected void	setURLInternal(java.lang.String pURL) Sets the url of the system.
void	startRetrieveAllLibrariesTask() Starts a task to retrieve all the Libraries in the database for this system.
void	taskCompleted(TaskEvent pTaskEvent) Invoked when a task completes its execution.
void	taskFailed(TaskEvent pTaskEvent) Invoked when a task fails while executing.
void	taskStarted(TaskEvent pTaskEvent) Invoked when a task starts executing.
java.lang.String	toString() Returns the String representation of this system.

Methods inherited from class java.lang.Object

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

Field Detail

LIBRARIES_NOT_SUPPORTED

public static final byte LIBRARIES_NOT_SUPPORTED

This DB System does not support libraries

See Also:

Constant Field Values

LIBRARIES_SUPPORTED

public static final byte LIBRARIES_SUPPORTED

This DB System supports libraries

See Also:

Constant Field Values

LIBRARIES_REQUIRED

public static final byte LIBRARIES_REQUIRED

This DB System requries libraries in SQL statements

See Also:

Constant Field Values

METADATA_COLUMN_NAME_FIELD

public static final java.lang.String METADATA_COLUMN_NAME_FIELD

See Also:

Constant Field Values

METADATA_TABLE_NAME_FIELD

public static final java.lang.String METADATA_TABLE_NAME_FIELD

See Also:

Constant Field Values

METADATA_LIBRARY_NAME_FIELD

public static final java.lang.String METADATA_LIBRARY_NAME_FIELD

See Also:

Constant Field Values

METADATA_CATALOG_NAME_FIELD

public static final java.lang.String METADATA_CATALOG_NAME_FIELD

See Also:

Constant Field Values

METADATA_SYSTEM_NAME_FIELD

public static final java.lang.String METADATA_SYSTEM_NAME_FIELD

See Also:

Constant Field Values

METADATA_LIBRARY_NAME

public static final java.lang.String METADATA_LIBRARY_NAME

See Also:

Constant Field Values

METADATA_TABLE_NAME_FOR_LIBRARIES

public static final java.lang.String METADATA_TABLE_NAME_FOR_LIBRARIES

See Also:

Constant Field Values

METADATA_TABLE_NAME_FOR_TABLES

public static final java.lang.String METADATA_TABLE_NAME_FOR_TABLES

See Also:

Constant Field Values

METADATA_TABLE_NAME_FOR_COLUMNS

public static final java.lang.String METADATA_TABLE_NAME_FOR_COLUMNS

See Also:

Constant Field Values

METADATA_TABLE_NAME_OPERATION

public static final int METADATA_TABLE_NAME_OPERATION

See Also:

Constant Field Values

METADATA_COLUMN_NAME_OPERATION

public static final int METADATA_COLUMN_NAME_OPERATION

See Also:

Constant Field Values

METADATA_TABLE_NAME_OPERATION_FOR_CATALOGS

public static final int METADATA_TABLE_NAME_OPERATION_FOR_CATALOGS

See Also:

Constant Field Values

METADATA_COLUMN_NAME_OPERATION_FOR_CATALOGS

public static final int METADATA_COLUMN_NAME_OPERATION_FOR_CATALOGS

See Also:

Constant Field Values

Constructor Detail

DBSystem

protected DBSystem()

Creates a new System object and sets its url and alias name.

DBSystem

protected DBSystem(java.lang.String url)

Creates a new System object and sets its url and alias name.

Parameters:

url - String

DBSystem

protected DBSystem(java.lang.String pURL,
                   java.lang.String pAlias)

Creates a new System object and sets its url and alias name.

Method Detail

addSQLTypeName

protected static void addSQLTypeName(java.lang.String name,
                                     java.lang.Class c)

correctDatabaseObject

public java.lang.Object correctDatabaseObject(java.lang.Object object,
                                              int datatype)

Returns an object of the appropriate type for insertion into the database. In some cases, the default object type for a given datatype may not be appropriate for a given DB system - this method addresses that issue

Parameters:

object - The object to be inserted into the database

datatype - The datatype of the database field

Returns:

The corrected object to be inserted into the database

correctSQLLiteral

public java.lang.String correctSQLLiteral(java.lang.String value)

Corrects the given SQL literal by adding additional escape characters to allow the value to be as is. For example, "can't" becomes "can''t". Otherwise, running the SQL would terminate the literal when it found the first "'".

correctOperation

public void correctOperation(Operation op)

Corrects the operation to account for syntax differences of different DB systems. For example, in mySQL you cannot use the DECIMAL data type inside of a cast, instead the BINARY data type should be used

correctOperationSQL

public java.lang.String correctOperationSQL(java.lang.String originalSQL)

Deprecated. Use correctOperation(Operation) instead

Corrects the SQL to account for difference in the SQL syntax of different DB systems. For example, in mySQL you cannot use the DECIMAL data type inside of a cast, instead the BINARY data type should be used

createLibrary

public Library createLibrary(java.lang.String pLibraryName)

Gets the Library with the given name. The library is created if it does not exist.

Parameters:

pLibraryName - name of Library

Returns:

newly created or existing Library

createSystem

public static DBSystem createSystem(java.lang.String systemURL)
                             throws DataEngineException

Deprecated. removed (11/29/2002 1:48:58 PM) - driver is no required to create the DBSystem

Creates and returns a new DBSystem using the given system url. (The system will have an alias equal to its url.)

Parameters:

systemURL - String

Returns:

DBSystem

Throws:

DataEngineException

createSystem

public static DBSystem createSystem(java.lang.String url,
                                    java.lang.String alias)
                             throws DataEngineException

Creates and returns a new DBSystem using the given system url and alias

Throws:

DataEngineException

createSystem

public static DBSystem createSystem(java.lang.String url,
                                    java.lang.String alias,
                                    java.lang.Class dbSystem)
                             throws DataEngineException

Creates and returns a new DBSystem using the given system url and alias

Parameters:

url - String

Returns:

DBSystem

Throws:

DataEngineException

createSystem

public static DBSystem createSystem(java.lang.String url,
                                    java.lang.String alias,
                                    java.lang.String driver)
                             throws DataEngineException

Creates and returns a new DBSystem using the given system url and alias

Returns:

DBSystem

Throws:

DataEngineException

getAlias

public java.lang.String getAlias()

Returns the alias of the system.

Returns:

String

getAllLibraries

public java.util.Map getAllLibraries()
                              throws DataEngineException

Returns a Map of all the Libraries (keyed by name) in this system.

Returns:

Map

Throws:

DataEngineException

getCache

public DataEngineCache getCache(AbstractContext context)

Gets the cache which holds RC's read from this system

getColumnDataTypeName

public java.lang.String getColumnDataTypeName(FieldDescriptorRow oldFD)

Gets the correct column data type name for the FD on this system. This method is invoked on a DBSystem when the SQL for creating a new table on that system is being generated from the FD's of another table. The two tables may be on different systems. A null return value indicates that the same data type name is used for the new & old tables. For some data types the column length may have to be included.

Parameters:

oldFD - The FD for the column of the existing table

getColumnIndicationCharacter

public java.lang.String getColumnIndicationCharacter()

Returns the character that needs to be used during an insert. This char may be different for different DBSystems, so if necessary, override this method to return the required char An Example in MySQL: insert into depvdta (`TYPE`, `key`, `value`) values (6, 'HeHa', 'Yo') In this example the MySQLDBSystem should return a ` char The AS400DBSystem would return a " char

This char will is necessary when a column name is the same as a reserved keyword for this DBSystem. Such as KEY or USER Creation date: (6/23/2003 2:27:41 PM)

getColumnPrimaryKeyName

public java.lang.String getColumnPrimaryKeyName(FieldDescriptorRow oldFD)

Gets the correct column name which a primary key on this system should refer to for the FD. This method is invoked on a DBSystem when the SQL for creating a new table on that system is being generated from the FD's of another table. The two tables may be on different systems. This method returns the name of the column as referenced by the PRIMARY KEY clause of the CREATE TABLE statement. For some data types and systems, a length may need to be included with the column name (to indicate that the primary key should only look at a certain number of characters in the column)

Parameters:

oldFD - The FD for the column of the existing table

getDataType

public int getDataType(IParameter param)

Gets the correct data type for the parameter for this DBSystem.

getDBLibraryName

public java.lang.String getDBLibraryName(Library library)

Returns the database name of the given library in the database.

getDefaultDateFormat

public java.lang.String getDefaultDateFormat()

getDefaultTimeFormat

public java.lang.String getDefaultTimeFormat()

getDefaultTimestampFormat

public java.lang.String getDefaultTimestampFormat()

getDefaultLibraryName

public java.lang.String getDefaultLibraryName()

Gets the name of the default library specified in the connection URL. In no such library was specified, null is returned.

getFieldClassForSQLTypeName

public static java.lang.Class getFieldClassForSQLTypeName(java.lang.String pTypeName)
                                                   throws DataEngineException

Gets the Field subclass that is representative of this SQL type name. This subclass is not necessarily the field's direct class name, it is the most generic subclass of planetj.database.Field. For example, even though a field might have an SQL type name of BIGINT, which would mean that its class type would be BigIntegerField, this map is to the most generic subclass of planetj.database.Field which in this case would be NumberField.

Parameters:

pTypeName - The SQL type name of the field

Returns:

The appropriate subclass of Field which can represent this SQL type.

Throws:

DataEngineException

getIPAddress

public byte[] getIPAddress()

Gets the IP Address of this system

getLibraries

public java.util.Map getLibraries()

Gets a Map of the libraries in this system. The key is the library name and the value is a Library object. Note that the returned Map contains only the libraries which have been loaded by the DataEngine; there may be more libraries in the database.

getMetadataColumns

public java.sql.ResultSet getMetadataColumns(SQLContext context)
                                      throws CMException

Return a ResultSet of Columns

Throws:

CMException

getMetadataTables

public java.sql.ResultSet getMetadataTables(SQLContext context)
                                     throws CMException

Return a ResultSet of Tables

Throws:

CMException

getMetadataLibraries

public java.sql.ResultSet getMetadataLibraries(SQLContext context)
                                        throws CMException

Return a ResultSet of libraries (schemas)

Throws:

CMException

getLibrary

public Library getLibrary(java.lang.String pLibraryName)

Gets one of this system's libraries

Parameters:

pLibraryName - The name of the library to get

Returns:

The Library object with the specified name, or null if no such Library object exists

getLibrary

public Library getLibrary(java.lang.String pLibraryName,
                          boolean pCreate)

Get the DBSystem's Library with the given name. If it does not exist and specified so, then the Library is created.

Parameters:

pLibraryName - The name of the library to get

pCreate - Whether or not the library should be created if it doesn't exist

Returns:

Library with specified name or null if it does not exist and create was not specified

getLibrarySupportLevel

public byte getLibrarySupportLevel()

Gets the level of library support; this is one of the constants defined in the class. By default, libraries are required. Subclasses may override this method to indicate a different level of library support.

getLibraryTableSeparator

public java.lang.String getLibraryTableSeparator()

Get the separator that should be placed between a library and a table for the system. e.g. LibraryName.Table or LibraryName..Table

getMetaDataAlias

public java.lang.String getMetaDataAlias()

Gets the alias of the system containing additional meta data (FD's, PV's, etc) for this system.

Returns:

alias of system containing meta data

getMetaDataSystem

public static DBSystem getMetaDataSystem()

Gets the metadata system

getName

public java.lang.String getName()

Specified by:

getName in interface IDBObject

getProperties

public java.lang.String getProperties()

Gets the connection JDBC properties of the system.

Returns:

String

getSQLTypeNames

public static java.util.List getSQLTypeNames()

Gets a List of SQL type names.

getSupportedDataType

public int getSupportedDataType(int datatype)

Returns the equivalent supported datatype name for a specified datatype. For example, MS Access does not support the DECIMAL datatype, so if Types.DECIMAL was passed into this method on an Access system, the Types.DOUBLE datatype would be returned (since that is the datatype which will be used to store DECIMAL values on Access systems).

If the supplied datatype is supported, then that same datatype is returned.

getSystem

public static DBSystem getSystem(java.lang.String systemAlias)

Gets the DBSystem for the given system alias. If no such DBSystem exists null is returned.

Returns:

system for specified alias.

getURL

public java.lang.String getURL()

Returns the url of the system.

Returns:

String

getXMLData

public java.lang.StringBuffer getXMLData(java.lang.StringBuffer pXMLData)

This returns a StringBuffer containing all necessary XML data for this object. Creation date: (1/22/2002 1:35:13 PM)

Specified by:

getXMLData in interface IXMLObject

handleConnectionEvent

public void handleConnectionEvent(ConnectionEvent event)

Invoked when a ConnectionEvent occurs.

isBackgroundThreadsSupported

public boolean isBackgroundThreadsSupported()

Override this method to return false if this system does not support background threads

isDefaultLibraryOmitted

public boolean isDefaultLibraryOmitted()

Tests if the default library should be included in SQL statements sent to the DB (if the statement operates on the default library). For example, if the we want to select all records in MYTABLE in the default libarary (which is MYLIB):

When this method returns true: SELECT * FROM MYTABLE
When this method returns false: SELECT * FROM MYLIB.MYTABLE

isDelegateToPersonal

public boolean isDelegateToPersonal()

Tests if this DBSystem is a placeholder for multiple personal DBSystems which should be used to connect to the DB in lieu of using this one. When a user signs onto an app secured by a personal connection pool, then a special DBSystem just for that user is created; however a generic DBSystem shared by all users is also created and that generic DBSystem will return true from this method. The generic DBSystem shouldn't be used for connecting to the database, but is used for FD's, etc.

isHasAllLibraries

public boolean isHasAllLibraries()

Returns whether or not this DBSystem has all the libraries in the database. Once all the libraries have been retrieved, any additional libraries added to the database may not be retrieved and stored in this DBSystem, unless the method refreshLibraries() is called on the DBSystem.

Returns:

boolean

isMySQL

public boolean isMySQL()

Returns whether or not this DBSystem is a MySQL DB system KGetting (07/13/2005)

Returns:

boolean

isSQLServer

public boolean isSQLServer()

Returns whether or not this DBSystem is a MS SQL Server DB system KGetting (07/13/2005)

Returns:

boolean

isOracle

public boolean isOracle()

Returns whether or not this DBSystem is an Oracle DB system KGetting (07/13/2005)

Returns:

boolean

isMSAccess

public boolean isMSAccess()

Returns whether or not this DBSystem is an MS Access DB system KGetting (07/13/2005)

Returns:

boolean

isDB2

public boolean isDB2()

Returns whether or not this DBSystem is a DB2 DB system KGetting (07/13/2005)

Returns:

boolean

isAS400

public boolean isAS400()

Returns whether or not this DBSystem is an AS400 DB system KGetting (07/13/2005)

Returns:

boolean

removeLibrary

public Library removeLibrary(java.lang.String pLibraryName)

Removes the Library with the given name.

Parameters:

pLibraryName - name of Library

Returns:

Library being removed

setAlias

protected void setAlias(java.lang.String pAlias)

Sets the url of the system.

setDelegateToPersonal

public void setDelegateToPersonal(boolean newDelegateToPersonal)

Sets if this DBSystem is a placeholder for multiple personal DBSystems which should be used to connect to the DB in lieu of using this one. When a user signs onto an app secured by a personal connection pool, then a special DBSystem just for that user is created; however a generic DBSystem shared by all users is also created and that generic DBSystem will return true from this method. The generic DBSystem shouldn't be used for connecting to the database, but is used for FD's, etc.

setMetaDataAlias

protected void setMetaDataAlias(java.lang.String pMetaDataAlias)

Sets the alias of the system containing additional meta data (FD's, PV's, etc) for this system.

Parameters:

pMetaDataAlias - alias of system containing meta data

setProperties

public void setProperties(java.lang.String pProperties)

Sets the connection JDBC properties of the system.

setURL

protected void setURL(java.lang.String pURL)

Sets the url of the system.

setURLInternal

protected void setURLInternal(java.lang.String pURL)

Sets the url of the system.

startRetrieveAllLibrariesTask

public void startRetrieveAllLibrariesTask()

Starts a task to retrieve all the Libraries in the database for this system.

taskCompleted

public void taskCompleted(TaskEvent pTaskEvent)

Invoked when a task completes its execution.

Specified by:

taskCompleted in interface ITaskListener

taskFailed

public void taskFailed(TaskEvent pTaskEvent)

Invoked when a task fails while executing.

Specified by:

taskFailed in interface ITaskListener

taskStarted

public void taskStarted(TaskEvent pTaskEvent)

Invoked when a task starts executing.

Specified by:

taskStarted in interface ITaskListener

toString

public java.lang.String toString()

Returns the String representation of this system.

Returns:

String