模块 java.sql

软件包 java.sql

Interface Clob

All Known Subinterfaces:

NClob

所有已知实现类：

SerialClob

public interface Clob

用于SQL CLOB类型的CLOB “¢编程语言中的CLOB 。 SQL CLOB是一种内置类型，它将字符大对象存储为数据库表的行中的列值。 默认情况下，驱动程序使用SQL locator(CLOB)实现Clob对象，这意味着Clob对象包含指向SQL CLOB数据的逻辑指针，而不是数据本身。 Clob对象在创建它的事务期间有效。

Clob接口提供了获取SQL CLOB （字符大对象）值的长度的方法，用于在客户端上实现CLOB值，以及在CLOB值内搜索子字符串或CLOB对象。 方法在接口ResultSet ， CallableStatement ，并PreparedStatement ，如getClob和setClob允许编程人员访问SQL CLOB值。 此外，此接口还具有更新CLOB值的方法。

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

从以下版本开始：

1.2

方法摘要

变量和类型	方法	描述
void	free()	此方法释放 Clob对象所拥有的资源。
InputStream	getAsciiStream()	以ascii流的 CLOB检索此 Clob对象指定的 CLOB值。
Reader	getCharacterStream()	将此 Clob对象指定的 CLOB值检索为 java.io.Reader对象（或作为字符流）。
Reader	getCharacterStream(long pos, long length)	返回包含部分 Clob值的 Reader对象，该值以pos指定的字符开头，长度为长度字符。
String	getSubString(long pos, int length)	检索此 Clob对象指定的 CLOB值中指定子字符串的副本。
long	length()	检索此 Clob对象指定的 CLOB值中的字符数。
long	position(String searchstr, long start)	检索指定的子字符串 searchstr出现在此 Clob对象表示的SQL CLOB值中的字符位置。
long	position(Clob searchstr, long start)	检索指定的 Clob对象 searchstr在此 Clob对象中出现的字符位置。
OutputStream	setAsciiStream(long pos)	检索用于将Ascii字符写入此 Clob对象表示的 CLOB值的流，从位置 pos开始。
Writer	setCharacterStream(long pos)	检索用于将Unicode字符流写入此 Clob对象所代表的 CLOB值的流，位于位置 pos 。
int	setString(long pos, String str)	将给定的Java String写入此 Clob对象在位置 pos处指定的 CLOB值。
int	setString(long pos, String str, int offset, int len)	将 len字符 str （从字符 offset开始）写入此 Clob表示的 CLOB值。
void	truncate(long len)	截断此 Clob指定的 CLOB值，其长度为 len字符。

方法详细信息

length

long length()     throws SQLException

检索此 Clob对象指定的 CLOB值中的字符数。

结果

字符长度为 CLOB

异常

SQLException - 如果访问 CLOB值的长度时 CLOB

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

从以下版本开始：

1.2

getSubString

String getSubString(long pos,                    int length)             throws SQLException

检索此Clob对象指定的CLOB值中指定子字符串的副本。 子字符串从位置pos开始，最多length个连续字符。

参数

pos - 要提取的子字符串的第一个字符。 第一个角色位于第1位。

length - 要复制的连续字符数; length的值必须为0或更大

结果

a String ，它是此 Clob对象指定的 CLOB值中的指定子字符串

异常

SQLException - 如果访问CLOB值时出错; 如果pos小于1或长度小于0

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

从以下版本开始：

1.2

getCharacterStream

Reader getCharacterStream()                   throws SQLException

将此 Clob对象指定的 CLOB值检索为 java.io.Reader对象（或作为字符流）。

结果

包含 CLOB数据的 java.io.Reader对象

异常

SQLException - 如果访问 CLOB值时出错

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

从以下版本开始：

1.2

另请参见：

setCharacterStream(long)

getAsciiStream

InputStream getAsciiStream()                    throws SQLException

以ascii流的 CLOB检索此 Clob对象指定的 CLOB值。

结果

包含 CLOB数据的 java.io.InputStream对象

异常

SQLException - 如果访问 CLOB值时出错

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

从以下版本开始：

1.2

另请参见：

setAsciiStream(long)

position

long position(String searchstr,              long start)       throws SQLException

检索指定的子字符串searchstr出现在此Clob对象表示的SQL CLOB值中的字符位置。 搜索从位置start开始。

参数

searchstr - 要搜索的子字符串

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

结果

子串出现的位置，如果不存在则为-1; 第一个位置是1

异常

SQLException - 如果访问 CLOB值时出错或者pos小于1

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

从以下版本开始：

1.2

position

long position(Clob searchstr,              long start)       throws SQLException

检索指定的Clob对象searchstr在此Clob对象中出现的字符位置。 搜索从位置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

写入给定的Java String到CLOB值，这Clob对象表示在该位置pos 。 字符串将覆盖在现有的字符Clob在位置对象起始pos 。 如果年底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

将len字符str （从字符offset开始）写入此Clob代表的CLOB值。 字符串将覆盖在现有的字符Clob在位置对象起始pos 。 如果年底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

另请参见：

getAsciiStream()

setCharacterStream

Writer setCharacterStream(long pos)                   throws SQLException

检索用于将Unicode字符流写入此Clob对象所代表的CLOB值的流，位于位置pos 。 写入流的字符将覆盖Clob对象中的现有字符，从位置pos 。 如果的端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指定的长度为len字符的CLOB值。

注意：如果为pos指定的值大于CLOB值的长度+ 1，则行为未定义。 某些JDBC驱动程序可能会抛出SQLException而其他驱动程序可能支持此操作。

参数

len - 应截断 CLOB值的字符长度（以字符为 CLOB

异常

SQLException - 如果访问 CLOB值时出错或者len小于0

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

从以下版本开始：

1.4

free

void free()   throws SQLException

此方法释放Clob对象包含的资源。 调用free方法后，该对象无效。

在free之后，任何调用free以外的方法的尝试free将导致抛出SQLException 。 如果free被多次调用，在后续调用free被视为无操作。

异常

SQLException - 如果发生错误，释放Clob的资源

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

从以下版本开始：

1.6

getCharacterStream

Reader getCharacterStream(long pos,                          long length)                   throws SQLException

返回包含部分 Clob值的 Reader对象，以pos指定的字符开头，长度为长度字符。

参数

pos - 要检索的部分值的第一个字符的偏移量。 Clob中的第一个字符位于第1位。

length - 要检索的部分值的字符长度。

结果

Reader ，通过该局部 Clob值可被读取。

异常

SQLException - 如果pos小于1; 或者如果pos大于Clob的字符数; 或者如果pos + length大于Clob的字符数

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

从以下版本开始：

1.6