Blob
Date: 2018-05-01

com.mysql.jdbc

## Class Blob

- java.lang.Object
- - com.mysql.jdbc.Blob

- All Implemented Interfaces:
    OutputStreamWatcher, java.sql.Blob

      public class Blob
      extends java.lang.Object
      implements java.sql.Blob, OutputStreamWatcher

  The representation (mapping) in the JavaTM programming language of an SQL BLOB value. An SQL BLOB is a built-in type that stores a Binary Large Object as a column value in a row of a database table. The driver implements Blob using an SQL locator(BLOB), which means that a Blob object contains a logical pointer to the SQL BLOB data rather than the data itself. A Blob object is valid for the duration of the transaction in which is was created. Methods in the interfaces ResultSet, CallableStatement, and PreparedStatement, such as getBlob and setBlob allow a programmer to access an SQL BLOB value. The Blob interface provides methods for getting the length of an SQL BLOB (Binary Large Object) value, for materializing a BLOB value on the client, and for determining the position of a pattern of bytes within a BLOB value. This class is new in the JDBC 2.0 API.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Blob(byte[] data, ExceptionInterceptor exceptionInterceptor)` Creates a BLOB encapsulating the given binary data
    `Blob(byte[] data, ResultSetInternalMethods creatorResultSetToSet, int columnIndexToSet)` Creates an updatable BLOB that can update in-place (not implemented yet).
    `Blob(ExceptionInterceptor exceptionInterceptor)` Creates a Blob without data

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `free()` This method frees the `Blob` object and releases the resources that it holds.
    `java.io.InputStream` | `getBinaryStream()` Retrieves the BLOB designated by this Blob instance as a stream.
    `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.
    `byte[]` | `getBytes(long pos, int length)` Returns as an array of bytes, part or all of the BLOB value that this Blob object designates.
    `long` | `length()` Returns the number of bytes in the BLOB value designated by this Blob object.
    `long` | `position(java.sql.Blob pattern, long start)` Finds the position of the given pattern in this BLOB.
    `long` | `position(byte[] pattern, long start)`
    `java.io.OutputStream` | `setBinaryStream(long indexToWriteAt)`
    `int` | `setBytes(long writeAt, byte[] bytes)`
    `int` | `setBytes(long writeAt, byte[] bytes, int offset, int length)`
    `void` | `streamClosed(byte[] byteData)`
    `void` | `streamClosed(WatchableOutputStream out)` Called when the OutputStream being watched has .close() called
    `void` | `truncate(long len)` Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length.

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

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

- - ### Constructor Detail

    - #### Blob

          Blob(ExceptionInterceptor exceptionInterceptor)

      Creates a Blob without data

    - #### Blob

          Blob(byte[] data,
              ExceptionInterceptor exceptionInterceptor)

      Creates a BLOB encapsulating the given binary data
      Parameters:
        `data` -

    - #### Blob

          Blob(byte[] data,
              ResultSetInternalMethods creatorResultSetToSet,
              int columnIndexToSet)

      Creates an updatable BLOB that can update in-place (not implemented yet).
      Parameters:
        `data` -
        `creatorResultSetToSet` -
        `columnIndexToSet` -

  - ### Method Detail

    - #### getBinaryStream

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

      Retrieves the BLOB designated by this Blob instance as a stream.
      Specified by:
        `getBinaryStream` in interface `java.sql.Blob`
      Returns:
        this BLOB represented as a binary stream of bytes.
      Throws:
        `java.sql.SQLException` - if a database error occurs

    - #### getBytes

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

      Returns as an array of bytes, part or all of the BLOB value that this Blob object designates.
      Specified by:
        `getBytes` in interface `java.sql.Blob`
      Parameters:
        `pos` - where to start the part of the BLOB
        `length` - the length of the part of the BLOB you want returned.
      Returns:
        the bytes stored in the blob starting at position `pos` and having a length of `length`.
      Throws:
        `java.sql.SQLException` - if a database error occurs

    - #### 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:
        the length of this blob
      Throws:
        `java.sql.SQLException` - if a database error occurs

    - #### position

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

      Specified by:
        `position` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`
      See Also:
        `Blob.position(byte[], long)`

    - #### position

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

      Finds the position of the given pattern in this BLOB.
      Specified by:
        `position` in interface `java.sql.Blob`
      Parameters:
        `pattern` - the pattern to find
        `start` - where to start finding the pattern
      Returns:
        the position where the pattern is found in the BLOB, -1 if not found
      Throws:
        `java.sql.SQLException` - if a database error occurs

    - #### setBinaryStream

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

      Specified by:
        `setBinaryStream` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`
      See Also:
        `setBinaryStream(long)`

    - #### setBytes

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

      Specified by:
        `setBytes` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`
      See Also:
        `setBytes(long, byte[])`

    - #### setBytes

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

      Specified by:
        `setBytes` in interface `java.sql.Blob`
      Throws:
        `java.sql.SQLException`
      See Also:
        `setBytes(long, byte[], int, int)`

    - #### streamClosed

          public void streamClosed(byte[] byteData)

      See Also:
        `com.mysql.jdbc.OutputStreamWatcher#streamClosed(byte[])`

    - #### streamClosed

          public void streamClosed(WatchableOutputStream out)

      Description copied from interface: `OutputStreamWatcher`
      Called when the OutputStream being watched has .close() called
      Specified by:
        `streamClosed` in interface `OutputStreamWatcher`
      See Also:
        `com.mysql.jdbc.OutputStreamWatcher#streamClosed(byte[])`

    - #### truncate

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

      Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length.

      Note: If the value specified for `len` is greater then the length+1 of the `BLOB` value then the behavior is undefined. Some JDBC drivers may throw a `SQLException` while other drivers may support this operation.

      Specified by:
        `truncate` in interface `java.sql.Blob`
      Parameters:
        `len` - the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated
      Throws:
        `java.sql.SQLException` - if there is an error accessing the `BLOB` value or if len is less than 0
        `SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.4

    - #### 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
        `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`
        `SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6