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