Package org.firebirdsql.gds.ng

## Interface FbService

- All Superinterfaces:
    `java.lang.AutoCloseable`, `ExceptionListenable`, `FbAttachment`
  All Known Subinterfaces:
    `FbWireService`
  All Known Implementing Classes:
    `AbstractFbService`, `AbstractFbWireService`, `JnaService`, `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

    All Methods Instance Methods Abstract Methods
    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 Detail

    - #### 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 java.sql.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:
        `java.sql.SQLException` - For errors retrieving or transforming the response.

    - #### getServiceInfo

          byte[] getServiceInfo​(ServiceParameterBuffer serviceParameterBuffer,
                                ServiceRequestBuffer serviceRequestBuffer,
                                int maxBufferLength)
                         throws java.sql.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:
        `java.sql.SQLException` - For errors retrieving the information.

    - #### startServiceAction

          void startServiceAction​(ServiceRequestBuffer serviceRequestBuffer)
                           throws java.sql.SQLException

      Starts a service action.
      Parameters:
        `serviceRequestBuffer` - Service action request details
      Throws:
        `java.sql.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