Package org.firebirdsql.event

## Interface EventManager

- All Superinterfaces:
    `AttachmentProperties`, `java.lang.AutoCloseable`, `BaseProperties`
  All Known Implementing Classes:
    `FBEventManager`

      public interface EventManager
      extends AttachmentProperties, java.lang.AutoCloseable

  An interface for registering `EventListener` instances to listen for database events.
  Author:
    Gabriel Reid, Mark Rotteveel

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addEventListener​(java.lang.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.
    `java.lang.String` | `getDatabase()` | Deprecated. Use `getDatabaseName()`; will be removed in Jaybird 6 or later
    `java.lang.String` | `getDatabaseName()` | Get the database name.
    `java.lang.String` | `getHost()` | Deprecated. Use `AttachmentProperties.getServerName()`; will be removed in Jaybird 6 or later
    `int` | `getPort()` | Deprecated. Use `AttachmentProperties.getPortNumber()`; will be removed in Jaybird 6 or later
    `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​(java.lang.String eventName, EventListener listener)` | Remove an EventListener for a given event.
    `void` | `setDatabase​(java.lang.String database)` | Deprecated. Use `setDatabaseName(String)`; will be removed in Jaybird 6 or later
    `void` | `setDatabaseName​(java.lang.String databaseName)` | Set the database name.
    `void` | `setHost​(java.lang.String host)` | Deprecated. Use `AttachmentProperties.setServerName(String)`; will be removed in Jaybird 6 or later
    `void` | `setPort​(int port)` | Deprecated. Use `AttachmentProperties.setPortNumber(int)`; will be removed in Jaybird 6 or later
    `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​(java.lang.String eventName)` | Wait for the one-time occurrence of an event.
    `int` | `waitForEvent​(java.lang.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, getEncoding, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEncoding, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, 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 Detail

    - #### connect

          void connect()
                throws java.sql.SQLException

      Make a connection with a database to listen for events.
      Throws:
        `java.sql.SQLException` - If a database communication error occurs
        `java.lang.IllegalStateException` - If already connected

    - #### close

          void close()
              throws java.sql.SQLException

      If connected, disconnects, otherwise does nothing.

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

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

    - #### disconnect

          void disconnect()
                   throws java.sql.SQLException

      Close the connection to the database.
      Throws:
        `java.sql.SQLException` - If a database communication error occurs
        `java.lang.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

          java.lang.String getDatabaseName()

      Get the database name.

      See `DatabaseConnectionProperties.getDatabaseName()` for details.

      Returns:
        database name
      Since:
        5

    - #### setDatabaseName

          void setDatabaseName​(java.lang.String databaseName)

      Set the database name.

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

      Parameters:
        `databaseName` - database name
      Since:
        5

    - #### setDatabase

          @Deprecated
          void setDatabase​(java.lang.String database)

      Deprecated.
      Use `setDatabaseName(String)`; will be removed in Jaybird 6 or later
      Sets the database path or url for the connection to the database.
      Parameters:
        `database` - path or url for the connection to the database.

    - #### getDatabase

          @Deprecated
          java.lang.String getDatabase()

      Deprecated.
      Use `getDatabaseName()`; will be removed in Jaybird 6 or later
      Returns:
        the database path or url for the connection to the database.

    - #### getHost

          @Deprecated
          java.lang.String getHost()

      Deprecated.
      Use `AttachmentProperties.getServerName()`; will be removed in Jaybird 6 or later
      Returns:
        the host for the connection to the database.

    - #### setHost

          @Deprecated
          void setHost​(java.lang.String host)

      Deprecated.
      Use `AttachmentProperties.setServerName(String)`; will be removed in Jaybird 6 or later
      Sets the host for the connection to the database.

      See `AttachmentProperties.setServerName(String)` for details.

      Parameters:
        `host` - for the connection to the database.

    - #### getPort

          @Deprecated
          int getPort()

      Deprecated.
      Use `AttachmentProperties.getPortNumber()`; will be removed in Jaybird 6 or later
      Returns:
        the port for the connection to the database.

    - #### setPort

          @Deprecated
          void setPort​(int port)

      Deprecated.
      Use `AttachmentProperties.setPortNumber(int)`; will be removed in Jaybird 6 or later
      Sets the port for the connection to the database.
      Parameters:
        `port` - for the connection to the database.

    - #### 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​(java.lang.String eventName,
                                EventListener listener)
                         throws java.sql.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:
        `java.sql.SQLException` - If a database access error occurs

    - #### removeEventListener

          void removeEventListener​(java.lang.String eventName,
                                   EventListener listener)
                            throws java.sql.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:
        `java.sql.SQLException` - If a database access error occurs

    - #### waitForEvent

          int waitForEvent​(java.lang.String eventName)
                    throws java.lang.InterruptedException,
                           java.sql.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:
        `java.lang.InterruptedException` - If interrupted while waiting
        `java.sql.SQLException` - If a database access error occurs

    - #### waitForEvent

          int waitForEvent​(java.lang.String eventName,
                           int timeout)
                    throws java.lang.InterruptedException,
                           java.sql.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:
        `java.lang.InterruptedException` - If interrupted while waiting
        `java.sql.SQLException` - If a database access error occurs