Module org.firebirdsql.jaybird
Package org.firebirdsql.event

# Interface EventManager

All Superinterfaces:
  `AttachmentProperties`, `AutoCloseable`, `BaseProperties`

All Known Implementing Classes:
  `FBEventManager`

public interface EventManager extends AttachmentProperties, AutoCloseable
An interface for registering `EventListener` instances to listen for database events.

Author:
  Gabriel Reid, Mark Rotteveel

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addEventListener(String eventName, EventListener listener)`
  Register an EventListener that will be called when an event occurs.
  `void`
  `close()`
  If connected, disconnects, otherwise does nothing.
  `void`
  `connect()`
  Make a connection with a database to listen for events.
  `void`
  `disconnect()`
  Close the connection to the database.
  `String`
  `getDatabaseName()`
  Get the database name.
  `long`
  `getWaitTimeout()`
  Get the poll timeout in milliseconds of the async thread to check whether it was stopped or not.
  `WireCrypt`
  `getWireCryptAsEnum()`
  Get the wire encryption level.
  `boolean`
  `isConnected()`
  `void`
  `removeEventListener(String eventName, EventListener listener)`
  Remove an EventListener for a given event.
  `void`
  `setDatabaseName(String databaseName)`
  Set the database name.
  `void`
  `setWaitTimeout(long waitTimeout)`
  Set the poll timeout in milliseconds of the async thread to check whether it was stopped or not.
  `void`
  `setWireCryptAsEnum(WireCrypt wireCrypt)`
  Set the wire encryption level.
  `int`
  `waitForEvent(String eventName)`
  Wait for the one-time occurrence of an event.
  `int`
  `waitForEvent(String eventName, int timeout)`
  Wait for the one-time occurrence of an event.

  ### Methods inherited from interface org.firebirdsql.jaybird.props.AttachmentProperties

  `getAuthPlugins, getCharSet, getConnectTimeout, getDbCryptConfig, getEnableProtocol, getEncoding, getParallelWorkers, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSocketFactory, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEnableProtocol, setEncoding, setParallelWorkers, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSocketFactory, setSoTimeout, setType, setUser, setWireCompression, setWireCrypt`

  ### Methods inherited from interface org.firebirdsql.jaybird.props.BaseProperties

  `connectionPropertyValues, getBooleanProperty, getBooleanProperty, getIntProperty, getIntProperty, getProperty, getProperty, setBooleanProperty, setIntProperty, setProperty`

- ## Method Details

  - ### connect

    void connect() throws SQLException
    Make a connection with a database to listen for events.
    Throws:
      `SQLException` - If a database communication error occurs
      `IllegalStateException` - If already connected

  - ### close

    void close() throws SQLException
    If connected, disconnects, otherwise does nothing.

    Contrary to `disconnect()`, this method does not throw `IllegalStateException` when not connected.

    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `SQLException` - For errors during disconnect
    Since:
      3.0.7

  - ### disconnect

    void disconnect() throws SQLException
    Close the connection to the database.
    Throws:
      `SQLException` - If a database communication error occurs
      `IllegalStateException` - If not currently connected
    See Also:
      - `close()`

  - ### isConnected

    boolean isConnected()
    Returns:
      `true` when connected and able to listen for events
    See Also:
      - `connect()`
      - `disconnect()`

  - ### getDatabaseName

    String getDatabaseName()
    Get the database name.

    See `DatabaseConnectionProperties.getDatabaseName()` for details.

    Returns:
      database name
    Since:
      5

  - ### setDatabaseName

    void setDatabaseName(String databaseName)
    Set the database name.

    See `DatabaseConnectionProperties.setDatabaseName(String)` for details.

    Parameters:
      `databaseName` - database name
    Since:
      5

  - ### getWireCryptAsEnum

    WireCrypt getWireCryptAsEnum()
    Get the wire encryption level.
    Returns:
      Wire encryption level
    Since:
      5

  - ### setWireCryptAsEnum

    void setWireCryptAsEnum(WireCrypt wireCrypt)
    Set the wire encryption level.
    Parameters:
      `wireCrypt` - Wire encryption level (`null` not allowed)
    Since:
      5

  - ### getWaitTimeout

    long getWaitTimeout()
    Get the poll timeout in milliseconds of the async thread to check whether it was stopped or not.

    Default value is 1000 (1 second).

    Returns:
      wait timeout in milliseconds

  - ### setWaitTimeout

    void setWaitTimeout(long waitTimeout)
    Set the poll timeout in milliseconds of the async thread to check whether it was stopped or not.

    Default value is 1000 (1 second).

    Parameters:
      `waitTimeout` - wait timeout in milliseconds

  - ### addEventListener

    void addEventListener(String eventName, EventListener listener) throws SQLException
    Register an EventListener that will be called when an event occurs.
    Parameters:
      `eventName` - The name of the event for which the listener will be notified
      `listener` - The EventListener that will be called when the given event occurs
    Throws:
      `SQLException` - If a database access error occurs

  - ### removeEventListener

    void removeEventListener(String eventName, EventListener listener) throws SQLException
    Remove an EventListener for a given event.
    Parameters:
      `eventName` - The name of the event for which the listener will be unregistered.
      `listener` - The EventListener that is to be unregistered
    Throws:
      `SQLException` - If a database access error occurs

  - ### waitForEvent

    int waitForEvent(String eventName) throws InterruptedException, SQLException
    Wait for the one-time occurrence of an event.

    This method blocks indefinitely until the event identified by the value of `eventName` occurs. The return value is the number of occurrences of the requested event.

    Parameters:
      `eventName` - The name of the event to wait for
    Returns:
      The number of occurences of the requested event
    Throws:
      `InterruptedException` - If interrupted while waiting
      `SQLException` - If a database access error occurs

  - ### waitForEvent

    int waitForEvent(String eventName, int timeout) throws InterruptedException, SQLException
    Wait for the one-time occurrence of an event.

    This method blocks for a maximum of `timeout` milliseconds, waiting for the event identified by `eventName` to occur. A timeout value of `0` means wait indefinitely.

    The return value is the number of occurences of the event in question, or `-1` if the call timed out.

    Parameters:
      `eventName` - The name of the event to wait for
      `timeout` - The maximum number of milliseconds to wait
    Returns:
      The number of occurrences of the requested event, or `1` if the call timed out
    Throws:
      `InterruptedException` - If interrupted while waiting
      `SQLException` - If a database access error occurs