Package org.firebirdsql.gds.ng

## Interface FbAttachment

- All Superinterfaces:
    `java.lang.AutoCloseable`, `ExceptionListenable`
  All Known Subinterfaces:
    `FbDatabase`, `FbService`, `FbWireAttachment`, `FbWireDatabase`, `FbWireService`, `JnaAttachment`
  All Known Implementing Classes:
    `AbstractFbAttachment`, `AbstractFbDatabase`, `AbstractFbService`, `AbstractFbWireDatabase`, `AbstractFbWireService`, `JnaDatabase`, `JnaService`, `V10Database`, `V10Service`, `V11Database`, `V12Database`, `V13Database`, `V15Database`, `V16Database`, `V18Database`

      public interface FbAttachment
      extends java.lang.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

    All Methods Instance Methods Abstract Methods
    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 Detail

    - #### attach

          void attach()
               throws java.sql.SQLException

      Attach to the attachment type.
      Throws:
        `java.sql.SQLException`

    - #### close

          void close()
              throws java.sql.SQLException

      Detaches and closes the connection.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.sql.SQLException` - If not currently connected, or another problem occurred detaching.

    - #### forceClose

          void forceClose()
                   throws java.sql.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:
        `java.sql.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 java.sql.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:
        `java.sql.SQLException` - If this attachment is closed, the value of `milliseconds` is smaller than 0, or if setting the timeout fails.
        `java.sql.SQLFeatureNotSupportedException` - If this attachment doesn't support (changing) the network timeout.

    - #### getNetworkTimeout

          int getNetworkTimeout()
                         throws java.sql.SQLException

      Gets the current network timeout for this attachment.
      Returns:
        Timeout in milliseconds, 0 means no timeout
      Throws:
        `java.sql.SQLException` - If this attachment is closed
        `java.sql.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()`