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
`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