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
`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` - DOCUMENT ME!

#### Blob

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

Creates an updatable BLOB that can update in-place (not implemented yet).

Parameters:
  `data` - DOCUMENT ME!
  `creatorResultSetToSet` - DOCUMENT ME!
  `columnIndexToSet` - DOCUMENT ME!

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