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

# Interface FbWireOperations

All Known Implementing Classes:
  `AbstractWireOperations`, `V10WireOperations`, `V11WireOperations`, `V13WireOperations`, `V15WireOperations`, `V16WireOperations`, `V18WireOperations`, `V19WireOperations`

public interface FbWireOperations
Common connection operations shared by database and service handles

Since:
  3.0
Author:
  Mark Rotteveel

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `FbWireOperations.ProcessAttachCallback`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `authReceiveResponse(FbWireAttachment.AcceptPacket acceptPacket, DbCryptCallback dbCryptCallback, FbWireOperations.ProcessAttachCallback processAttachCallback)`
  Receive authentication response from the server.
  `default void`
  `completeDeferredActions()`
  Completes pending deferred actions.
  `void`
  `consumePackets(int numberOfResponses, WarningMessageCallback warningCallback)`
  Consumes packets notifying for warnings, but ignoring exceptions thrown from the packet.
  `default void`
  `enqueueDeferredAction(DeferredAction deferredAction)`
  Enqueue a deferred action.
  `XdrStreamAccess`
  `getXdrStreamAccess()`
  `void`
  `handleCryptKeyCallback(DbCryptCallback dbCryptCallback)`
  Handles the database encryption key callback.
  `default void`
  `processDeferredActions()`
  Processes any deferred actions.
  `void`
  `processResponse(Response response)`
  `void`
  `processResponseWarnings(Response response, WarningMessageCallback warningCallback)`
  Checks if the response included a warning and signals that warning to the WarningMessageCallback.
  `GenericResponse`
  `readGenericResponse(WarningMessageCallback callback)`
  Convenience method to read a Response to a GenericResponse
  `int`
  `readNextOperation()`
  Reads the next operation code, after processing deferred packets.
  `Response`
  `readOperationResponse(int operationCode, WarningMessageCallback callback)`
  Reads the response from the server when the operation code has already been read.
  `Response`
  `readResponse(WarningMessageCallback callback)`
  Reads the response from the server.
  `SqlResponse`
  `readSqlResponse(WarningMessageCallback callback)`
  Convenience method to read a Response to a SqlResponse
  `SQLException`
  `readStatusVector()`
  Process the status vector and returns the associated `SQLException` instance.
  `void`
  `setNetworkTimeout(int milliseconds)`
  Sets the network timeout for this attachment.
  `void`
  `writeDirect(byte[] data)`
  Writes directly to the `OutputStream` of the underlying connection.

- ## Method Details

  - ### getXdrStreamAccess

    XdrStreamAccess getXdrStreamAccess()
    Returns:
      Instance of `XdrStreamAccess` for this service.

  - ### readStatusVector

    SQLException readStatusVector() throws SQLException
    Process the status vector and returns the associated `SQLException` instance.

    NOTE: This method returns the SQLException read from the status vector, and only throws SQLException when an error occurs processing the status vector.

    Returns:
      SQLException from the status vector
    Throws:
      `SQLException` - for errors reading or processing the status vector

  - ### readResponse

    Response readResponse(WarningMessageCallback callback) throws SQLException, IOException
    Reads the response from the server.
    Parameters:
      `callback` - Callback object for warnings, `null` for default callback
    Returns:
      `Response` read.
    Throws:
      `SQLException` - For errors returned from the server, or when attempting to read
      `IOException` - For errors reading the response from the connection.

  - ### readNextOperation

    int readNextOperation() throws IOException
    Reads the next operation code, after processing deferred packets.

    In general, calling `readResponse(WarningMessageCallback)` or one of the specific `readXXXResponse` methods should be preferred to read the response code and the response body. Use this method only for reading custom responses, or if you need to process the response in a way that is not possible with `readResponse(WarningMessageCallback)`.

    Returns:
      next operation
    Throws:
      `IOException` - for errors reading the operation from the connection
    Since:
      6

  - ### readOperationResponse

    Response readOperationResponse(int operationCode, WarningMessageCallback callback) throws SQLException, IOException
    Reads the response from the server when the operation code has already been read.
    Parameters:
      `operationCode` - The operation code
      `callback` - Callback object for warnings, `null` for default callback
    Returns:
      `Response` read.
    Throws:
      `SQLException` - For errors returned from the server, or when attempting to read
      `IOException` - For errors reading the response from the connection.
    See Also:
      - `readResponse(WarningMessageCallback)`

  - ### readGenericResponse

    GenericResponse readGenericResponse(WarningMessageCallback callback) throws SQLException, IOException
    Convenience method to read a Response to a GenericResponse
    Parameters:
      `callback` - Callback object for warnings, `null` for default callback
    Returns:
      GenericResponse
    Throws:
      `SQLException` - For errors returned from the server, or when attempting to read.
      `IOException` - For errors reading the response from the connection.

  - ### readSqlResponse

    SqlResponse readSqlResponse(WarningMessageCallback callback) throws SQLException, IOException
    Convenience method to read a Response to a SqlResponse
    Parameters:
      `callback` - Callback object for warnings, `null` for default callback
    Returns:
      SqlResponse
    Throws:
      `SQLException` - For errors returned from the server, or when attempting to read.
      `IOException` - For errors reading the response from the connection.

  - ### handleCryptKeyCallback

    void handleCryptKeyCallback(DbCryptCallback dbCryptCallback) throws IOException, SQLException
    Handles the database encryption key callback.
    Parameters:
      `dbCryptCallback` - Database encryption callback plugin
    Throws:
      `IOException` - For errors reading data from the socket
      `SQLException` - For database errors
      `SQLFeatureNotSupportedException` - If this protocol version does not support crypt key callbacks
    Since:
      4.0

  - ### enqueueDeferredAction

    default void enqueueDeferredAction(DeferredAction deferredAction) throws SQLException
    Enqueue a deferred action.

    FbDatabase implementations that do not support deferred actions are allowed to throw an `UnsupportedOperationException` (which the default implementation does).

    Parameters:
      `deferredAction` - Deferred action
    Throws:
      `SQLException` - for errors forcing handling of oversized queue using `op_ping` (or `op_batch_sync`)

  - ### completeDeferredActions

    default void completeDeferredActions() throws SQLException
    Completes pending deferred actions.

    Wire protocol implementations that do not support deferred actions should simply do nothing.

    Throws:
      `SQLException` - for errors forcing ping/batch sync
    Since:
      6

  - ### consumePackets

    void consumePackets(int numberOfResponses, WarningMessageCallback warningCallback)
    Consumes packets notifying for warnings, but ignoring exceptions thrown from the packet.

    This method should only be used inside the implementation if either packets need to be ignored, or to ensure that there is no backlog of packets (eg when an exception occurs during processing of multiple package responses).

    Parameters:
      `numberOfResponses` - Number of responses to consume.
      `warningCallback` - Callback for warnings

  - ### processDeferredActions

    default void processDeferredActions()
    Processes any deferred actions. Protocol versions that do not support deferred actions should simply do nothing.

    WARNING: If the server queues deferred responses, and expects an operation (e.g. `op_batch_sync`, `op_batch_exec` or `op_ping`) to actual send those responses, this method may block indefinitely.

  - ### processResponse

    void processResponse(Response response) throws SQLException
    Parameters:
      `response` - Response to process
    Throws:
      `SQLException` - For errors returned from the server.

  - ### processResponseWarnings

    void processResponseWarnings(Response response, WarningMessageCallback warningCallback)
    Checks if the response included a warning and signals that warning to the WarningMessageCallback.
    Parameters:
      `response` - Response to process

  - ### writeDirect

    void writeDirect(byte[] data) throws IOException
    Writes directly to the `OutputStream` of the underlying connection.

    Use of this method might lead to hard to find race conditions in the protocol. It is currently only used to allow `FbDatabase.cancelOperation(int)` to work.

    Parameters:
      `data` - Data to write
    Throws:
      `IOException` - If there is no socket, the socket is closed, or for errors writing to the socket.
    See Also:
      - `WireConnection.writeDirect(byte[])`

  - ### authReceiveResponse

    void authReceiveResponse(FbWireAttachment.AcceptPacket acceptPacket, DbCryptCallback dbCryptCallback, FbWireOperations.ProcessAttachCallback processAttachCallback) throws IOException, SQLException
    Receive authentication response from the server.

    This method is only relevant for protocol V13 or higher.

    Parameters:
      `acceptPacket` - Packet with `op_cond_accept` data, or `null` when the data should be read from the connection.
      `dbCryptCallback` - Database encryption callback (ignored by protocols v12 and lower)
      `processAttachCallback` - Callback for processing the final attach response
    Throws:
      `IOException` - For errors reading the response from the connection.
      `SQLException` - For errors returned from the server, or when attempting to read.

  - ### 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.