IfxBblob
Date: 2015-03-03

com.informix.jdbc

## Class IfxBblob

- java.lang.Object
- - com.informix.jdbc.IfxBblob

- All Implemented Interfaces:
    java.sql.Blob

      public class IfxBblob
      extends java.lang.Object
      implements java.sql.Blob

  By default, a Blob is a transaction duration reference to a binary large object. By default, a Blob is implemented using a LOCATOR(blob) internally.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IfxBblob()` Creates an IfxBblob instance.
    `IfxBblob(java.sql.Connection conn, byte[] buffer)` Creates an IfxBblob instance with a given connection and a buffer containing data.
    `IfxBblob(java.sql.Connection conn, byte[] buffer, IfxLobDescriptor loDesc)` Creates an IfxBblob instance with a given connection and a buffer containing data and a specified lob descriptor.
    `IfxBblob(java.sql.Connection conn, byte[] buffer, java.lang.String sbspaceName)` Creates an IfxBblob instance with a given connection and a buffer containing data and a specified smart blob space.
    `IfxBblob(java.sql.Connection conn, java.io.InputStream fin, int length)` Creates an IfxBblob instance with a given connection, an inputStream and number of bytes to write.
    `IfxBblob(java.sql.Connection conn, java.io.InputStream fin, int length, IfxLobDescriptor loDesc)` Creates an IfxBblob instance with a given connection, an inputStream, number of bytes to write and a specified lob descriptor.
    `IfxBblob(java.sql.Connection conn, java.io.InputStream fin, int length, java.lang.String sbspaceName)` Creates an IfxBblob instance with a given connection, an inputStream and number of bytes to write to a specified smart blob space.
    `IfxBblob(com.informix.jdbc.IfxConnection connection, IfxLocator locator)` Creates an IfxBblob instance with a given connection and a locator.
    `IfxBblob(IfxLocator locator)` Creates an IfxBblob instance with the given locator.
    `IfxBblob(java.io.InputStream fin)` Creates an IfxBblob instance with the given input stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` This method will release the resources used by the object
    `void` | `free()`
    `java.io.InputStream` | `getBinaryStream()` Retrieves the entire smart large object as a stream.
    `java.io.InputStream` | `getBinaryStream(long pos, long length)`
    `byte[]` | `getBytes(long position, int length)` Returns a copy of the contents of the smart large object at the requested position.
    `IfxLocator` | `getLocator()` Gets the smart large object locator from the blob object.
    `IfxLoStat` | `getLoStat()` This method returns an IfxLoStat object, which provides statistical information, such as the last access time, the last update status time, the last modification time, and the reference count of the smart large object.
    `long` | `length()` Gets the length of the binary smart large object in bytes.
    `long` | `position(java.sql.Blob pattern, long start)` Determines the byte position at which the given pattern occurs.
    `long` | `position(byte[] pattern, long start)` Determines the byte position at which the given byte pattern occurs.
    `long` | `seek(long offset, int whence)` This method sets the position for the next read and write operation of the smart large object.
    `java.io.OutputStream` | `setBinaryStream(long pos)` Retrieves a stream that can be used to write to the BLOB value that this Blob object represents.
    `void` | `setBinaryStream(long position, java.io.InputStream fin, int length)` Writes binary stream of data from an InputStream to an already existing smart large blob object.
    `int` | `setBytes(long position, byte[] buffer)` Writes binary data from a buffer to an existing smart large blob object.
    `int` | `setBytes(long position, byte[] bytes, int offset, int len)` Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written.
    `void` | `truncate(long size)` This method truncates the smart large object at the given position.
    `long` | `where()` This method returns the current seek position within the large object.

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

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

- - ### Constructor Detail

    - #### IfxBblob

          public IfxBblob()

      Creates an IfxBblob instance. An IfxBblob object created using this constructor cannot be used for accessing the Blob.

    - #### IfxBblob

          public IfxBblob(IfxLocator locator)

      Creates an IfxBblob instance with the given locator. An IfxBblob object created using this constructor cannot be used for accessing the Blob.
      Parameters:
        `locator` - the locator that references the smart large object

    - #### IfxBblob

          public IfxBblob(com.informix.jdbc.IfxConnection connection,
                  IfxLocator locator)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection and a locator. The object will be opened in the database.
      Parameters:
        `connection` - the IfxConnection object
        `locator` - the locator that references the smart large object
      Throws:
        `java.sql.SQLException`

    - #### IfxBblob

          public IfxBblob(java.io.InputStream fin)

      Creates an IfxBblob instance with the given input stream. An IfxBblob object created using this constructor cannot be used for accessing the Blob.
      Parameters:
        `fin` - the input stream to use for this smart large object

    - #### IfxBblob

          public IfxBblob(java.sql.Connection conn,
                  java.io.InputStream fin,
                  int length)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection, an inputStream and number of bytes to write.
      Parameters:
        `conn` - the Connection object
        `fin` - the input stream from which the data will be written into the smart large object
        `length` - number of bytes to be written
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

    - #### IfxBblob

          public IfxBblob(java.sql.Connection conn,
                  java.io.InputStream fin,
                  int length,
                  java.lang.String sbspaceName)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection, an inputStream and number of bytes to write to a specified smart blob space.
      Parameters:
        `conn` - the Connection object.
        `fin` - the input stream from which the data will be written into the smart large object
        `length` - number of bytes to be written
        `sbspaceName` - specified smart blob space name
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

    - #### IfxBblob

          public IfxBblob(java.sql.Connection conn,
                  java.io.InputStream fin,
                  int length,
                  IfxLobDescriptor loDesc)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection, an inputStream, number of bytes to write and a specified lob descriptor.
      Parameters:
        `conn` - the Connection object
        `fin` - the input stream from which the data will be written into the smart large object
        `length` - number of bytes to be written
        `loDesc` - user created lob descriptor
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

    - #### IfxBblob

          public IfxBblob(java.sql.Connection conn,
                  byte[] buffer)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection and a buffer containing data.
      Parameters:
        `conn` - the Connection object
        `buffer` - from which the data will be written to smart blob
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

    - #### IfxBblob

          public IfxBblob(java.sql.Connection conn,
                  byte[] buffer,
                  java.lang.String sbspaceName)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection and a buffer containing data and a specified smart blob space.
      Parameters:
        `conn` - the Connection object
        `buffer` - from which the data will be written to smart blob
        `sbspaceName` - specified smart blob space name
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

    - #### IfxBblob

          public IfxBblob(java.sql.Connection conn,
                  byte[] buffer,
                  IfxLobDescriptor loDesc)
                   throws java.sql.SQLException

      Creates an IfxBblob instance with a given connection and a buffer containing data and a specified lob descriptor.
      Parameters:
        `conn` - the Connection object
        `buffer` - from which the data will be written to smart blob
        `loDesc` - user defined lob descriptor
      Throws:
        `java.sql.SQLException` - if object instance cannot be instantiated

  - ### Method Detail

    - #### getLocator

          public IfxLocator getLocator()
                                throws java.sql.SQLException

      Gets the smart large object locator from the blob object.
      Returns:
        the smart large object locator.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### length

          public long length()
                      throws java.sql.SQLException

      Gets the length of the binary smart large object in bytes.
      Specified by:
        `length` in interface `java.sql.Blob`
      Returns:
        the length of the smart large object in bytes.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the length of the BLOB

    - #### getBytes

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

      Returns a copy of the contents of the smart large object at the requested position. This method can be used to fetch data from a blob. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used. This method can be used when an IfxBblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxBblob(IfxConnection connection, IfxLocator locator) IfxBblob(IfxConnection conn, InputStream fin, int length) IfxBblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxBblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxBblob(IfxConnection conn, byte[] buffer) IfxBblob(IfxConnection conn, byte[] buffer, String sbspaceName) IfxBblob(IfxConnection conn, byte[] buffer, IfxLobDescriptor loDesc)
      Specified by:
        `getBytes` in interface `java.sql.Blob`
      Parameters:
        `position` - the offset from the start of the smart large object
        `length` - the number of consecutive bytes to be copied
      Returns:
        a byte array containing a portion of the smart large object.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### getBinaryStream

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

      Retrieves the entire smart large object as a stream. This method can be used to fetch data from a blob. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used. This method can be used when an IfxBblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxBblob(IfxConnection connection, IfxLocator locator) IfxBblob(IfxConnection conn, InputStream fin, int length) IfxBblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxBblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxBblob(IfxConnection conn, byte[] buffer) IfxBblob(IfxConnection conn, byte[] buffer, String sbspaceName) IfxBblob(IfxConnection conn, byte[] buffer, IfxLobDescriptor loDesc)
      Specified by:
        `getBinaryStream` in interface `java.sql.Blob`
      Returns:
        a stream containing the smart large object data.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### position

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

      Determines the byte position at which the given byte pattern occurs. This method can be used to find a match for a pattern within a blob. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used. This method can be used when an IfxBblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxBblob(IfxConnection connection, IfxLocator locator) IfxBblob(IfxConnection conn, InputStream fin, int length) IfxBblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxBblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxBblob(IfxConnection conn, byte[] buffer) IfxBblob(IfxConnection conn, byte[] buffer, String sbspaceName) IfxBblob(IfxConnection conn, byte[] buffer, IfxLobDescriptor loDesc)
      Specified by:
        `position` in interface `java.sql.Blob`
      Parameters:
        `pattern` - the pattern to search for
        `start` - the position at which to begin searching
      Returns:
        the position at which the pattern appears, or -1 if the pattern does not appear in the smart large object.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### position

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

      Determines the byte position at which the given pattern occurs. This method can be used to find a match for a pattern within a blob. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used. This method can be used when an IfxBblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxBblob(IfxConnection connection, IfxLocator locator) IfxBblob(IfxConnection conn, InputStream fin, int length) IfxBblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxBblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxBblob(IfxConnection conn, byte[] buffer) IfxBblob(IfxConnection conn, byte[] buffer, String sbspaceName) IfxBblob(IfxConnection conn, byte[] buffer, IfxLobDescriptor loDesc)
      Specified by:
        `position` in interface `java.sql.Blob`
      Parameters:
        `pattern` - the pattern to search for
        `start` - the position at which to begin searching
      Returns:
        the position at which the pattern appears, or -1 if the pattern does not appear in the smart large object.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### setBinaryStream

          public void setBinaryStream(long position,
                             java.io.InputStream fin,
                             int length)
                               throws java.sql.SQLException

      Writes binary stream of data from an InputStream to an already existing smart large blob object. This method can be used to write data into a blob. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used. This method can be used when an IfxBblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxBblob(IfxConnection connection, IfxLocator locator) IfxBblob(IfxConnection conn, InputStream fin, int length) IfxBblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxBblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxBblob(IfxConnection conn, byte[] buffer) IfxBblob(IfxConnection conn, byte[] buffer, String sbspaceName) IfxBblob(IfxConnection conn, byte[] buffer, IfxLobDescriptor loDesc)
      Parameters:
        `postion` - at which smart large object will be written
        `fin` - InputStream
        `length` - number of bytes to be written from the input stream
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### setBytes

          public int setBytes(long position,
                     byte[] buffer)
                       throws java.sql.SQLException

      Writes binary data from a buffer to an existing smart large blob object. This method can be used to write data into a blob. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used. This method can be used when an IfxBblob object gets created out of a resultSet.getBlob() statement or using the following constructors; IfxBblob(IfxConnection connection, IfxLocator locator) IfxBblob(IfxConnection conn, InputStream fin, int length) IfxBblob(IfxConnection conn, InputStream fin, int length, String sbspaceName) IfxBblob(IfxConnection conn, InputStream fin, int length, IfxLobDescriptor loDesc) IfxBblob(IfxConnection conn, byte[] buffer) IfxBblob(IfxConnection conn, byte[] buffer, String sbspaceName) IfxBblob(IfxConnection conn, byte[] buffer, IfxLobDescriptor loDesc)
      Specified by:
        `setBytes` in interface `java.sql.Blob`
      Parameters:
        `postion` - at which smart large object will be written
        `buffer` - contain the data
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### close

          public void close()
                     throws java.sql.SQLException

      This method will release the resources used by the object
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### seek

          public long seek(long offset,
                  int whence)
                    throws java.sql.SQLException

      This method sets the position for the next read and write operation of the smart large object. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used.
      Parameters:
        `offset` - From the location specified in the whence parameter
        `whence` - Define the offset value more specifically; LO_SEEK_SET, from begining; LO_SEEK_CUR, relative from current position; LO_SEEK_END, from the end.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### where

          public long where()
                     throws java.sql.SQLException

      This method returns the current seek position within the large object. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### getLoStat

          public IfxLoStat getLoStat()
                              throws java.sql.SQLException

      This method returns an IfxLoStat object, which provides statistical information, such as the last access time, the last update status time, the last modification time, and the reference count of the smart large object. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used.
      Returns:
        IfxLoStat object.
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### truncate

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

      This method truncates the smart large object at the given position. If the position given is beyond the length of the smart large object it ignores the request. In case IfxBblob object is created with following constructors; IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used.
      Specified by:
        `truncate` in interface `java.sql.Blob`
      Parameters:
        `size` - at which the truncation will occur
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB

    - #### setBytes

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

      Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written. Writing starts at position pos in the BLOB value; len bytes from the given byte array are written. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used.
      Specified by:
        `setBytes` in interface `java.sql.Blob`
      Parameters:
        `position` - the position in the BLOB object at which to start writing
        `bytes` - the array of bytes to be written to this BLOB object
        `offset` - the offset into the array bytes at which to start reading the bytes to be set
        `len` - the number of bytes to be written to the BLOB value from the array of bytes bytes
      Returns:
        the number of bytes written
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB value

    - #### setBinaryStream

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

      Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos. If the IfxBblob object is created with following constructors: IfxBblob() or IfxBblob(IfxLocaor locator) or IfxBblob(InputStream fin) this method cannot be used.
      Specified by:
        `setBinaryStream` in interface `java.sql.Blob`
      Parameters:
        `pos` - the position in the BLOB value at which to start writing
      Returns:
        a java.io.OutputStream object to which data can be written
      Throws:
        `java.sql.SQLException` - if there is an error accessing the BLOB value

    - #### free

          public void free()
                    throws java.sql.SQLException

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

    - #### getBinaryStream

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

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