java.sql
介面 Clob

所有已知子介面：

NClob

所有已知實作類別：

SerialClob

public interface Clob

SQL 型別 CLOB 在 Java^TM 程式語言中的映射關係。SQL CLOB 是內置型別，它將字元大物件 (Character Large Object) 存儲為資料庫表某一行中的一個列值。預設情況下，驅動程序使用 SQL locator(CLOB) 實作 Clob 物件，這意味著 CLOB 物件包含一個指向 SQL CLOB 資料的邏輯指針而不是資料本身。Clob 物件在它被創建的事務處理期間有效。

CLOB 介面提供一些方法來獲取 SQL CLOB (Character Large Object) 值長度、在客戶端實作 CLOB 值以及搜尋 CLOB 值中的子字元串或 CLOB 物件。介面 ResultSet、CallableStatement 和 PreparedStatement 中的方法（如 getClob 和 setClob）允許程式人員存取 SQL CLOB 值。此外，此介面還擁有更新 CLOB 值的方法。

如果 JDBC 驅動程序支持該資料型別，則必須完全實作 Clob 介面上的所有方法。

從以下版本開始：

1.2

方法摘要

void	free() 此方法釋放 Clob 物件以及它所佔用的資源。
InputStream	getAsciiStream() 以 ascii 串流形式獲取此 Clob 物件指定的 CLOB 值。
Reader	getCharacterStream() 以 java.io.Reader 物件形式（或字元串流形式）獲取此 Clob 物件指定的 CLOB 值。
Reader	getCharacterStream(long pos, long length) 返回包含部分 Clob 值的 Reader 物件，該值從 pos 指定的字元開始，長度為 length 個字元。
String	getSubString(long pos, int length) 獲取此 Clob 物件指定的 CLOB 值中指定子字元串的副本。
long	length() 獲取此 Clob 物件指定的 CLOB 值中的字元數。
long	position(Clob searchstr, long start) 獲取此 Clob 物件中指定的 Clob 物件 searchstr 出現的字元位置。
long	position(String searchstr, long start) 獲取此 Clob 物件表示的 SQL CLOB 值中指定子字元串 searchstr 出現的字元位置。
OutputStream	setAsciiStream(long pos) 獲取用於將 Ascii 字元寫入此 Clob 物件表示的 Clob 值中的串流，從位置 pos 處開始。
Writer	setCharacterStream(long pos) 獲取用於將 Unicode 字元串流寫入此 Clob 物件表示的 CLOB 值中（位置 pos 處）的串流。
int	setString(long pos, String str) 在位置 pos 處將給定 Java String 寫入此 Clob 物件指定的 CLOB 值中。
int	setString(long pos, String str, int offset, int len) 將 str 的 len 個字元（從字元 offset 開始）寫入此 Clob 表示的 CLOB 值中。
void	truncate(long len) 截取此 Clob 指定的 CLOB 值，使其長度為 len 個字元。

方法詳細資訊

length

long length()
            throws SQLException

獲取此 Clob 物件指定的 CLOB 值中的字元數。

返回：

CLOB 的字元長度

拋出：

SQLException - 如果存取 CLOB 值的長度時發生錯誤

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.2

getSubString

String getSubString(long pos,
                    int length)
                    throws SQLException

獲取此 Clob 物件指定的 CLOB 值中指定子字元串的副本。子字元串開始於位置 pos 處，有 length 個連續字元。

參數：

pos - 要提取的子字元串的第一個字元。第一個字元位於位置 1 處。

length - 要複製的連續字元的數量；length 的值必須大於等於 0

返回：

一個 String，它是由此 Clob 物件指定的 CLOB 值中的指定子字元串

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤；如果 pos 小於 1 或者 length 小於 0

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.2

getCharacterStream

Reader getCharacterStream()
                          throws SQLException

以 java.io.Reader 物件形式（或字元串流形式）獲取此 Clob 物件指定的 CLOB 值。

返回：

包含 CLOB 資料的 java.io.Reader 物件

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.2

另請參見：

setCharacterStream(long)

getAsciiStream

InputStream getAsciiStream()
                           throws SQLException

以 ascii 串流形式獲取此 Clob 物件指定的 CLOB 值。

返回：

包含 CLOB 資料的 java.io.InputStream 物件

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.2

另請參見：

setAsciiStream(long)

position

long position(String searchstr,
              long start)
              throws SQLException

獲取此 Clob 物件表示的 SQL CLOB 值中指定子字元串 searchstr 出現的字元位置。從位置 start 開始搜尋。

參數：

searchstr - 要搜尋的子字元串

start - 開始搜尋的位置；第一個位置是 1

返回：

子字元串出現的位置；如果沒有出現，則返回 -1；第一個位置是 1

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 pos 小於 1

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.2

position

long position(Clob searchstr,
              long start)
              throws SQLException

獲取此 Clob 物件中指定的 Clob 物件 searchstr 出現的字元位置。從位置 start 開始搜尋。

參數：

searchstr - 要搜尋的 Clob 物件

start - 開始搜尋的位置；第一個位置是 1

返回：

Clob 物件出現的位置；如果沒有出現，則返回 -1；第一個位置是 1

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 start 小於 1

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.2

setString

int setString(long pos,
              String str)
              throws SQLException

在位置 pos 處將給定 Java String 寫入此 Clob 物件指定的 CLOB 值中。該字元串將從位置 pos 開始覆寫 Clob 物件中的現有位元組。如果在寫入給定字元串時到達 Clob 值的末尾，則將增加 Clob 值的長度，以容納額外的字元。

註：如果為 pos 指定的值大於 CLOB 值的長度+1，則行為是不確定的。一些 JDBC 驅動程序可能拋出 SQLException，而另一些驅動程序可能支持此操作。

參數：

pos - 開始寫入此 Clob 物件表示的 CLOB 值的位置；第一個位置是 1

str - 要寫入此 Clob 指定的 CLOB 值中的字元串

返回：

寫入的字元數

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 pos 小於 1

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.4

setString

int setString(long pos,
              String str,
              int offset,
              int len)
              throws SQLException

將 str 的 len 個字元（從字元 offset 開始）寫入此 Clob 表示的 CLOB 值中。該字元串將從位置 pos 開始覆寫 Clob 物件中的現有位元組。如果在寫入給定字元串時到達 Clob 值的末尾，則將增加 Clob 值的長度，以容納額外的字元。

註：如果為 pos 指定的值大於 CLOB 值的長度+1，則行為是不確定的。一些 JDBC 驅動程序可能拋出 SQLException，而另一些驅動程序可能支持此操作。

參數：

pos - 開始寫入此 CLOB 物件的位置；第一個位置是 1

str - 要寫入此 Clob 物件表示的 CLOB 值中的字元串

offset - str 中開始讀取要寫入字元的偏移量

len - 要寫入的字元數

返回：

寫入的字元數

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 pos 小於 1

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.4

setAsciiStream

OutputStream setAsciiStream(long pos)
                            throws SQLException

獲取用於將 Ascii 字元寫入此 Clob 物件表示的 Clob 值中的串流，從位置 pos 處開始。寫入串流中的字元將從位置 pos 開始覆寫 Clob 物件中的現有位元組。如果在將字元寫入串流中時到達 Clob 值的末尾，則將增加 Clob 值的長度，以容納額外的字元。

註：如果為 pos 指定的值大於 CLOB 值的長度+1，則行為是不確定的。一些 JDBC 驅動程序可能拋出 SQLException，而另一些驅動程序可能支持此操作。

參數：

pos - 開始寫入此 CLOB 物件中的位置；第一個位置是 1

返回：

可以將 ASCII 編碼字元寫入其中的串流

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 pos 小於 1

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.4

另請參見：

#getBinaryStream

setCharacterStream

Writer setCharacterStream(long pos)
                          throws SQLException

獲取用於將 Unicode 字元串流寫入此 Clob 物件表示的 CLOB 值中（位置 pos 處）的串流。寫入串流中的字元將從位置 pos 開始覆寫 Clob 物件中的現有位元組。如果在將字元寫入串流中時到達 Clob 值的末尾，則將增加 Clob 值的長度，以容納額外的字元。

註：如果為 pos 指定的值大於 CLOB 值的長度+1，則行為是不確定的。一些 JDBC 驅動程序可能拋出 SQLException，而另一些驅動程序可能支持此操作。

參數：

pos - 開始寫入 CLOB 值中的位置；第一個位置是 1

返回：

可將 Unicode 編碼字元寫入其中的串流

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 pos 小於 1

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.4

另請參見：

getCharacterStream()

truncate

void truncate(long len)
              throws SQLException

截取此 Clob 指定的 CLOB 值，使其長度為 len 個字元。

註：如果為 pos 指定的值大於 CLOB 值的長度+1，則行為是不確定的。一些 JDBC 驅動程序可能拋出 SQLException，而另一些驅動程序可能支持此操作。

參數：

len - CLOB 值應被截取的字元長度

拋出：

SQLException - 如果存取 CLOB 值時發生錯誤，或者 len 小於 0

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.4

free

void free()
          throws SQLException

此方法釋放 Clob 物件以及它所佔用的資源。調用 free 方法後，該物件無效。

在調用 free 方法之後，試圖調用 free 之外的方法將導致拋出 SQLException。如果多次調用 free，則對 free 的後續調用被視為無操作 (no-op)。

拋出：

SQLException - 如果釋放 Clob 的資源時發生錯誤

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.6

getCharacterStream

Reader getCharacterStream(long pos,
                          long length)
                          throws SQLException

返回包含部分 Clob 值的 Reader 物件，該值從 pos 指定的字元開始，長度為 length 個字元。

參數：

pos - 將獲取的部分值第一個字元的偏移量。Clob 中的第一個字元在位置 1 處。

length - 要獲取的部分值的字元長度。

返回：

Reader，可以通過它來讀取部分 Clob 值。

拋出：

SQLException - 如果 pos 小於 1，或者 pos 大於 Clob 中的字元數，或者 pos + length 大於 Clob 中的字元數

SQLFeatureNotSupportedException - 如果 JDBC 驅動程序不支持此方法

從以下版本開始：

1.6