Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng

# Interface FbAttachment

All Superinterfaces:
  `AutoCloseable`, `ExceptionListenable`

All Known Subinterfaces:
  `FbDatabase`, `FbService`, `FbWireAttachment`, `FbWireDatabase`, `FbWireService`

All Known Implementing Classes:
  `AbstractFbAttachment`, `AbstractFbDatabase`, `AbstractFbService`, `AbstractFbWireDatabase`, `AbstractFbWireService`, `V10Database`, `V10Service`, `V11Database`, `V12Database`, `V13Database`, `V15Database`, `V16Database`, `V18Database`, `V19Database`

public interface FbAttachment extends AutoCloseable, ExceptionListenable
Connection to a Firebird server (to a database or service).

All methods defined in this interface and the direct descendants `FbDatabase` and `FbService` are required to notify all `SQLException` thrown from the methods defined in this interface, and those exceptions notified by all `ExceptionListenable` implementations created from them.

Since:
  3.0
Author:
  Mark Rotteveel

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `attach()`
  Attach to the attachment type.
  `void`
  `close()`
  Detaches and closes the connection.
  `void`
  `forceClose()`
  Forces the connection to close without proper detach or cleanup.
  `DatatypeCoder`
  `getDatatypeCoder()`
  `Encoding`
  `getEncoding()`
  `IEncodingFactory`
  `getEncodingFactory()`
  `int`
  `getHandle()`
  `int`
  `getNetworkTimeout()`
  Gets the current network timeout for this attachment.
  `GDSServerVersion`
  `getServerVersion()`
  `boolean`
  `isAttached()`
  Current attachment status.
  `boolean`
  `isLockedByCurrentThread()`
  Queries if the lock is held by the current thread.
  `void`
  `setNetworkTimeout(int milliseconds)`
  Sets the network timeout for this attachment.
  `LockCloseable`
  `withLock()`
  Locks the lock with `Lock.lock()` (or equivalent).

  ### Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

  `addExceptionListener, removeExceptionListener`

- ## Method Details

  - ### attach

    void attach() throws SQLException
    Attach to the attachment type.
    Throws:
      `SQLException`

  - ### close

    void close() throws SQLException
    Detaches and closes the connection.
    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `SQLException` - If not currently connected, or another problem occurred detaching.

  - ### forceClose

    void forceClose() throws SQLException
    Forces the connection to close without proper detach or cleanup.

    If a given implementation does not support this, then this method should call `close()`.

    Throws:
      `SQLException` - For problems closing the connection.

  - ### getHandle

    int getHandle()
    Returns:
      The attachment handle value

  - ### getServerVersion

    GDSServerVersion getServerVersion()
    Returns:
      Firebird version string

  - ### isAttached

    boolean isAttached()
    Current attachment status.
    Returns:
      `true` if connected to the server and attached to a database or service, `false` otherwise.

  - ### getEncodingFactory

    IEncodingFactory getEncodingFactory()
    Returns:
      The `IEncodingFactory` for this connection

  - ### getEncoding

    Encoding getEncoding()
    Returns:
      The connection encoding (should be the same as returned from calling `IEncodingFactory.getDefaultEncoding()` on the result of `getEncodingFactory()`).

  - ### getDatatypeCoder

    DatatypeCoder getDatatypeCoder()
    Returns:
      The `DatatypeCoder` for this database implementation.

  - ### setNetworkTimeout

    void setNetworkTimeout(int milliseconds) throws SQLException
    Sets the network timeout for this attachment.
    Parameters:
      `milliseconds` - Timeout in milliseconds; 0 means no timeout. If the attachment doesn't support milliseconds, it should round up to the nearest second.
    Throws:
      `SQLException` - If this attachment is closed, the value of `milliseconds` is smaller than 0, or if setting the timeout fails.
      `SQLFeatureNotSupportedException` - If this attachment doesn't support (changing) the network timeout.

  - ### getNetworkTimeout

    int getNetworkTimeout() throws SQLException
    Gets the current network timeout for this attachment.
    Returns:
      Timeout in milliseconds, 0 means no timeout
    Throws:
      `SQLException` - If this attachment is closed
      `SQLFeatureNotSupportedException` - If this attachment doesn't support network timeout

  - ### withLock

    LockCloseable withLock()
    Locks the lock with `Lock.lock()` (or equivalent).

    The returned `LockClosable` can be used to unlock, preferably for use in a try-with-resources.

    Returns:
      lock closeable which unlocks the lock on close

  - ### isLockedByCurrentThread

    boolean isLockedByCurrentThread()
    Queries if the lock is held by the current thread.
    Returns:
      `true` if current thread holds this lock and `false` otherwise
    See Also:
      - `ReentrantLock.isHeldByCurrentThread()`