-
- 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 Summary
All 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
-
length
long 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 theBLOBSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
-
getBytes
byte[] 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 theBLOBvalue to be extracted; the first byte is at position 1length- 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 theBLOBvalue; if pos is less than 1 or length is less than 0SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
- See Also:
setBytes(long, byte[])
-
getBinaryStream
InputStream 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 theBLOBvalueSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
- See Also:
setBinaryStream(long)
-
position
long 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 searchstart- 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 theBLOBor if start is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
-
position
long 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- theBlobobject designating theBLOBvalue for which to searchstart- the position in theBLOBvalue 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 theBLOBvalue or if start is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
-
setBytes
int 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 theBLOBobject at which to start writing; the first position is 1bytes- the array of bytes to be written to theBLOBvalue that thisBlobobject represents- Returns:
- the number of bytes written
- Throws:
SQLException- if there is an error accessing theBLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
- See Also:
getBytes(long, int)
-
setBytes
int 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 theBLOBobject at which to start writing; the first position is 1bytes- the array of bytes to be written to thisBLOBobjectoffset- the offset into the arraybytesat which to start reading the bytes to be setlen- the number of bytes to be written to theBLOBvalue from the array of bytesbytes- Returns:
- the number of bytes written
- Throws:
SQLException- if there is an error accessing theBLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
- See Also:
getBytes(long, int)
-
setBinaryStream
OutputStream 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 theBLOBvalue 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 theBLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
- See Also:
getBinaryStream()
-
truncate
void 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 theBLOBvalue that thisBlobobject represents should be truncated- Throws:
SQLException- if there is an error accessing theBLOBvalue or if len is less than 0SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
-
free
void 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 resourcesSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.6
-
getBinaryStream
InputStream 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 theBlobis at position 1.length- the length in bytes of the partial value to be retrieved- Returns:
InputStreamthrough which the partialBlobvalue can be read.- Throws:
SQLException- if pos is less than 1 or if pos is greater than the number of bytes in theBlobor if pos + length is greater than the number of bytes in theBlobSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.6
-
-