## 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:

- Load/create/save routine objects;
- Get database metadata to present as content assist proposals;
- Get supported data types;
- Manage all the internal connections to the same database;
- etc.

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.