java.sql
接口 Blob

所有已知实现类：

SerialBlob

public interface Blob

SQL BLOB 值在 Java^TM 编程语言中的表示形式（映射关系）。SQL BLOB 是内置类型，它将二进制大对象 (Binary Large Object) 存储为数据库表某一行中的一个列值。默认情况下，驱动程序使用 SQL locator(BLOB) 实现 Blob，这意味着 Blob 对象包含一个指向 SQL BLOB 数据的逻辑指针而不是数据本身。Blob 对象在它被创建的事务处理期间有效。

接口 ResultSet、CallableStatement 和 PreparedStatement 中的方法（如 getBlob 和 setBlob）允许编程人员访问 SQL BLOB 值。Blob 接口提供一些方法来获取 SQL BLOB (Binary Large Object) 值的长度、在客户端实现 BLOB 值以及确定 BLOB 值中某一字节样本的位置。此外，此接口还有更新 BLOB 值的方法。

如果 JDBC 驱动程序支持该数据类型，则必须完全实现 Blob 接口的所有方法。

从以下版本开始：

1.2

方法摘要

void	free() 此方法释放 Blob 对象以及它所占用的资源。
InputStream	getBinaryStream() 以流的形式获取此 Blob 实例指定的 BLOB 值。
InputStream	getBinaryStream(long pos, long length) 返回包含部分 Blob 值的 InputStream 对象，该值从 pos 指定的字节开始，长度为 length 个字节。
byte[]	getBytes(long pos, int length) 以 byte 数组的形式获取此 Blob 对象表示的全部或部分 BLOB 值。
long	length() 返回此 Blob 对象指定的 BLOB 值中的字节数。
long	position(Blob pattern, long start) 获取此 Blob 对象指定的 BLOB 值中 pattern 开始处的字节位置。
long	position(byte[] pattern, long start) 获取此 Blob 对象表示的 BLOB 值中指定 byte 数组 pattern 开始处的字节位置。
OutputStream	setBinaryStream(long pos) 获取用于写入此 Blob 对象表示的 BLOB 值的流。
int	setBytes(long pos, byte[] bytes) 从位置 pos 处开始，将给定 byte 数组写入此 Blob 对象表示的 BLOB 值，并返回写入的字节数。
int	setBytes(long pos, byte[] bytes, int offset, int len) 将所有或部分给定的 byte 数组写入此 Blob 对象表示的 BLOB 值中，并返回写入的字节数。
void	truncate(long len) 截取此 Blob 对象表示的 BLOB 值，使其长度为 len 个字节。

方法详细信息

length

long length()
            throws SQLException

返回此 Blob 对象指定的 BLOB 值中的字节数。

返回：

BLOB 的字节长度

抛出：

SQLException - 如果访问 BLOB 的长度时发生错误

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.2

getBytes

byte[] getBytes(long pos,
                int length)
                throws SQLException

以 byte 数组的形式获取此 Blob 对象表示的全部或部分 BLOB 值。此 byte 数组包含从位置 pos 开始的 length 个连续字节。

参数：

pos - 要提取的 BLOB 值中第一个字节的顺序位置；第一个字节位于位置 1 处

length - 要复制的连续字节的数量；length 的值必须大于等于 0

返回：

一个字节数组，它包含此 Blob 对象指定的 BLOB 值中的 length 个连续字节（从位置 pos 处的字节开始）

抛出：

SQLException - 如果访问 BLOB 值时发生错误；如果 pos 小于 1 或 length 小于 0

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.2

另请参见：

setBytes(long, byte[])

getBinaryStream

InputStream getBinaryStream()
                            throws SQLException

以流的形式获取此 Blob 实例指定的 BLOB 值。

返回：

包含 BLOB 数据的流

抛出：

SQLException - 如果访问 BLOB 值时发生错误

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.2

另请参见：

setBinaryStream(long)

position

long position(byte[] pattern,
              long start)
              throws SQLException

获取此 Blob 对象表示的 BLOB 值中指定 byte 数组 pattern 开始处的字节位置。对 pattern 的搜索从位置 start 开始。

参数：

pattern - 要搜索的字节数组

start - 开始搜索的位置；第一个位置是 1

返回：

pattern 出现的位置，否则返回 -1

抛出：

SQLException - 如果访问 BLOB 时发生错误或者 start 小于 1

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.2

position

long position(Blob pattern,
              long start)
              throws SQLException

获取此 Blob 对象指定的 BLOB 值中 pattern 开始处的字节位置。从位置 start 开始搜索。

参数：

pattern - 指定要搜索的 BLOB 值的 Blob 对象

start - BLOB 值中开始进行搜索的位置；第一个位置是 1

返回：

pattern 开始处的位置，否则返回 -1

抛出：

SQLException - 如果访问 BLOB 值时发生错误或者 start 小于 1

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.2

setBytes

int setBytes(long pos,
             byte[] bytes)
             throws SQLException

从位置 pos 处开始，将给定 byte 数组写入此 Blob 对象表示的 BLOB 值，并返回写入的字节数。该 byte 数组将从位置 pos 开始重写 Blob 对象中的现有字节。如果在写 byte 数组时到达 Blob 值的末尾，则将增加 Blob 值的长度，以容纳额外的字节。

注：如果为 pos 指定的值大于 BLOB 值的长度+1，则行为是不确定的。一些 JDBC 驱动程序可能抛出 SQLException，而另一些驱动程序可能支持此操作。

参数：

pos - BLOB 对象开始进行写入操作的位置；第一个位置是 1

bytes - 要写入此 Blob 对象表示的 BLOB 值中的 byte 数组

返回：

写入的字节数

抛出：

SQLException - 如果访问 BLOB 值时发生错误或者 pos 小于 1

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.4

另请参见：

getBytes(long, int)

setBytes

int setBytes(long pos,
             byte[] bytes,
             int offset,
             int len)
             throws SQLException

将所有或部分给定的 byte 数组写入此 Blob 对象表示的 BLOB 值中，并返回写入的字节数。写入操作从 BLOB 值中的位置 pos 处开始；写入给定 byte 数组中的 len 个字节。该 byte 数组将从位置 pos 开始重写 Blob 对象中的现有字节。如果在写 byte 数组时到达 Blob 值的末尾，则将增加 Blob 值的长度，以容纳额外的字节。

注：如果为 pos 指定的值大于 BLOB 值的长度+1，则行为是不确定的。一些 JDBC 驱动程序可能抛出 SQLException，而另一些驱动程序可能支持此操作。

参数：

pos - BLOB 对象开始进行写入操作的位置；第一个位置是 1

bytes - 要写入此 BLOB 对象中的 byte 数组

offset - 数组 bytes 中的偏移量，从此处开始读取要设置的字节

len - 要从 byte 数组 bytes 中写入 BLOB 值的字节数

返回：

写入的字节数

抛出：

SQLException - 如果访问 BLOB 值时发生错误或者 pos 小于 1

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.4

另请参见：

getBytes(long, int)

setBinaryStream

OutputStream setBinaryStream(long pos)
                             throws SQLException

获取用于写入此 Blob 对象表示的 BLOB 值的流。该流从位置 pos 处开始。写入流中的字节将从位置 pos 开始重写 Blob 对象中的现有字节。如果在写入流时到达 Blob 值的末尾，则将增加 Blob 值的长度，以容纳额外的字节。

注：如果为 pos 指定的值大于 BLOB 值的长度+1，则行为是不确定的。一些 JDBC 驱动程序可能抛出 SQLException，而另一些驱动程序可能支持此操作。

参数：

pos - BLOB 值中开始进行写入操作的位置；第一个位置是 1

返回：

可以将数据写入其中的 java.io.OutputStream 对象

抛出：

SQLException - 如果访问 BLOB 值时发生错误或者 pos 小于 1

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.4

另请参见：

getBinaryStream()

truncate

void truncate(long len)
              throws SQLException

截取此 Blob 对象表示的 BLOB 值，使其长度为 len 个字节。

注：如果为 pos 指定的值大于 BLOB 值的长度+1，则行为是不确定的。一些 JDBC 驱动程序可能抛出 SQLException，而另一些驱动程序可能支持此操作。

参数：

len - 此 Blob 对象表示的 BLOB 值将被截取的字节长度

抛出：

SQLException - 如果访问 BLOB 值时发生错误或者 len 小于 0

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.4

free

void free()
          throws SQLException

此方法释放 Blob 对象以及它所占用的资源。调用 free 方法后，该对象将无效。

在调用 free 方法之后，试图调用 free 之外的方法将导致抛出 SQLException。如果多次调用 free，则对 free 的后续调用被视为无操作 (no-op)。

抛出：

SQLException - 如果在释放 Blob 的资源时发生错误

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.6

getBinaryStream

InputStream getBinaryStream(long pos,
                            long length)
                            throws SQLException

返回包含部分 Blob 值的 InputStream 对象，该值从 pos 指定的字节开始，长度为 length 个字节。

参数：

pos - 将获取的部分值第一个字节的偏移量。Blob 中的第一个字节在位置 1 处

length - 将获取的部分值的字节长度

返回：

将从中读取部分 Blob 值的 InputStream。

抛出：

SQLException - 如果 pos 小于 1，或者 pos 大于 Blob 中的字节数，或者 pos + length 大于 Blob 中的字节数

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

从以下版本开始：

1.6