Module org.firebirdsql.jaybird
Package org.firebirdsql.jdbc

# Class FBBlob

java.lang.Object
org.firebirdsql.jdbc.FBBlob

All Implemented Interfaces:
  `Blob`, `TransactionListener`, `FirebirdBlob`

@InternalApi public final class FBBlob extends Object implements FirebirdBlob, TransactionListener
Firebird implementation of `Blob`.

This class is internal API of Jaybird. Future versions may radically change, move, or make inaccessible this type. For the public API, refer to the `Blob` and `FirebirdBlob` interfaces.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `FBBlob.Config`
  Standard configuration for blobs.

  ## Nested classes/interfaces inherited from interface org.firebirdsql.jdbc.FirebirdBlob

  `FirebirdBlob.BlobInputStream, FirebirdBlob.BlobOutputStream`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FBBlob(GDSHelper c, long blobId, FBObjectListener.BlobListener blobListener, FBBlob.Config config)`
  Create instance of this class to access existing Blob.
  `FBBlob(GDSHelper c, FBObjectListener.BlobListener blobListener, FBBlob.Config config)`
  Create new Blob instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `copyBytes(byte[] bytes, int pos, int len)`
  `void`
  `copyCharacterStream(Reader reader)`
  Copy data from a character stream into this Blob.
  `void`
  `copyCharacterStream(Reader reader, long length)`
  Copy data from a character stream into this Blob.
  `void`
  `copyCharacterStream(Reader reader, long length, Encoding encoding)`
  Copy data from a character stream into this Blob.
  `void`
  `copyCharacterStream(Reader reader, Encoding encoding)`
  Copy data from a character stream into this Blob.
  `void`
  `copyStream(InputStream inputStream)`
  Copy the contents of an `InputStream` into this Blob.
  `void`
  `copyStream(InputStream inputStream, long length)`
  Copy the contents of an `InputStream` into this Blob.
  `static FBBlob.Config`
  `createConfig(int subType, boolean useStreamBlob, int blobBufferSize, DatatypeCoder datatypeCoder)`
  Create a blob configuration.
  `static FBBlob.Config`
  `createConfig(int subType, DatabaseConnectionProperties connectionProperties, DatatypeCoder datatypeCoder)`
  Creates a blob configuration from a subtype and connection properties and datatype coder.
  `static FBBlob.Config`
  `createConfig(FieldDescriptor fieldDescriptor, DatabaseConnectionProperties connectionProperties)`
  Creates a blob configuration from a field descriptor and connection properties.
  `FBBlob`
  `detach()`
  Detach this blob.
  `void`
  `free()`
  `InputStream`
  `getBinaryStream()`
  `InputStream`
  `getBinaryStream(long pos, long length)`
  `long`
  `getBlobId()`
  Get the identifier for this `Blob`
  `byte[]`
  `getBytes()`
  Gets the byte content of this blob as a byte array.
  `byte[]`
  `getBytes(long pos, int length)`
  `byte[]`
  `getInfo(byte[] items, int bufferLength)`
  Get information about this Blob.
  `boolean`
  `isSegmented()`
  Check if blob is segmented.
  `long`
  `length()`
  `long`
  `position(byte[] pattern, long start)`
  `long`
  `position(Blob pattern, long start)`
  `OutputStream`
  `setBinaryStream(long pos)`
  `int`
  `setBytes(long pos, byte[] bytes)`
  `int`
  `setBytes(long pos, byte[] bytes, int offset, int len)`
  `void`
  `transactionStateChanged(FbTransaction transaction, TransactionState newState, TransactionState previousState)`
  Signals that the transaction state changed.
  `void`
  `truncate(long len)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### FBBlob

    public FBBlob(GDSHelper c, FBObjectListener.BlobListener blobListener, FBBlob.Config config)
    Create new Blob instance. This constructor creates a new fresh Blob, only writing to the Blob is allowed.
    Parameters:
      `c` - connection that will be used to write data to blob
      `blobListener` - Blob listener instance
      `config` - blob configuration (cannot be `null`)
    Since:
      5

  - ### FBBlob

    public FBBlob(GDSHelper c, long blobId, FBObjectListener.BlobListener blobListener, FBBlob.Config config)
    Create instance of this class to access existing Blob.
    Parameters:
      `c` - connection that will be used to access Blob.
      `blobId` - ID of the Blob.
      `blobListener` - blob listener instance
      `config` - blob configuration (cannot be `null`)
    Since:
      5

- ## Method Details

  - ### free

    public void free() throws SQLException
    Specified by:
      `free` in interface `Blob`
    Throws:
      `SQLException`

  - ### getBinaryStream

    public InputStream getBinaryStream(long pos, long length) throws SQLException
    Specified by:
      `getBinaryStream` in interface `Blob`
    Throws:
      `SQLException`

  - ### getInfo

    public byte[] getInfo(byte[] items, int bufferLength) throws SQLException
    Get information about this Blob. This method should be considered as temporary because it provides access to low-level API. More information on how to use the API can be found in "API Guide".
    Parameters:
      `items` - items in which we are interested
      `bufferLength` - buffer where information will be stored
    Returns:
      array of bytes containing information about this Blob
    Throws:
      `SQLException` - if something went wrong

  - ### length

    public long length() throws SQLException
    Specified by:
      `length` in interface `Blob`
    Throws:
      `SQLException`

  - ### isSegmented

    public boolean isSegmented() throws SQLException
    Description copied from interface: `FirebirdBlob`
    Check if blob is segmented. If Blob is segmented, you cannot use `FirebirdBlob.BlobInputStream.seek(int)` method.
    Specified by:
      `isSegmented` in interface `FirebirdBlob`
    Returns:
      `true` if this blob is segmented, otherwise `false`
    Throws:
      `SQLException`

  - ### detach

    public FBBlob detach() throws SQLException
    Description copied from interface: `FirebirdBlob`
    Detach this blob. This method creates new instance of the same blob database object that is not under result set control. When result set is closed, all associated resources are also released, including open blob streams. This method creates a new instance of blob object with the same blob ID that can be used even when result set is closed.

    Note, detached blob will not remember the stream position of this object. This means that you cannot start reading data from the blob, then detach it, and then continue reading. Reading from detached blob will begin at the blob start.

    Specified by:
      `detach` in interface `FirebirdBlob`
    Returns:
      instance of `FirebirdBlob` that is not under result set control.
    Throws:
      `SQLException` - if Blob cannot be detached.

  - ### getBytes

    public byte[] getBytes(long pos, int length) throws SQLException
    Specified by:
      `getBytes` in interface `Blob`
    Throws:
      `SQLException`

  - ### getBytes

    public byte[] getBytes() throws SQLException
    Description copied from interface: `FirebirdBlob`
    Gets the byte content of this blob as a byte array.
    Specified by:
      `getBytes` in interface `FirebirdBlob`
    Returns:
      byte array with blob content (may return `null` for certain cached blobs)
    Throws:
      `SQLException` - for database access errors, or if the blob size exceeds the maximum safe array size (i.e. `Integer.MAX_VALUE` - 8)

  - ### getBinaryStream

    public InputStream getBinaryStream() throws SQLException
    Specified by:
      `getBinaryStream` in interface `Blob`
    Throws:
      `SQLException`

  - ### position

    public long position(byte[] pattern, long start) throws SQLException
    Specified by:
      `position` in interface `Blob`
    Throws:
      `SQLException`

  - ### position

    public long position(Blob pattern, long start) throws SQLException
    Specified by:
      `position` in interface `Blob`
    Throws:
      `SQLException`

  - ### truncate

    public void truncate(long len) throws SQLException
    Specified by:
      `truncate` in interface `Blob`
    Throws:
      `SQLException`

  - ### setBytes

    public int setBytes(long pos, byte[] bytes) throws SQLException
    Specified by:
      `setBytes` in interface `Blob`
    Throws:
      `SQLException`

  - ### setBytes

    public int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException
    Specified by:
      `setBytes` in interface `Blob`
    Throws:
      `SQLException`

  - ### setBinaryStream

    public OutputStream setBinaryStream(long pos) throws SQLException
    Specified by:
      `setBinaryStream` in interface `Blob`
    Throws:
      `SQLException`

  - ### getBlobId

    public long getBlobId() throws SQLException
    Get the identifier for this `Blob`
    Returns:
      This `Blob`'s identifier
    Throws:
      `SQLException` - if a database access error occurs

  - ### copyBytes

    public void copyBytes(byte[] bytes, int pos, int len) throws SQLException
    Throws:
      `SQLException`

  - ### copyStream

    public void copyStream(InputStream inputStream, long length) throws SQLException
    Copy the contents of an `InputStream` into this Blob.

    Calling with length `-1` is equivalent to calling `copyStream(InputStream)`, and will copy the whole stream.

    Parameters:
      `inputStream` - the stream from which data will be copied
      `length` - The maximum number of bytes to read from the InputStream, `-1` to read whole stream
    Throws:
      `SQLException` - if a database access error occurs

  - ### copyStream

    public void copyStream(InputStream inputStream) throws SQLException
    Copy the contents of an `InputStream` into this Blob. Unlike the `copyStream(InputStream, long)` method, this one copies bytes until the EOF is reached.
    Parameters:
      `inputStream` - the stream from which data will be copied
    Throws:
      `SQLException` - if a database access error occurs

  - ### copyCharacterStream

    public void copyCharacterStream(Reader reader, long length, Encoding encoding) throws SQLException
    Copy data from a character stream into this Blob.

    Calling with length `-1` is equivalent to calling `copyCharacterStream(Reader, Encoding)`.

    Parameters:
      `reader` - the source of data to copy
      `length` - The maximum number of bytes to copy, or `-1` to read the whole stream
      `encoding` - The encoding used in the character stream
    Throws:
      `SQLException`
    See Also:
      - `copyCharacterStream(Reader, long)`

  - ### copyCharacterStream

    public void copyCharacterStream(Reader reader, long length) throws SQLException
    Copy data from a character stream into this Blob. This method uses the encoding from the blob config (field character set for subtype TEXT, if known, otherwise connection character set).

    Calling with length `-1` is equivalent to calling `copyCharacterStream(Reader)`.

    Parameters:
      `reader` - the source of data to copy
      `length` - The maximum number of bytes to copy, or `-1` to read the whole stream
    Throws:
      `SQLException`
    Since:
      5

  - ### copyCharacterStream

    public void copyCharacterStream(Reader reader, Encoding encoding) throws SQLException
    Copy data from a character stream into this Blob. Unlike the `copyCharacterStream(Reader, long, Encoding)` method, this one copies bytes until the EOF is reached.
    Parameters:
      `reader` - the source of data to copy
      `encoding` - The encoding used in the character stream
    Throws:
      `SQLException`
    See Also:
      - `copyCharacterStream(Reader)`

  - ### copyCharacterStream

    public void copyCharacterStream(Reader reader) throws SQLException
    Copy data from a character stream into this Blob. Unlike the `copyCharacterStream(Reader, long)` method, this one copies bytes until the EOF is reached. This method uses the encoding from the blob config (field character set for subtype TEXT, if known, otherwise connection character set).
    Parameters:
      `reader` - the source of data to copy
    Throws:
      `SQLException`
    Since:
      5

  - ### transactionStateChanged

    public void transactionStateChanged(FbTransaction transaction, TransactionState newState, TransactionState previousState)
    Description copied from interface: `TransactionListener`
    Signals that the transaction state changed.
    Specified by:
      `transactionStateChanged` in interface `TransactionListener`
    Parameters:
      `transaction` - `FbTransaction` that changed state

  - ### createConfig

    public static FBBlob.Config createConfig(FieldDescriptor fieldDescriptor, DatabaseConnectionProperties connectionProperties)
    Creates a blob configuration from a field descriptor and connection properties.
    Parameters:
      `fieldDescriptor` - field descriptor
      `connectionProperties` - connection properties
    Returns:
      field based blob configuration
    Since:
      5

  - ### createConfig

    public static FBBlob.Config createConfig(int subType, DatabaseConnectionProperties connectionProperties, DatatypeCoder datatypeCoder)
    Creates a blob configuration from a subtype and connection properties and datatype coder.
    Parameters:
      `subType` - blob subtype (e.g. `ISCConstants.BLOB_SUB_TYPE_BINARY` or `ISCConstants.BLOB_SUB_TYPE_TEXT`)
      `connectionProperties` - connection properties
      `datatypeCoder` - data type coder for the connection character set
    Returns:
      field based blob configuration
    Since:
      5

  - ### createConfig

    public static FBBlob.Config createConfig(int subType, boolean useStreamBlob, int blobBufferSize, DatatypeCoder datatypeCoder)
    Create a blob configuration.
    Parameters:
      `subType` - blob subtype (e.g. `ISCConstants.BLOB_SUB_TYPE_BINARY` or `ISCConstants.BLOB_SUB_TYPE_TEXT`)
      `useStreamBlob` - `true` use stream blob, `false` use segmented blob
      `blobBufferSize` - blob buffer size
      `datatypeCoder` - data type coder for the connection character set
    Returns:
      generic blob configuration
    Since:
      5