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

# Interface FbService

All Superinterfaces:
  `AutoCloseable`, `ExceptionListenable`, `FbAttachment`

All Known Subinterfaces:
  `FbWireService`

All Known Implementing Classes:
  `AbstractFbService`, `AbstractFbWireService`, `V10Service`

public interface FbService extends FbAttachment
Connection handle to a service.

All methods defined in this interface 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`
  `addServiceListener(ServiceListener listener)`
  Adds a `ServiceListener` instance to this database.
  `ServiceParameterBuffer`
  `createServiceParameterBuffer()`
  Creates an empty `ServiceParameterBuffer`.
  `ServiceRequestBuffer`
  `createServiceRequestBuffer()`
  `int`
  `getHandle()`
  `byte[]`
  `getServiceInfo(ServiceParameterBuffer serviceParameterBuffer, ServiceRequestBuffer serviceRequestBuffer, int maxBufferLength)`
  Performs a service info request (service query.
  `<T> T`
  `getServiceInfo(ServiceParameterBuffer serviceParameterBuffer, ServiceRequestBuffer serviceRequestBuffer, int bufferLength, InfoProcessor<T> infoProcessor)`
  Request service info (service query).
  `void`
  `removeServiceListener(ServiceListener listener)`
  Removes a `ServiceListener` instance from this database.
  `void`
  `startServiceAction(ServiceRequestBuffer serviceRequestBuffer)`
  Starts a service action.

  ### Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

  `addExceptionListener, removeExceptionListener`

  ### Methods inherited from interface org.firebirdsql.gds.ng.FbAttachment

  `attach, close, forceClose, getDatatypeCoder, getEncoding, getEncodingFactory, getNetworkTimeout, getServerVersion, isAttached, isLockedByCurrentThread, setNetworkTimeout, withLock`

- ## Method Details

  - ### getHandle

    int getHandle()
    Specified by:
      `getHandle` in interface `FbAttachment`
    Returns:
      The service handle value

  - ### getServiceInfo

    <T> T getServiceInfo(ServiceParameterBuffer serviceParameterBuffer, ServiceRequestBuffer serviceRequestBuffer, int bufferLength, InfoProcessor<T> infoProcessor) throws SQLException
    Request service info (service query).
    Parameters:
      `serviceParameterBuffer` - Service parameters
      `serviceRequestBuffer` - Service request info
      `bufferLength` - Response buffer length to use
      `infoProcessor` - Implementation of `InfoProcessor` to transform the info response
    Returns:
      Transformed info response of type T
    Throws:
      `SQLException` - For errors retrieving or transforming the response.

  - ### getServiceInfo

    byte[] getServiceInfo(ServiceParameterBuffer serviceParameterBuffer, ServiceRequestBuffer serviceRequestBuffer, int maxBufferLength) throws SQLException
    Performs a service info request (service query.
    Parameters:
      `serviceParameterBuffer` - Service parameters (can be null)
      `serviceRequestBuffer` - Service request info
      `maxBufferLength` - Maximum response buffer length to use
    Returns:
      The response buffer (note: length is the actual length of the response, not `maxBufferLength`
    Throws:
      `SQLException` - For errors retrieving the information.

  - ### startServiceAction

    void startServiceAction(ServiceRequestBuffer serviceRequestBuffer) throws SQLException
    Starts a service action.
    Parameters:
      `serviceRequestBuffer` - Service action request details
    Throws:
      `SQLException` - For errors starting the service action.

  - ### createServiceParameterBuffer

    ServiceParameterBuffer createServiceParameterBuffer()
    Creates an empty `ServiceParameterBuffer`.

    Attach expects a service parameter buffer to have the version as the first item. This needs to be added explicitly.

    Returns:
      Service

  - ### createServiceRequestBuffer

    ServiceRequestBuffer createServiceRequestBuffer()
    Returns:
      An empty service request buffer

  - ### addServiceListener

    void addServiceListener(ServiceListener listener)
    Adds a `ServiceListener` instance to this database.
    Parameters:
      `listener` - Database listener

  - ### removeServiceListener

    void removeServiceListener(ServiceListener listener)
    Removes a `ServiceListener` instance from this database.
    Parameters:
      `listener` - Database Listener