/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.sql;
import java.io.InputStream;
The representation (mapping) in
the Java™ 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. By default drivers implement 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. In addition, this interface has methods for updating
a BLOB
value.
All methods on the Blob
interface must be fully implemented if the
JDBC driver supports the data type.
Since: 1.2
/**
* The representation (mapping) in
* the Java™ programming
* language of an SQL
* <code>BLOB</code> value. An SQL <code>BLOB</code> is a built-in type
* that stores a Binary Large Object as a column value in a row of
* a database table. By default drivers implement <code>Blob</code> using
* an SQL <code>locator(BLOB)</code>, which means that a
* <code>Blob</code> object contains a logical pointer to the
* SQL <code>BLOB</code> data rather than the data itself.
* A <code>Blob</code> object is valid for the duration of the
* transaction in which is was created.
*
* <P>Methods in the interfaces {@link ResultSet},
* {@link CallableStatement}, and {@link PreparedStatement}, such as
* <code>getBlob</code> and <code>setBlob</code> allow a programmer to
* access an SQL <code>BLOB</code> value.
* The <code>Blob</code> interface provides methods for getting the
* length of an SQL <code>BLOB</code> (Binary Large Object) value,
* for materializing a <code>BLOB</code> value on the client, and for
* determining the position of a pattern of bytes within a
* <code>BLOB</code> value. In addition, this interface has methods for updating
* a <code>BLOB</code> value.
* <p>
* All methods on the <code>Blob</code> interface must be fully implemented if the
* JDBC driver supports the data type.
*
* @since 1.2
*/
public interface Blob {
Returns the number of bytes in the BLOB
value
designated by this Blob
object.
Throws: - SQLException – if there is an error accessing the
length of the
BLOB
- SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns: length of the BLOB
in bytes Since: 1.2
/**
* Returns the number of bytes in the <code>BLOB</code> value
* designated by this <code>Blob</code> object.
* @return length of the <code>BLOB</code> in bytes
* @exception SQLException if there is an error accessing the
* length of the <code>BLOB</code>
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.2
*/
long length() throws SQLException;
Retrieves all or part of the BLOB
value that this Blob
object represents, as an array of
bytes. This byte
array contains up to length
consecutive bytes starting at position pos
.
Params: - pos – the ordinal position of the first byte in the
BLOB
value 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
Throws: - SQLException – if there is an error accessing the
BLOB
value; if pos is less than 1 or length is
less than 0 - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
See Also: Returns: a byte array containing up to length
consecutive bytes from the BLOB
value designated
by this Blob
object, starting with the
byte at position pos
Since: 1.2
/**
* Retrieves all or part of the <code>BLOB</code>
* value that this <code>Blob</code> object represents, as an array of
* bytes. This <code>byte</code> array contains up to <code>length</code>
* consecutive bytes starting at position <code>pos</code>.
*
* @param pos the ordinal position of the first byte in the
* <code>BLOB</code> value to be extracted; the first byte is at
* position 1
* @param length the number of consecutive bytes to be copied; the value
* for length must be 0 or greater
* @return a byte array containing up to <code>length</code>
* consecutive bytes from the <code>BLOB</code> value designated
* by this <code>Blob</code> object, starting with the
* byte at position <code>pos</code>
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value; if pos is less than 1 or length is
* less than 0
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @see #setBytes
* @since 1.2
*/
byte[] getBytes(long pos, int length) throws SQLException;
Retrieves the BLOB
value designated by this
Blob
instance as a stream.
Throws: - SQLException – if there is an error accessing the
BLOB
value - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
See Also: Returns: a stream containing the BLOB
data Since: 1.2
/**
* Retrieves the <code>BLOB</code> value designated by this
* <code>Blob</code> instance as a stream.
*
* @return a stream containing the <code>BLOB</code> data
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @see #setBinaryStream
* @since 1.2
*/
java.io.InputStream getBinaryStream () throws SQLException;
Retrieves the byte position at which the specified byte array
pattern
begins within the BLOB
value that this Blob
object represents. The
search for pattern
begins at position
start
.
Params: - pattern – the byte array for which to search
- start – the position at which to begin searching; the
first position is 1
Throws: - SQLException – if there is an error accessing the
BLOB
or if start is less than 1 - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns: the position at which the pattern appears, else -1 Since: 1.2
/**
* Retrieves the byte position at which the specified byte array
* <code>pattern</code> begins within the <code>BLOB</code>
* value that this <code>Blob</code> object represents. The
* search for <code>pattern</code> begins at position
* <code>start</code>.
*
* @param pattern the byte array for which to search
* @param start the position at which to begin searching; the
* first position is 1
* @return the position at which the pattern appears, else -1
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> or if start is less than 1
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.2
*/
long position(byte pattern[], long start) throws SQLException;
Retrieves the byte position in the BLOB
value
designated by this Blob
object at which
pattern
begins. The search begins at position
start
.
Params: - pattern – the
Blob
object designating
the BLOB
value for which to search - start – the position in the
BLOB
value
at which to begin searching; the first position is 1
Throws: - SQLException – if there is an error accessing the
BLOB
value or if start is less than 1 - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns: the position at which the pattern begins, else -1 Since: 1.2
/**
* Retrieves the byte position in the <code>BLOB</code> value
* designated by this <code>Blob</code> object at which
* <code>pattern</code> begins. The search begins at position
* <code>start</code>.
*
* @param pattern the <code>Blob</code> object designating
* the <code>BLOB</code> value for which to search
* @param start the position in the <code>BLOB</code> value
* at which to begin searching; the first position is 1
* @return the position at which the pattern begins, else -1
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value or if start is less than 1
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.2
*/
long position(Blob pattern, long start) throws SQLException;
// -------------------------- JDBC 3.0 -----------------------------------
Writes the given array of bytes to the BLOB
value that
this Blob
object represents, starting at position
pos
, and returns the number of bytes written.
The array of bytes will overwrite the existing bytes
in the Blob
object starting at the position
pos
. If the end of the Blob
value is reached
while writing the array of bytes, then the length of the Blob
value will be increased to accommodate the extra bytes.
Note: If the value specified for pos
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.
Params: - pos – the position in the
BLOB
object at which
to start writing; the first position is 1 - bytes – the array of bytes to be written to the
BLOB
value that this Blob
object represents
Throws: - SQLException – if there is an error accessing the
BLOB
value or if pos is less than 1 - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
See Also: Returns: the number of bytes written Since: 1.4
/**
* Writes the given array of bytes to the <code>BLOB</code> value that
* this <code>Blob</code> object represents, starting at position
* <code>pos</code>, and returns the number of bytes written.
* The array of bytes will overwrite the existing bytes
* in the <code>Blob</code> object starting at the position
* <code>pos</code>. If the end of the <code>Blob</code> value is reached
* while writing the array of bytes, then the length of the <code>Blob</code>
* value will be increased to accommodate the extra bytes.
* <p>
* <b>Note:</b> If the value specified for <code>pos</code>
* is greater then the length+1 of the <code>BLOB</code> value then the
* behavior is undefined. Some JDBC drivers may throw a
* <code>SQLException</code> while other drivers may support this
* operation.
*
* @param pos the position in the <code>BLOB</code> object at which
* to start writing; the first position is 1
* @param bytes the array of bytes to be written to the <code>BLOB</code>
* value that this <code>Blob</code> object represents
* @return the number of bytes written
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value or if pos is less than 1
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @see #getBytes
* @since 1.4
*/
int setBytes(long pos, byte[] bytes) throws SQLException;
Writes all or part of the given byte
array to the
BLOB
value that this Blob
object represents
and returns the number of bytes written.
Writing starts at position pos
in the BLOB
value; len
bytes from the given byte array are written.
The array of bytes will overwrite the existing bytes
in the Blob
object starting at the position
pos
. If the end of the Blob
value is reached
while writing the array of bytes, then the length of the Blob
value will be increased to accommodate the extra bytes.
Note: If the value specified for pos
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.
Params: - pos – the position in the
BLOB
object at which
to start writing; the first position is 1 - bytes – the array of bytes to be written to this
BLOB
object - offset – the offset into the array
bytes
at which
to start reading the bytes to be set - len – the number of bytes to be written to the
BLOB
value from the array of bytes bytes
Throws: - SQLException – if there is an error accessing the
BLOB
value or if pos is less than 1 - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
See Also: Returns: the number of bytes written Since: 1.4
/**
* Writes all or part of the given <code>byte</code> array to the
* <code>BLOB</code> value that this <code>Blob</code> object represents
* and returns the number of bytes written.
* Writing starts at position <code>pos</code> in the <code>BLOB</code>
* value; <code>len</code> bytes from the given byte array are written.
* The array of bytes will overwrite the existing bytes
* in the <code>Blob</code> object starting at the position
* <code>pos</code>. If the end of the <code>Blob</code> value is reached
* while writing the array of bytes, then the length of the <code>Blob</code>
* value will be increased to accommodate the extra bytes.
* <p>
* <b>Note:</b> If the value specified for <code>pos</code>
* is greater then the length+1 of the <code>BLOB</code> value then the
* behavior is undefined. Some JDBC drivers may throw a
* <code>SQLException</code> while other drivers may support this
* operation.
*
* @param pos the position in the <code>BLOB</code> object at which
* to start writing; the first position is 1
* @param bytes the array of bytes to be written to this <code>BLOB</code>
* object
* @param offset the offset into the array <code>bytes</code> at which
* to start reading the bytes to be set
* @param len the number of bytes to be written to the <code>BLOB</code>
* value from the array of bytes <code>bytes</code>
* @return the number of bytes written
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value or if pos is less than 1
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @see #getBytes
* @since 1.4
*/
int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException;
Retrieves a stream that can be used to write to the BLOB
value that this Blob
object represents. The stream begins
at position pos
.
The bytes written to the stream will overwrite the existing bytes
in the Blob
object starting at the position
pos
. If the end of the Blob
value is reached
while writing to the stream, then the length of the Blob
value will be increased to accommodate the extra bytes.
Note: If the value specified for pos
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.
Params: - pos – the position in the
BLOB
value at which
to start writing; the first position is 1
Throws: - SQLException – if there is an error accessing the
BLOB
value or if pos is less than 1 - SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
See Also: Returns: a java.io.OutputStream
object to which data can
be written Since: 1.4
/**
* Retrieves a stream that can be used to write to the <code>BLOB</code>
* value that this <code>Blob</code> object represents. The stream begins
* at position <code>pos</code>.
* The bytes written to the stream will overwrite the existing bytes
* in the <code>Blob</code> object starting at the position
* <code>pos</code>. If the end of the <code>Blob</code> value is reached
* while writing to the stream, then the length of the <code>Blob</code>
* value will be increased to accommodate the extra bytes.
* <p>
* <b>Note:</b> If the value specified for <code>pos</code>
* is greater then the length+1 of the <code>BLOB</code> value then the
* behavior is undefined. Some JDBC drivers may throw a
* <code>SQLException</code> while other drivers may support this
* operation.
*
* @param pos the position in the <code>BLOB</code> value at which
* to start writing; the first position is 1
* @return a <code>java.io.OutputStream</code> object to which data can
* be written
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value or if pos is less than 1
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @see #getBinaryStream
* @since 1.4
*/
java.io.OutputStream setBinaryStream(long pos) throws SQLException;
Truncates the BLOB
value that this Blob
object represents to be len
bytes in length.
Note: If the value specified for pos
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.
Params: - len – the length, in bytes, to which the
BLOB
value
that this Blob
object represents should be truncated
Throws: - 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
/**
* Truncates the <code>BLOB</code> value that this <code>Blob</code>
* object represents to be <code>len</code> bytes in length.
* <p>
* <b>Note:</b> If the value specified for <code>pos</code>
* is greater then the length+1 of the <code>BLOB</code> value then the
* behavior is undefined. Some JDBC drivers may throw a
* <code>SQLException</code> while other drivers may support this
* operation.
*
* @param len the length, in bytes, to which the <code>BLOB</code> value
* that this <code>Blob</code> object represents should be truncated
* @exception SQLException if there is an error accessing the
* <code>BLOB</code> value or if len is less than 0
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.4
*/
void truncate(long len) throws 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.
Throws: - SQLException – if an error occurs releasing
the Blob's resources
- SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Since: 1.6
/**
* This method frees the <code>Blob</code> object and releases the resources that
* it holds. The object is invalid once the <code>free</code>
* method is called.
*<p>
* After <code>free</code> has been called, any attempt to invoke a
* method other than <code>free</code> will result in a <code>SQLException</code>
* being thrown. If <code>free</code> is called multiple times, the subsequent
* calls to <code>free</code> are treated as a no-op.
*<p>
*
* @throws SQLException if an error occurs releasing
* the Blob's resources
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.6
*/
void free() throws SQLException;
Returns an InputStream
object that contains a partial Blob
value,
starting with the byte specified by pos, which is length bytes in length.
Params: - 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
Throws: - 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
Returns: InputStream
through which the partial Blob
value can be read.Since: 1.6
/**
* Returns an <code>InputStream</code> object that contains a partial <code>Blob</code> value,
* starting with the byte specified by pos, which is length bytes in length.
*
* @param pos the offset to the first byte of the partial value to be retrieved.
* The first byte in the <code>Blob</code> is at position 1
* @param length the length in bytes of the partial value to be retrieved
* @return <code>InputStream</code> through which the partial <code>Blob</code> value can be read.
* @throws SQLException if pos is less than 1 or if pos is greater than the number of bytes
* in the <code>Blob</code> or if pos + length is greater than the number of bytes
* in the <code>Blob</code>
*
* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
* this method
* @since 1.6
*/
InputStream getBinaryStream(long pos, long length) throws SQLException;
}