org.eclipse.datatools.sqltools.core
Interface IControlConnection


public interface IControlConnection

For each connected database, we keep a "control connection". This connection is used for all shared usage to that particular database. This control connection is a wrapper of the connection created by connectivity layer and relies on connectivity layer to do connection caching/pooling. Shared usage refers to the following ones:

As you can see, all the above mentioned functions can be accomplished by using SQL Model, Database Model and the API from Connectivity layer. This is because SQL Dev Tools evolves at the same time with DTP Model Base project and Connectivity project, so you can view this interface as the ��adapter�� between SQL Dev Tools and the other 2 projects of DTP. In fact, we��ll provide a default implementation of this interface which uses SQL Model, Database Model and the API from Connectivity layer.

Author:
Yang Liu, Hui Cao

Method Summary
 java.lang.String convertToInternalConnId(java.lang.String externalId, java.lang.String exteranlName)
          As the connection id used inside IControlConnection may be different from those external ids.
 java.sql.Connection createConnection(java.lang.String[] connId)
           
 boolean disconnect()
          same as disconnect(false)
 boolean disconnect(boolean force)
          Disconnects this control connection.
 void executeDDL(java.lang.String[] sql)
          Creates or drops a routine object in the database by executing the definition statement
 ProcIdentifier[] getAllProcs()
          gets all routine object identifiers exist in the database.
 DatabaseIdentifier getDatabaseIdentifier()
          Returns which databaseIdentifier is used for this control connection
 IDBItem getDBItem(ProcIdentifier identifier)
          NOTE: caller should check whether the return value is null.
 java.lang.String getDbUsername()
          As the profile login name could be different from the database user name.
 java.lang.String getProcSource(ProcIdentifier proc)
          Gets the source code of the specified routine.
 java.sql.Connection getReusableConnection()
          Returns the wrapped connection object.
 IDatatype getTypeByNameStr(java.lang.String nameStr)
          Gets a IDatatype object by name.
 boolean isTextHidden(DatabaseIdentifier databaseIdentifier, java.lang.String dbObjectName, int dbObjectType)
          Checks if the Text of the procedural object is hidden.
 boolean okToDisconnect()
          Whether it's ok to disconnect this control connection.
 void profileRenamed(java.lang.String profileName)
          Should be called to keep in sync when profile name is changed while other profile properties are left unchanged.
 void refresh()
          Refreshs all the cached routine object definitions.
 void refresh(ProcIdentifier procIdentifier)
          Refreshs the specified cached routine object definitions.
 void saveRoutine(ProcIdentifier proc, java.lang.String string)
          Saves the specified routine object into database.
 boolean supportsDebugging()
          Whether this control connection supports debugging.
 

Method Detail

getDatabaseIdentifier

DatabaseIdentifier getDatabaseIdentifier()
Returns which databaseIdentifier is used for this control connection

Returns:
a DatabaseIdentifier object, key of this control connection

profileRenamed

void profileRenamed(java.lang.String profileName)
Should be called to keep in sync when profile name is changed while other profile properties are left unchanged.

Parameters:
profileName - the connection profile name

getDbUsername

java.lang.String getDbUsername()
                               throws java.sql.SQLException
As the profile login name could be different from the database user name. this method will get the database user name.

Returns:
database user name
Throws:
java.sql.SQLException

getProcSource

java.lang.String getProcSource(ProcIdentifier proc)
                               throws java.sql.SQLException
Gets the source code of the specified routine. Wrapper method for connectivity layer.

Parameters:
proc - the identifier of a routine object
Returns:
the routine source code
Throws:
java.sql.SQLException

getAllProcs

ProcIdentifier[] getAllProcs()
                             throws java.sql.SQLException
gets all routine object identifiers exist in the database.

Returns:
Array of ProcIdentifier
Throws:
java.sql.SQLException

okToDisconnect

boolean okToDisconnect()
Whether it's ok to disconnect this control connection.


disconnect

boolean disconnect(boolean force)
Disconnects this control connection.

Parameters:
force - whether force to disconnect even if still in use (by debugger, etc)
Returns:
true means successfully disconnected. false means it is still in use.

disconnect

boolean disconnect()
same as disconnect(false)

Returns:
true means successfully disconnected. false means it is still in use.

getReusableConnection

java.sql.Connection getReusableConnection()
Returns the wrapped connection object. This is a convenience method which gets the jdbc connection from connection profile.

Returns:
the wrapped connection object

saveRoutine

void saveRoutine(ProcIdentifier proc,
                 java.lang.String string)
                 throws java.sql.SQLException
Saves the specified routine object into database.

Parameters:
proc - routine identifier
string - source code of the routine object
Throws:
java.sql.SQLException

getDBItem

IDBItem getDBItem(ProcIdentifier identifier)
NOTE: caller should check whether the return value is null.

Parameters:
identifier - routine identifier
Returns:
can return null.

executeDDL

void executeDDL(java.lang.String[] sql)
                throws java.sql.SQLException
Creates or drops a routine object in the database by executing the definition statement

Parameters:
sql - the ddl statements
Throws:
java.sql.SQLException

refresh

void refresh()
Refreshs all the cached routine object definitions. Wrapper method for connectivity layer.


refresh

void refresh(ProcIdentifier procIdentifier)
Refreshs the specified cached routine object definitions. Wrapper method for connectivity layer.

Parameters:
procIdentifier - routine identifier

getTypeByNameStr

IDatatype getTypeByNameStr(java.lang.String nameStr)
                           throws java.lang.Exception
Gets a IDatatype object by name. e.g., given char(10), return a IDatatype object which describe char(10)

Returns:
a IDatatype represented by the given name.
Throws:
java.sql.SQLException
java.lang.Exception

isTextHidden

boolean isTextHidden(DatabaseIdentifier databaseIdentifier,
                     java.lang.String dbObjectName,
                     int dbObjectType)
Checks if the Text of the procedural object is hidden. (TODO: request Model Base project to add "isSourceHidden" attribute to SQL Routine object so that we can remove this mothed).

Returns:
true if text hidden, else false

convertToInternalConnId

java.lang.String convertToInternalConnId(java.lang.String externalId,
                                         java.lang.String exteranlName)
                                         throws ConnectionException
As the connection id used inside IControlConnection may be different from those external ids. So sometimes when people have external id and exteranl name, they need to convert to internal id first. For vendors that don't care about it, just return the externalId is fine.

Parameters:
externalId - external connection id
exteranlName - optional connection name
Throws:
ConnectionException

supportsDebugging

boolean supportsDebugging()
Whether this control connection supports debugging. Later this can be obtained from database definition model. If the return value is true, this should be an instance of IDebuggerControlConnection.

Returns:
true if so; false otherwise
See Also:
IDebuggerControlConnection

createConnection

java.sql.Connection createConnection(java.lang.String[] connId)
                                     throws java.sql.SQLException,
                                            CoreException,
                                            NoSuchProfileException
Throws:
java.sql.SQLException
CoreException
NoSuchProfileException


Copyright © 2006 -- 2008 Actuate, IBM Corporation, Sybase, Inc. and others. All rights reserved.