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

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