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 and 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()`

Copyright © 2001-2025 Jaybird (Firebird JDBC) team. All rights reserved.