Package org.firebirdsql.event

## Class FBEventManager

- java.lang.Object
- - org.firebirdsql.event.FBEventManager

- All Implemented Interfaces:
    `java.lang.AutoCloseable`, `EventManager`, `AttachmentProperties`, `BaseProperties`

      public class FBEventManager
      extends java.lang.Object
      implements EventManager

  An `EventManager` implementation to listen for database events.
  Author:
    Gabriel Reid, Mark Rotteveel, Vasiliy Yashkov

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FBEventManager()` |
    `FBEventManager​(GDSType gdsType)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete 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.
    `java.util.Map<ConnectionProperty,​java.lang.Object>` | `connectionPropertyValues()` | An unmodifiable view on the connection properties held by this BaseProperties implementation.
    `static EventManager` | `createFor​(java.sql.Connection connection)` | Creates an `EventManager` for a connection.
    `void` | `disconnect()` | Close the connection to the database.
    `java.lang.String` | `getAuthPlugins()` | Get the list of authentication plugins to try.
    `java.lang.Boolean` | `getBooleanProperty​(java.lang.String name)` | Retrieves a `boolean` property value by name.
    `java.lang.String` | `getDatabase()` | Deprecated.
    `java.lang.String` | `getDatabaseName()` | Get the database name.
    `java.lang.String` | `getDbCryptConfig()` | Get the database encryption plugin configuration.
    `java.lang.String` | `getHost()` | Deprecated.
    `java.lang.Integer` | `getIntProperty​(java.lang.String name)` | Retrieves an `int` property value by name.
    `java.lang.String` | `getPassword()` |
    `int` | `getPort()` | Deprecated.
    `int` | `getPortNumber()` | Get the port number of the server.
    `java.lang.String` | `getProperty​(java.lang.String name)` | Retrieves a string property value by name.
    `java.lang.String` | `getServerName()` | Get the hostname or IP address of the Firebird server.
    `java.lang.String` | `getUser()` |
    `long` | `getWaitTimeout()` | Get the poll timeout in milliseconds of the async thread to check whether it was stopped or not.
    `java.lang.String` | `getWireCrypt()` | Get the wire encryption level.
    `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` | `setAuthPlugins​(java.lang.String authPlugins)` | Sets the authentication plugins to try.
    `void` | `setBooleanProperty​(java.lang.String name, java.lang.Boolean value)` | Sets a `boolean` property by name.
    `void` | `setDatabase​(java.lang.String database)` | Deprecated.
    `void` | `setDatabaseName​(java.lang.String databaseName)` | Set the database name.
    `void` | `setDbCryptConfig​(java.lang.String dbCryptConfig)` | Sets the database encryption plugin configuration.
    `void` | `setHost​(java.lang.String host)` | Deprecated.
    `void` | `setIntProperty​(java.lang.String name, java.lang.Integer value)` | Sets an `int` property by name.
    `void` | `setPassword​(java.lang.String password)` |
    `void` | `setPort​(int port)` | Deprecated.
    `void` | `setPortNumber​(int portNumber)` | Set the port number of the server.
    `void` | `setProperty​(java.lang.String name, java.lang.String value)` | Sets a property by name.
    `void` | `setServerName​(java.lang.String serverName)` | Set the hostname or IP address of the Firebird server.
    `void` | `setType​(java.lang.String type)` |
    `void` | `setUser​(java.lang.String user)` |
    `void` | `setWaitTimeout​(long waitTimeout)` | Set the poll timeout in milliseconds of the async thread to check whether it was stopped or not.
    `void` | `setWireCrypt​(java.lang.String wireCrypt)` | Set the wire encryption level.
    `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.
    `protected LockCloseable` | `withLock()` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

      `getCharSet, getConnectTimeout, getEncoding, getProcessId, getProcessName, getRoleName, getSocketBufferSize, getSoTimeout, getType, isWireCompression, setCharSet, setConnectTimeout, setEncoding, setProcessId, setProcessName, setRoleName, setSocketBufferSize, setSoTimeout, setWireCompression`

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

      `getBooleanProperty, getIntProperty, getProperty`

- - ### Constructor Detail

    - #### FBEventManager

          public FBEventManager()

    - #### FBEventManager

          public FBEventManager​(GDSType gdsType)

  - ### Method Detail

    - #### createFor

          public static EventManager createFor​(java.sql.Connection connection)
                                        throws java.sql.SQLException

      Creates an `EventManager` for a connection.

      The created event manager does not allow setting the properties and will instead throw `UnsupportedOperationException` for the setters.

      The returned instance is not necessarily an implementation of `FBEventManager`.

      Parameters:
        `connection` - A connection that unwraps to `FirebirdConnection`
      Returns:
        An event manager
      Throws:
        `java.sql.SQLException` - When `connection` does not unwrap to `FirebirdConnection`
      Since:
        3.0.7

    - #### withLock

          protected final LockCloseable withLock()

    - #### setType

          public final void setType​(java.lang.String type)

      Specified by:
        `setType` in interface `AttachmentProperties`
      Parameters:
        `type` - type of the connection, for example, "PURE_JAVA", "NATIVE", "EMBEDDED", depends on the GDS implementations installed in the system.

    - #### connect

          public void connect()
                       throws java.sql.SQLException

      Description copied from interface: `EventManager`
      Make a connection with a database to listen for events.
      Specified by:
        `connect` in interface `EventManager`
      Throws:
        `java.sql.SQLException` - If a database communication error occurs

    - #### close

          public void close()
                     throws java.sql.SQLException

      Description copied from interface: `EventManager`
      If connected, disconnects, otherwise does nothing.

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

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

    - #### disconnect

          public void disconnect()
                          throws java.sql.SQLException

      Description copied from interface: `EventManager`
      Close the connection to the database.
      Specified by:
        `disconnect` in interface `EventManager`
      Throws:
        `java.sql.SQLException` - If a database communication error occurs
      See Also:
        `EventManager.close()`

    - #### isConnected

          public boolean isConnected()

      Specified by:
        `isConnected` in interface `EventManager`
      Returns:
        `true` when connected and able to listen for events
      See Also:
        `EventManager.connect()`, `EventManager.disconnect()`

    - #### setUser

          public void setUser​(java.lang.String user)

      Specified by:
        `setUser` in interface `AttachmentProperties`
      Parameters:
        `user` - Name of the user to authenticate to the server.

    - #### getUser

          public java.lang.String getUser()

      Specified by:
        `getUser` in interface `AttachmentProperties`
      Returns:
        Name of the user to authenticate to the server.

    - #### setPassword

          public void setPassword​(java.lang.String password)

      Specified by:
        `setPassword` in interface `AttachmentProperties`
      Parameters:
        `password` - Password to authenticate to the server.

    - #### getPassword

          public java.lang.String getPassword()

      Specified by:
        `getPassword` in interface `AttachmentProperties`
      Returns:
        Password to authenticate to the server.

    - #### getServerName

          public java.lang.String getServerName()

      Description copied from interface: `AttachmentProperties`
      Get the hostname or IP address of the Firebird server.
      Specified by:
        `getServerName` in interface `AttachmentProperties`
      Returns:
        Hostname or IP address of the server
      See Also:
        `AttachmentProperties.setServerName(String)`

    - #### setServerName

          public void setServerName​(java.lang.String serverName)

      Description copied from interface: `AttachmentProperties`
      Set the hostname or IP address of the Firebird server.

      When set to `null` (the default), the `databaseName` or `serviceName` is used as the full identification of the database host, port and database path/alias. Protocol implementations, for example `PURE_JAVA`, may default to `localhost` when this property is `null`, but `databaseName`/`serviceName` does not (seem to) contain a host name.

      Specified by:
        `setServerName` in interface `AttachmentProperties`
      Parameters:
        `serverName` - Hostname or IP address of the server

    - #### getPortNumber

          public int getPortNumber()

      Description copied from interface: `AttachmentProperties`
      Get the port number of the server.
      Specified by:
        `getPortNumber` in interface `AttachmentProperties`
      Returns:
        Port number of the server
      See Also:
        `AttachmentProperties.setPortNumber(int)`

    - #### setPortNumber

          public void setPortNumber​(int portNumber)

      Description copied from interface: `AttachmentProperties`
      Set the port number of the server.

      Defaults to `3050`. This property value will be ignored if `serverName` is `null`, unless the protocol implementation needs a hostname, but cannot find a hostname in `databaseName`/`serviceName`.

      Specified by:
        `setPortNumber` in interface `AttachmentProperties`
      Parameters:
        `portNumber` - Port number of the server
      See Also:
        `AttachmentProperties.setServerName(String)`

    - #### getDatabaseName

          public java.lang.String getDatabaseName()

      Description copied from interface: `EventManager`
      Get the database name.

      See `DatabaseConnectionProperties.getDatabaseName()` for details.

      Specified by:
        `getDatabaseName` in interface `EventManager`
      Returns:
        database name

    - #### setDatabaseName

          public void setDatabaseName​(java.lang.String databaseName)

      Description copied from interface: `EventManager`
      Set the database name.

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

      Specified by:
        `setDatabaseName` in interface `EventManager`
      Parameters:
        `databaseName` - database name

    - #### setDatabase

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

      Deprecated.
      Description copied from interface: `EventManager`
      Sets the database path or url for the connection to the database.
      Specified by:
        `setDatabase` in interface `EventManager`
      Parameters:
        `database` - path or url for the connection to the database.

    - #### getDatabase

          @Deprecated
          public java.lang.String getDatabase()

      Deprecated.
      Specified by:
        `getDatabase` in interface `EventManager`
      Returns:
        the database path or url for the connection to the database.

    - #### getHost

          @Deprecated
          public java.lang.String getHost()

      Deprecated.
      Specified by:
        `getHost` in interface `EventManager`
      Returns:
        the host for the connection to the database.

    - #### setHost

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

      Deprecated.
      Description copied from interface: `EventManager`
      Sets the host for the connection to the database.

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

      Specified by:
        `setHost` in interface `EventManager`
      Parameters:
        `host` - for the connection to the database.

    - #### getPort

          @Deprecated
          public int getPort()

      Deprecated.
      Specified by:
        `getPort` in interface `EventManager`
      Returns:
        the port for the connection to the database.

    - #### setPort

          @Deprecated
          public void setPort​(int port)

      Deprecated.
      Description copied from interface: `EventManager`
      Sets the port for the connection to the database.
      Specified by:
        `setPort` in interface `EventManager`
      Parameters:
        `port` - for the connection to the database.

    - #### getWireCryptAsEnum

          public WireCrypt getWireCryptAsEnum()

      Description copied from interface: `EventManager`
      Get the wire encryption level.
      Specified by:
        `getWireCryptAsEnum` in interface `EventManager`
      Returns:
        Wire encryption level

    - #### setWireCryptAsEnum

          public void setWireCryptAsEnum​(WireCrypt wireCrypt)

      Description copied from interface: `EventManager`
      Set the wire encryption level.
      Specified by:
        `setWireCryptAsEnum` in interface `EventManager`
      Parameters:
        `wireCrypt` - Wire encryption level (`null` not allowed)

    - #### getWireCrypt

          public java.lang.String getWireCrypt()

      Description copied from interface: `AttachmentProperties`
      Get the wire encryption level.
      Specified by:
        `getWireCrypt` in interface `AttachmentProperties`
      Returns:
        Wire encryption level

    - #### setWireCrypt

          public void setWireCrypt​(java.lang.String wireCrypt)

      Description copied from interface: `AttachmentProperties`
      Set the wire encryption level.

      Values are defined by `WireCrypt`, values are handled case insensitive. Invalid values will throw an exception.

      Specified by:
        `setWireCrypt` in interface `AttachmentProperties`
      Parameters:
        `wireCrypt` - Wire encryption level (`null` not allowed)

    - #### getDbCryptConfig

          public java.lang.String getDbCryptConfig()

      Description copied from interface: `AttachmentProperties`
      Get the database encryption plugin configuration.
      Specified by:
        `getDbCryptConfig` in interface `AttachmentProperties`
      Returns:
        Database encryption plugin configuration, meaning plugin specific

    - #### setDbCryptConfig

          public void setDbCryptConfig​(java.lang.String dbCryptConfig)

      Description copied from interface: `AttachmentProperties`
      Sets the database encryption plugin configuration.
      Specified by:
        `setDbCryptConfig` in interface `AttachmentProperties`
      Parameters:
        `dbCryptConfig` - Database encryption plugin configuration, meaning plugin specific

    - #### getAuthPlugins

          public java.lang.String getAuthPlugins()

      Description copied from interface: `AttachmentProperties`
      Get the list of authentication plugins to try.
      Specified by:
        `getAuthPlugins` in interface `AttachmentProperties`
      Returns:
        comma-separated list of authentication plugins

    - #### setAuthPlugins

          public void setAuthPlugins​(java.lang.String authPlugins)

      Description copied from interface: `AttachmentProperties`
      Sets the authentication plugins to try.

      Invalid names are skipped during authentication.

      Specified by:
        `setAuthPlugins` in interface `AttachmentProperties`
      Parameters:
        `authPlugins` - comma-separated list of authentication plugins

    - #### getWaitTimeout

          public long getWaitTimeout()

      Description copied from interface: `EventManager`
      Get the poll timeout in milliseconds of the async thread to check whether it was stopped or not.

      Default value is 1000 (1 second).

      Specified by:
        `getWaitTimeout` in interface `EventManager`
      Returns:
        wait timeout in milliseconds

    - #### setWaitTimeout

          public void setWaitTimeout​(long waitTimeout)

      Description copied from interface: `EventManager`
      Set the poll timeout in milliseconds of the async thread to check whether it was stopped or not.

      Default value is 1000 (1 second).

      Specified by:
        `setWaitTimeout` in interface `EventManager`
      Parameters:
        `waitTimeout` - wait timeout in milliseconds

    - #### addEventListener

          public void addEventListener​(java.lang.String eventName,
                                       EventListener listener)
                                throws java.sql.SQLException

      Description copied from interface: `EventManager`
      Register an EventListener that will be called when an event occurs.
      Specified by:
        `addEventListener` in interface `EventManager`
      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

          public void removeEventListener​(java.lang.String eventName,
                                          EventListener listener)
                                   throws java.sql.SQLException

      Description copied from interface: `EventManager`
      Remove an EventListener for a given event.
      Specified by:
        `removeEventListener` in interface `EventManager`
      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

          public int waitForEvent​(java.lang.String eventName)
                           throws java.lang.InterruptedException,
                                  java.sql.SQLException

      Description copied from interface: `EventManager`
      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.

      Specified by:
        `waitForEvent` in interface `EventManager`
      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

          public int waitForEvent​(java.lang.String eventName,
                                  int timeout)
                           throws java.lang.InterruptedException,
                                  java.sql.SQLException

      Description copied from interface: `EventManager`
      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.

      Specified by:
        `waitForEvent` in interface `EventManager`
      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

    - #### getProperty

          public java.lang.String getProperty​(java.lang.String name)

      Description copied from interface: `BaseProperties`
      Retrieves a string property value by name.

      For properties with an explicit default, this method should return the string presentation of that default, not `null`. For `int` or `boolean` the string equivalent is returned.

      Specified by:
        `getProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
      Returns:
        Value of the property, or `null` when not set or not a known property

    - #### setProperty

          public void setProperty​(java.lang.String name,
                                  java.lang.String value)

      Description copied from interface: `BaseProperties`
      Sets a property by name.

      This method can be used to set all defined properties, but also properties not known by Jaybird. When setting `int` or `boolean` properties, the appropriate conversions are applied. Using `null` will reset to the default value. For `boolean` properties, an empty string is taken to mean `true`.

      Specified by:
        `setProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
        `value` - Property value (use `null` to apply default)

    - #### getIntProperty

          public java.lang.Integer getIntProperty​(java.lang.String name)

      Description copied from interface: `BaseProperties`
      Retrieves an `int` property value by name.

      For properties with an explicit default, this method should return the integer presentation of that default. For implementation simplicity, it is allowed to convert any string property to `int` instead of checking if something is actually an `int` property

      Specified by:
        `getIntProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
      Returns:
        Integer with value of the property, or `null` when not set

    - #### setIntProperty

          public void setIntProperty​(java.lang.String name,
                                     java.lang.Integer value)

      Description copied from interface: `BaseProperties`
      Sets an `int` property by name.

      For implementation simplicity, it is allowed to also set string properties. The value set will be the string equivalent.

      Specified by:
        `setIntProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
        `value` - Property value (use `null` to apply default)

    - #### getBooleanProperty

          public java.lang.Boolean getBooleanProperty​(java.lang.String name)

      Description copied from interface: `BaseProperties`
      Retrieves a `boolean` property value by name.

      For properties with an explicit default, this method should return the boolean presentation of that default. For implementation simplicity, it is allowed to convert any string property to `boolean` instead of checking if something is actually an `int` property

      Specified by:
        `getBooleanProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
      Returns:
        Integer with value of the property, or `null` when not set

    - #### setBooleanProperty

          public void setBooleanProperty​(java.lang.String name,
                                         java.lang.Boolean value)

      Description copied from interface: `BaseProperties`
      Sets a `boolean` property by name.

      For implementation simplicity, it is allowed to also set string properties. The value set will be the string equivalent.

      Specified by:
        `setBooleanProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
        `value` - Property value (use `null` to apply default)

    - #### connectionPropertyValues

          public java.util.Map<ConnectionProperty,​java.lang.Object> connectionPropertyValues()

      Description copied from interface: `BaseProperties`
      An unmodifiable view on the connection properties held by this BaseProperties implementation.

      Be aware, implementations can have additional properties that are not mapped from `ConnectionProperty`. Such properties will need to be retrieved in an implementation-specific manner.

      Specified by:
        `connectionPropertyValues` in interface `BaseProperties`
      Returns:
        An unmodifiable view on the property values held in this properties instance