planetj.database
Class DBSystem

java.lang.Object
  |
  +--planetj.database.DBSystem

All Implemented Interfaces:

EventListener, IDBObject, ITaskListener, IXMLObject, Serializable

Direct Known Subclasses:

AS400DBSystem, DB2DBSystem, MSAccessDBSystem, MySQLDBSystem, OracleDBSystem, SQLServerDBSystem

public class DBSystem

extends Object

implements IDBObject, 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

Author:

PlanetJ Corporation

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

Method Summary

Object	correctDatabaseObject(Object object, int datatype) Returns an object of the appropriate type for insertion into the database.
Library	createLibrary(String pLibraryName) Gets the Library with the given name.
static DBSystem	createSystem(String systemURL) Deprecated. removed (11/29/2002 1:48:58 PM) - driver is no required to create the DBSystem
static DBSystem	createSystem(String url, String alias) Creates and returns a new DBSystem using the given system url and alias
static DBSystem	createSystem(String url, String alias, Class dbSystem) Creates and returns a new DBSystem using the given system url and alias
static DBSystem	createSystem(String url, String alias, String driver) Creates and returns a new DBSystem using the given system url and alias
String	getAlias() Returns the alias of the system.
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
String	getColumnIndicationCharacter() Returns the character that needs to be used during an insert.
String	getDefaultDateFormat()
String	getDefaultLibraryName() Gets the name of the default library specified in the connection URL.
static Class	getFieldClassForSQLTypeName(String pTypeName) Gets the Field subclass that is representative of this SQL type name.
byte[]	getIPAddress() Gets the IP Address of this system
Map	getLibraries() Gets a Map of the libraries in this system.
Library	getLibrary(String pLibraryName) Gets one of this system's libraries
Library	getLibrary(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.
String	getMetaDataAlias() Gets the alias of the system containing additional meta data (FD's, PV's, etc) for this system.
static DBSystem	getMetaDataSystem() Gets the metadata system
String	getName()
String	getProperties() Gets the connection JDBC properties of the system.
static 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(String systemAlias) Gets the DBSystem for the given system alias.
String	getURL() Returns the url of the system.
StringBuffer	getXMLData(StringBuffer pXMLData) This returns a StringBuffer containing all necessary XML data for this object.
boolean	isBackgroundThreadsSupported() Override this method to return false if this system does not support background threads
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.
Library	removeLibrary(String pLibraryName) Removes the Library with the given name.
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.
void	setProperties(String pProperties) Sets the connection JDBC properties 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.
String	toString() Returns the String representation of this system.

Methods inherited from class java.lang.Object

equals, 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

Method Detail

correctDatabaseObject

public Object correctDatabaseObject(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

createLibrary

public Library createLibrary(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(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

DataEngineException

createSystem

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

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

DataEngineException

createSystem

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

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

Parameters:

url - String

Returns:

DBSystem

DataEngineException

createSystem

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

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

Returns:

DBSystem

DataEngineException

getAlias

public String getAlias()

Returns the alias of the system.

Returns:

String

getAllLibraries

public Map getAllLibraries()
                    throws DataEngineException

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

Returns:

Map

DataEngineException

getCache

public DataEngineCache getCache(AbstractContext context)

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

getColumnIndicationCharacter

public 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)

getDefaultDateFormat

public String getDefaultDateFormat()

getDefaultLibraryName

public 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 Class getFieldClassForSQLTypeName(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.

DataEngineException

getIPAddress

public byte[] getIPAddress()

Gets the IP Address of this system

getLibraries

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

getLibrary

public Library getLibrary(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(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.

getMetaDataAlias

public 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 String getName()

Specified by:

getName in interface IDBObject

getProperties

public String getProperties()

Gets the connection JDBC properties of the system.

Returns:

String

getSQLTypeNames

public static 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(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 String getURL()

Returns the url of the system.

Returns:

String

getXMLData

public StringBuffer getXMLData(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

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

removeLibrary

public Library removeLibrary(String pLibraryName)

Removes the Library with the given name.

Parameters:

pLibraryName - name of Library

Returns:

Library being removed

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.

setProperties

public void setProperties(String pProperties)

Sets the connection JDBC properties 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 String toString()

Returns the String representation of this system.

Overrides:

toString in class Object

Returns:

String