org.firebirdsql.jdbc

## Class FBBlob

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

- All Implemented Interfaces:
    java.sql.Blob, TransactionListener, FirebirdBlob, Synchronizable

      public class FBBlob
      extends java.lang.Object
      implements FirebirdBlob, TransactionListener, Synchronizable

  Firebird implementation of `Blob`.

- - ### Nested Class Summary

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

      `FirebirdBlob.BlobInputStream, FirebirdBlob.BlobOutputStream`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte[]` | `BLOB_LENGTH_REQUEST`
    `static boolean` | `SEGMENTED`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `copyBytes(byte[] bytes, int pos, int len)`
    `void` | `copyCharacterStream(java.io.Reader reader, long length, java.lang.String encoding)` Deprecated. Method signature will change incompatibly in Jaybird 4
    `void` | `copyCharacterStream(java.io.Reader reader, java.lang.String encoding)` Deprecated. Method signature will change incompatibly in Jaybird 4
    `void` | `copyStream(java.io.InputStream inputStream)` Copy the contents of an `InputStream` into this Blob.
    `void` | `copyStream(java.io.InputStream inputStream, long length)` Copy the contents of an `InputStream` into this Blob.
    `FirebirdBlob` | `detach()` Detach this blob.
    `void` | `free()` This method frees the `Blob` object and releases the resources that it holds.
    `java.io.InputStream` | `getBinaryStream()`
    `java.io.InputStream` | `getBinaryStream(long pos, long length)` Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.
    `long` | `getBlobId()` Get the identifier for this `Blob`
    `byte[]` | `getBytes(long pos, int length)` Retrieves all or part of the `BLOB` value that this `Blob` object represents, as an array of bytes.
    `GDSHelper` | `getGdsHelper()`
    `byte[]` | `getInfo(byte[] items, int buffer_length)` Get information about this Blob.
    `java.lang.Object` | `getSynchronizationObject()` Get synchronization object.
    `boolean` | `isSegmented()` Check if blob is segmented.
    `long` | `length()` Returns the number of bytes in the `BLOB` value designated by this `Blob` object.
    `long` | `position(java.sql.Blob pattern, long start)`
    `long` | `position(byte[] pattern, long start)`
    `java.io.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`

- - ### Field Detail

    - #### SEGMENTED

          public static final boolean SEGMENTED

      See Also:
        Constant Field Values

    - #### BLOB_LENGTH_REQUEST

          public static final byte[] BLOB_LENGTH_REQUEST

  - ### Constructor Detail

    - #### FBBlob

          public FBBlob(GDSHelper c,
                FBObjectListener.BlobListener blobListener)

      Create new Blob instance. This constructor creates 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

    - #### FBBlob

          public FBBlob(GDSHelper c)

      Create new Blob instance. This constructor creates new fresh Blob, only writing to the Blob is allowed.
      Parameters:
        `c` - connection that will be used to write data to blob.

    - #### FBBlob

          public FBBlob(GDSHelper c,
                long blob_id,
                FBObjectListener.BlobListener blobListener)

      Create instance of this class to access existing Blob.
      Parameters:
        `c` - connection that will be used to access Blob.
        `blob_id` - ID of the Blob.
        `blobListener` - Blob listener instance

    - #### FBBlob

          public FBBlob(GDSHelper c,
                long blob_id)

      Create instance of this class to access existing Blob.
      Parameters:
        `c` - connection that will be used to access Blob.
        `blob_id` - ID of the Blob.

  - ### Method Detail

    - #### getSynchronizationObject

          public final java.lang.Object getSynchronizationObject()

      Description copied from interface: `Synchronizable`
      Get synchronization object.
      Specified by:
        `getSynchronizationObject` in interface `Synchronizable`
      Returns:
        object, cannot be `null`.

    - #### free

          public void free()
                    throws java.sql.SQLException

      This method frees the `Blob` object and releases the resources that it holds. The object is invalid once the `free` method is called.

      After `free` has been called, any attempt to invoke a method other than `free` will result in a `SQLException` being thrown. If `free` is called multiple times, the subsequent calls to `free` are treated as a no-op.

      Specified by:
        `free` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException` - if an error occurs releasing the Blob's resources
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### getBinaryStream

          public java.io.InputStream getBinaryStream(long pos,
                                            long length)
                                              throws java.sql.SQLException

      Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.
      Specified by:
        `getBinaryStream` in interface `java.sql.Blob`
      Parameters:
        `pos` - the offset to the first byte of the partial value to be retrieved. The first byte in the `Blob` is at position 1
        `length` - the length in bytes of the partial value to be retrieved
      Returns:
        `InputStream` through which the partial `Blob` value can be read.
      Throws:
        `java.sql.SQLException` - if pos is less than 1 or if pos is greater than the number of bytes in the `Blob` or if pos + length is greater than the number of bytes in the `Blob`
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### getInfo

          public byte[] getInfo(byte[] items,
                       int buffer_length)
                         throws java.sql.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.
        `buffer_length` - buffer where information will be stored.
      Returns:
        array of bytes containing information about this Blob.
      Throws:
        `java.sql.SQLException` - if something went wrong.

    - #### length

          public long length()
                      throws java.sql.SQLException

      Returns the number of bytes in the `BLOB` value designated by this `Blob` object.
      Specified by:
        `length` in interface `java.sql.Blob`
      Returns:
        length of the `BLOB` in bytes
      Throws:
        `java.sql.SQLException` - if there is an error accessing the length of the `BLOB`
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.2

    - #### isSegmented

          public boolean isSegmented()
                              throws java.sql.SQLException

      Check if blob is segmented.
      Specified by:
        `isSegmented` in interface `FirebirdBlob`
      Returns:
        `true` if this blob is segmented, otherwise `false`
      Throws:
        `java.sql.SQLException` - if something went wrong.

    - #### detach

          public FirebirdBlob detach()
                              throws java.sql.SQLException

      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 an 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 `FBBlob` that is not under result set control.
      Throws:
        `java.sql.SQLException` - if Blob cannot be detached.

    - #### getBytes

          public byte[] getBytes(long pos,
                        int length)
                          throws java.sql.SQLException

      Retrieves all or part of the `BLOB` value that this `Blob` object represents, as an array of bytes. This `byte` array contains up to `length` consecutive bytes starting at position `pos`.
      Specified by:
        `getBytes` in interface `java.sql.Blob`
      Parameters:
        `pos` - the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1
        `length` - the number of consecutive bytes to be copied; the value for length must be 0 or greater
      Returns:
        a byte array containing up to `length` consecutive bytes from the `BLOB` value designated by this `Blob` object, starting with the byte at position `pos`
      Throws:
        `java.sql.SQLException` - if there is an error accessing the `BLOB` value; if pos is less than 1 or length is less than 0
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.2
      See Also:
        `setBytes(long, byte[])`

    - #### getBinaryStream

          public java.io.InputStream getBinaryStream()
                                              throws java.sql.SQLException

      Specified by:
        `getBinaryStream` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### position

          public long position(byte[] pattern,
                      long start)
                        throws java.sql.SQLException

      Specified by:
        `position` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### position

          public long position(java.sql.Blob pattern,
                      long start)
                        throws java.sql.SQLException

      Specified by:
        `position` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### truncate

          public void truncate(long len)
                        throws java.sql.SQLException

      Specified by:
        `truncate` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### setBytes

          public int setBytes(long pos,
                     byte[] bytes)
                       throws java.sql.SQLException

      Specified by:
        `setBytes` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### setBytes

          public int setBytes(long pos,
                     byte[] bytes,
                     int offset,
                     int len)
                       throws java.sql.SQLException

      Specified by:
        `setBytes` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### setBinaryStream

          public java.io.OutputStream setBinaryStream(long pos)
                                               throws java.sql.SQLException

      Specified by:
        `setBinaryStream` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`

    - #### getBlobId

          public long getBlobId()
                         throws java.sql.SQLException

      Get the identifier for this `Blob`
      Returns:
        This `Blob`'s identifier
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### copyBytes

          public void copyBytes(byte[] bytes,
                       int pos,
                       int len)
                         throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getGdsHelper

          public GDSHelper getGdsHelper()

    - #### copyStream

          public void copyStream(java.io.InputStream inputStream,
                        long length)
                          throws java.sql.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:
        `java.sql.SQLException` - if a database access error occurs

    - #### copyStream

          public void copyStream(java.io.InputStream inputStream)
                          throws java.sql.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:
        `java.sql.SQLException` - if a database access error occurs

    - #### copyCharacterStream

          @Deprecated
          public void copyCharacterStream(java.io.Reader reader,
                                            long length,
                                            java.lang.String encoding)
                                   throws java.sql.SQLException

      Deprecated. Method signature will change incompatibly in Jaybird 4
      Copy data from a character stream into this Blob.

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

      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:
        `java.sql.SQLException`

    - #### copyCharacterStream

          @Deprecated
          public void copyCharacterStream(java.io.Reader reader,
                                            java.lang.String encoding)
                                   throws java.sql.SQLException

      Deprecated. Method signature will change incompatibly in Jaybird 4
      Copy data from a character stream into this Blob. Unlike the `copyCharacterStream(Reader, long, String)` )} 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:
        `java.sql.SQLException`

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

Copyright © 2001-2021 Jaybird (Firebird JDBC/JCA) team. All rights reserved.