com.mysql.jdbc
Class Blob

java.lang.Object
  extended by 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
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
 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