- 
- All Known Implementing Classes:
- SerialBlob
 
 public interface BlobThe representation (mapping) in the Java™ programming language of an SQLBLOBvalue. An SQLBLOBis a built-in type that stores a Binary Large Object as a column value in a row of a database table. By default drivers implementBlobusing an SQLlocator(BLOB), which means that aBlobobject contains a logical pointer to the SQLBLOBdata rather than the data itself. ABlobobject is valid for the duration of the transaction in which is was created.Methods in the interfaces ResultSet,CallableStatement, andPreparedStatement, such asgetBlobandsetBloballow a programmer to access an SQLBLOBvalue. TheBlobinterface provides methods for getting the length of an SQLBLOB(Binary Large Object) value, for materializing aBLOBvalue on the client, and for determining the position of a pattern of bytes within aBLOBvalue. In addition, this interface has methods for updating aBLOBvalue.All methods on the Blobinterface must be fully implemented if the JDBC driver supports the data type.- Since:
- 1.2
 
- 
- 
Method SummaryAll Methods Instance Methods Abstract Methods Modifier and Type Method Description voidfree()This method frees theBlobobject and releases the resources that it holds.InputStreamgetBinaryStream()Retrieves theBLOBvalue designated by thisBlobinstance as a stream.InputStreamgetBinaryStream(long pos, long length)Returns anInputStreamobject that contains a partialBlobvalue, starting with the byte specified by pos, which is length bytes in length.byte[]getBytes(long pos, int length)Retrieves all or part of theBLOBvalue that thisBlobobject represents, as an array of bytes.longlength()Returns the number of bytes in theBLOBvalue designated by thisBlobobject.longposition(byte[] pattern, long start)Retrieves the byte position at which the specified byte arraypatternbegins within theBLOBvalue that thisBlobobject represents.longposition(Blob pattern, long start)Retrieves the byte position in theBLOBvalue designated by thisBlobobject at whichpatternbegins.OutputStreamsetBinaryStream(long pos)Retrieves a stream that can be used to write to theBLOBvalue that thisBlobobject represents.intsetBytes(long pos, byte[] bytes)Writes the given array of bytes to theBLOBvalue that thisBlobobject represents, starting at positionpos, and returns the number of bytes written.intsetBytes(long pos, byte[] bytes, int offset, int len)Writes all or part of the givenbytearray to theBLOBvalue that thisBlobobject represents and returns the number of bytes written.voidtruncate(long len)Truncates theBLOBvalue that thisBlobobject represents to belenbytes in length.
 
- 
- 
- 
Method Detail- 
lengthlong length() throws SQLExceptionReturns the number of bytes in theBLOBvalue designated by thisBlobobject.- Returns:
- length of the BLOBin bytes
- Throws:
- SQLException- if there is an error accessing the length of the- BLOB
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.2
 
 - 
getBytesbyte[] getBytes(long pos, int length) throws SQLExceptionRetrieves all or part of theBLOBvalue that thisBlobobject represents, as an array of bytes. Thisbytearray contains up tolengthconsecutive bytes starting at positionpos.- Parameters:
- pos- the ordinal position of the first byte in the- BLOBvalue 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 lengthconsecutive bytes from theBLOBvalue designated by thisBlobobject, starting with the byte at positionpos
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue; if pos is less than 1 or length is less than 0
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.2
- See Also:
- setBytes(long, byte[])
 
 - 
getBinaryStreamInputStream getBinaryStream() throws SQLException Retrieves theBLOBvalue designated by thisBlobinstance as a stream.- Returns:
- a stream containing the BLOBdata
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.2
- See Also:
- setBinaryStream(long)
 
 - 
positionlong position(byte[] pattern, long start) throws SQLExceptionRetrieves the byte position at which the specified byte arraypatternbegins within theBLOBvalue that thisBlobobject represents. The search forpatternbegins at positionstart.- Parameters:
- pattern- the byte array for which to search
- start- the position at which to begin searching; the first position is 1
- Returns:
- the position at which the pattern appears, else -1
- Throws:
- SQLException- if there is an error accessing the- BLOBor if start is less than 1
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.2
 
 - 
positionlong position(Blob pattern, long start) throws SQLException Retrieves the byte position in theBLOBvalue designated by thisBlobobject at whichpatternbegins. The search begins at positionstart.- Parameters:
- pattern- the- Blobobject designating the- BLOBvalue for which to search
- start- the position in the- BLOBvalue at which to begin searching; the first position is 1
- Returns:
- the position at which the pattern begins, else -1
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue or if start is less than 1
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.2
 
 - 
setBytesint setBytes(long pos, byte[] bytes) throws SQLExceptionWrites the given array of bytes to theBLOBvalue that thisBlobobject represents, starting at positionpos, and returns the number of bytes written. The array of bytes will overwrite the existing bytes in theBlobobject starting at the positionpos. If the end of theBlobvalue is reached while writing the array of bytes, then the length of theBlobvalue will be increased to accommodate the extra bytes.Note: If the value specified for posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
- pos- the position in the- BLOBobject at which to start writing; the first position is 1
- bytes- the array of bytes to be written to the- BLOBvalue that this- Blobobject represents
- Returns:
- the number of bytes written
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue or if pos is less than 1
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.4
- See Also:
- getBytes(long, int)
 
 - 
setBytesint setBytes(long pos, byte[] bytes, int offset, int len) throws SQLExceptionWrites all or part of the givenbytearray to theBLOBvalue that thisBlobobject represents and returns the number of bytes written. Writing starts at positionposin theBLOBvalue;lenbytes from the given byte array are written. The array of bytes will overwrite the existing bytes in theBlobobject starting at the positionpos. If the end of theBlobvalue is reached while writing the array of bytes, then the length of theBlobvalue will be increased to accommodate the extra bytes.Note: If the value specified for posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
- pos- the position in the- BLOBobject at which to start writing; the first position is 1
- bytes- the array of bytes to be written to this- BLOBobject
- offset- the offset into the array- bytesat which to start reading the bytes to be set
- len- the number of bytes to be written to the- BLOBvalue from the array of bytes- bytes
- Returns:
- the number of bytes written
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue or if pos is less than 1
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.4
- See Also:
- getBytes(long, int)
 
 - 
setBinaryStreamOutputStream setBinaryStream(long pos) throws SQLException Retrieves a stream that can be used to write to theBLOBvalue that thisBlobobject represents. The stream begins at positionpos. The bytes written to the stream will overwrite the existing bytes in theBlobobject starting at the positionpos. If the end of theBlobvalue is reached while writing to the stream, then the length of theBlobvalue will be increased to accommodate the extra bytes.Note: If the value specified for posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
- pos- the position in the- BLOBvalue at which to start writing; the first position is 1
- Returns:
- a java.io.OutputStreamobject to which data can be written
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue or if pos is less than 1
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.4
- See Also:
- getBinaryStream()
 
 - 
truncatevoid truncate(long len) throws SQLExceptionTruncates theBLOBvalue that thisBlobobject represents to belenbytes in length.Note: If the value specified for posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
- len- the length, in bytes, to which the- BLOBvalue that this- Blobobject represents should be truncated
- Throws:
- SQLException- if there is an error accessing the- BLOBvalue or if len is less than 0
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.4
 
 - 
freevoid free() throws SQLException This method frees theBlobobject and releases the resources that it holds. The object is invalid once thefreemethod is called.After freehas been called, any attempt to invoke a method other thanfreewill result in anSQLExceptionbeing thrown. Iffreeis called multiple times, the subsequent calls tofreeare treated as a no-op.- Throws:
- SQLException- if an error occurs releasing the Blob's resources
- SQLFeatureNotSupportedException- if the JDBC driver does not support this method
- Since:
- 1.6
 
 - 
getBinaryStreamInputStream getBinaryStream(long pos, long length) throws SQLException Returns anInputStreamobject that contains a partialBlobvalue, starting with the byte specified by pos, which is length bytes in length.- Parameters:
- pos- the offset to the first byte of the partial value to be retrieved. The first byte in the- Blobis at position 1.
- length- the length in bytes of the partial value to be retrieved
- Returns:
- InputStreamthrough which the partial- Blobvalue can be read.
- Throws:
- SQLException- if pos is less than 1 or if pos is greater than the number of bytes in the- Blobor 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
 
 
- 
 
-