## org.eclipse.datatools.sqltools.debugger.core
Interface IDebuggerControlConnection

All Superinterfaces:
  IControlConnection

public interface IDebuggerControlConnection
extends IControlConnection

The "debugger control connection" is designed for the following functions: <LL>

- Used for debugging.
- Manage all client connection to the server (debugged or not debugged), the connections view will display these information.

  Author:
    Yang Liu, Hui Cao

  Method Summary
  `java.sql.Connection` `createConnection(java.lang.String[] connId)` Creates a debuggee connection.
  `ClientConInfo` `getClientConInfo(java.lang.String connId)` Get the client connection information by id.
  `ClientConInfo[]` `getClientConInfos()` Gets the client connection information.
  `int[]` `getValidBreakpointLocations(ProcIdentifier proc, int[] lineNumbers)` Given the ProcIdentifier and the line numbers, finds out the valid line numbers that is greater than number that can set breakpoint.
  `boolean` `hasClientConnection()`
  `boolean` `hasDebuggee()` Checks whether there is registered debuggee.
  `boolean` `isAttached(java.lang.String connId)` Tests whether the specified connection is attached by debugger
  `java.lang.String` `readyToDebug()` Checks whether ths control connection is ready to debug.
  `void` `refreshExternalClients()` Refreshs external clients info.
  `void` `registerDebuggee(java.lang.String connId, IConnectionObserver observer)` Registers the debuggee connection identified by `connId`.
  `void` `requestDetach(java.lang.String connId)` Requests to stop debugging on the specified connection
  `void` `unregisterDebuggee(java.lang.String connId)` Unregisters the debuggee connection identified by `connId`.

  Methods inherited from interface org.eclipse.datatools.sqltools.core.IControlConnection
  `convertToInternalConnId, createRoutine, disconnect, disconnect, getAllProcs, getContentAssistInfo, getDatabaseIdentifier, getDBItem, getDbUsername, getProcSource, getReusableConnection, getTypeByNameStr, isTextHidden, okToDisconnect, profileRenamed, refresh, refresh, registerInternalConn, saveStoredProcedure, supportsDebugging, unregisterInternalConn`

  Method Detail

  ### registerDebuggee

      public void registerDebuggee(java.lang.String connId,
                                   IConnectionObserver observer)
                            throws ConnectionException

    Registers the debuggee connection identified by `connId`. Called by the debugger to information this controller that the specified connection is being debugged. if the same id debuggee already registered, then the behavior is undefined.

    Parameters:
      `connId` - the database specific connection id @see org.eclipse.datatools.sqltools.core.services.IConnectionService#getConnectionId(org.eclipse.datatools.sqltools.core.DatabaseIdentifier, java.sql.Connection)
    Throws:
      `ConnectionException`

  ### unregisterDebuggee

      public void unregisterDebuggee(java.lang.String connId)

    Unregisters the debuggee connection identified by `connId`. This method is called when the debuggee is no longer being debugged.

    Parameters:
      `connId` - the database specific connection id @see org.eclipse.datatools.sqltools.core.services.IConnectionService#getConnectionId(org.eclipse.datatools.sqltools.core.DatabaseIdentifier, java.sql.Connection)

  ### hasDebuggee

      public boolean hasDebuggee()

    Checks whether there is registered debuggee.

    Returns:
      true if any; false if none.

  ### requestDetach

      public void requestDetach(java.lang.String connId)

    Requests to stop debugging on the specified connection

    Parameters:
      `connId` - the database specific connection id @see org.eclipse.datatools.sqltools.core.services.IConnectionService#getConnectionId(org.eclipse.datatools.sqltools.core.DatabaseIdentifier, java.sql.Connection)

  ### isAttached

      public boolean isAttached(java.lang.String connId)

    Tests whether the specified connection is attached by debugger

    Parameters:
      `connId` - the database specific connection id @see org.eclipse.datatools.sqltools.core.services.IConnectionService#getConnectionId(org.eclipse.datatools.sqltools.core.DatabaseIdentifier, java.sql.Connection)

  ### getClientConInfos

      public ClientConInfo[] getClientConInfos()

    Gets the client connection information.

    Returns:
      `ClientConInfo` array managed by this control connection.

  ### getClientConInfo

      public ClientConInfo getClientConInfo(java.lang.String connId)

    Get the client connection information by id.

    Parameters:
      `connId` - the database specific connection id @see org.eclipse.datatools.sqltools.core.services.IConnectionService#getConnectionId(org.eclipse.datatools.sqltools.core.DatabaseIdentifier, java.sql.Connection)
    Returns:

  ### hasClientConnection

      public boolean hasClientConnection()

    Returns:
    See Also:
      `getClientConInfos()`

  ### refreshExternalClients

      public void refreshExternalClients()

    Refreshs external clients info. This may be called from UI showing external clients info.

  ### getValidBreakpointLocations

      public int[] getValidBreakpointLocations(ProcIdentifier proc,
                                               int[] lineNumbers)
                                        throws java.sql.SQLException

    Given the ProcIdentifier and the line numbers, finds out the valid line numbers that is greater than number that can set breakpoint. If for some reason, this operation is not supported, the original number will be returned.

    Parameters:
      `proc` - the routine object containing the breakpoints
      `lineNumbers` - original breakpoint line numbers
    Returns:
      line numbers. Valid numbers are greater or equals to 0. -1 means can't find a valid location.
    Throws:
      `java.sql.SQLException`

  ### readyToDebug

      public java.lang.String readyToDebug()

    Checks whether ths control connection is ready to debug. Return null if it is ready, otherwise, return the error message.

    Returns:
      error message or null

  ### createConnection

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

    Creates a debuggee connection. If can't get connection, will put "" as the connid.

    Parameters:
      `connId` - the connection id of the new connection.
    Returns:
    Throws:
      `NoSuchProfileException`
      `CoreException`
      `java.sql.SQLException`

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