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