JavaTM Platform
Standard Ed. 6

javax.sql.rowset.serial
类 SerialClob

java.lang.Object
  继承者 javax.sql.rowset.serial.SerialClob
所有已实现的接口:
Serializable, Cloneable, Clob

public class SerialClob
extends Object
implements Clob, Serializable, Cloneable

SQL CLOB 值在 Java 编程语言中的序列化映射关系。

SerialClob 类提供一个根据 Clob 对象创建实例的构造方法。注意,在根据 Clob 对象构造 SerialBlob 对象之前,Clob 对象应该已经将 SQL Clob 值的数据置于客户端上。SQL CLOB 值的数据可以在客户端上以 Unicode 字符流的形式实现。

SerialClob 方法可以从 SerialClob 对象获取子字符串或者查找某种模式的字符的开头。

另请参见:
序列化表格

构造方法摘要
SerialClob(char[] ch)
          按照给定 char 数组的序列化形式构造一个 SerialClob 对象。
SerialClob(Clob clob)
          按照给定 Clob 对象的序列化形式构造一个 SerialClob 对象。
 
方法摘要
 void free()
          此方法释放 Clob 对象以及它所占用的资源。
 InputStream getAsciiStream()
          以 ascii 流的形式获取此 SerialClob 对象指定的 CLOB 值。
 Reader getCharacterStream()
          以 Unicode 字符流的形式返回此 SerialClob 对象的数据。
 Reader getCharacterStream(long pos, long length)
          返回包含部分 Clob 值的 Reader 对象,该值从 pos 指定的字符开始,长度为 length 个字符。
 String getSubString(long pos, int length)
          返回包含在此 SerialClob 对象中的子字符串的副本,从给定位置开始,后跟指定字符数。
 long length()
          获取此 SerialClob 对象字节数组中的字节数。
 long position(Clob searchStr, long start)
          返回此 SerialClob 对象中给定 Clob 签名开始的位置,搜索从指定位置开始。
 long position(String searchStr, long start)
          返回此 SerialClob 对象中给定 String 对象开始的位置,搜索从指定位置开始。
 OutputStream setAsciiStream(long pos)
          获取用于将 Ascii 字符写入此 SerialClob 对象所表示的 Clob 值的流,从位置 pos 处开始。
 Writer setCharacterStream(long pos)
          获取用于将 Unicode 字符流写入此 SerialClob 对象所表示的 CLOB 值(位置 pos 处)的流。
 int setString(long pos, String str)
          在位置 pos 处将给定 Java String 写入此 SerialClob 对象表示的 CLOB 值中。
 int setString(long pos, String str, int offset, int length)
          将 strlen 个字符写入此 Clob 表示的 CLOB 值中,从字符 offset 开始。
 void truncate(long length)
          截取此 SerialClob 对象所表示的 CLOB 值,使其长度为 len 个字符。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

SerialClob

public SerialClob(char[] ch)
           throws SerialException,
                  SQLException
按照给定 char 数组的序列化形式构造一个 SerialClob 对象。

新的 SerialClob 对象使用 char 数组中的数据进行初始化,因此允许未连接 RowSet 对象无需接触数据源即可建立序列化的 Clob 对象。

参数:
ch - 表示要序列化的 Clob 对象的 char 数组
抛出:
SerialException - 如果在序列化期间发生错误
SQLException - 如果发生 SQL 错误

SerialClob

public SerialClob(Clob clob)
           throws SerialException,
                  SQLException
按照给定 Clob 对象的序列化形式构造一个 SerialClob 对象。

新的 SerialClob 对象使用 Clob 对象中的数据进行初始化;因此,Clob 对象应该预先从数据库将 SQL CLOB 值的数据置于客户端上。否则,新 SerialClob 对象将不包含任何数据。

注:提供给此构造方法的 Clob 对象不能对 Clob.getCharacterStream()Clob.getAsciiStream 方法返回 null。此 SerialClob 构造方法不能在此实例中序列化 Clob 对象,将抛出 SQLException 对象。

参数:
clob - 要用来构造此 SerialClob 对象的 Clob 对象;不能为 null
抛出:
SerialException - 如果在序列化期间发生错误
SQLException - 如果在捕获 CLOB 期间发生 SQL 错误;如果 Clob 对象为 null;如果对 Clob 调用 Clob.getCharacterStream()Clob.getAsciiStream() 方法时都返回 null
另请参见:
Clob
方法详细信息

length

public long length()
            throws SerialException
获取此 SerialClob 对象字节数组中的字节数。

指定者:
接口 Clob 中的 length
返回:
一个 long 值,指示此 SerialClob 对象的字节数组的长度(以字节为单位)
抛出:
SerialException - 如果发生错误

getCharacterStream

public Reader getCharacterStream()
                          throws SerialException
以 Unicode 字符流的形式返回此 SerialClob 对象的数据。与相关方法 getAsciiStream 不同的是,无论 SerialClob 对象是使用 Clob 对象还是使用 char 数组创建,都将生成流。

指定者:
接口 Clob 中的 getCharacterStream
返回:
包含此 SerialClob 对象数据的 java.io.Reader 对象
抛出:
SerialException - 如果发生错误
另请参见:
Clob.setCharacterStream(long)

getAsciiStream

public InputStream getAsciiStream()
                           throws SerialException,
                                  SQLException
以 ascii 流的形式获取此 SerialClob 对象指定的 CLOB 值。如果此 SerialClob 对象是使用 Clob 对象实例化的,则此方法将 getAsciiStream 调用转发到底层 Clob。如果此 SerialClob 是使用 char 数组实例化的,则抛出 SerialException

指定者:
接口 Clob 中的 getAsciiStream
返回:
包含此 SerialClob 对象数据的 java.io.InputStream 对象
抛出:
SerialException - 如果此 SerialClob 对象不是使用 Clob 对象实例化的
SQLException - 如果在访问用于创建此 SerialClob 对象的 Clob 对象表示的 CLOB 值时发生错误
另请参见:
Clob.setAsciiStream(long)

getSubString

public String getSubString(long pos,
                           int length)
                    throws SerialException
返回包含在此 SerialClob 对象中的子字符串的副本,从给定位置开始,后跟指定字符数。

指定者:
接口 Clob 中的 getSubString
参数:
pos - 子字符串中要复制的第一个字符的位置;SerialClob 对象的第一个字符位于位置 1;不得小于 1,并且开始位置与子字符串的长度之和必须小于此 SerialClob 对象的长度
length - 子字符串中要返回的字符数;不得大于此 SerialClob 对象的长度,并且开始位置与子字符串的长度之和必须小于此 SerialClob 对象的长度
返回:
包含此 SerialClob 对象的子字符串的 String 对象,从给定位置开始,包含指定的连续字符数
抛出:
SerialException - 如果两个参数中的任意一个超出限制

position

public long position(String searchStr,
                     long start)
              throws SerialException,
                     SQLException
返回此 SerialClob 对象中给定 String 对象开始的位置,搜索从指定位置开始。如果未找到该模式,则此方法返回 -1

指定者:
接口 Clob 中的 position
参数:
searchStr - 要搜索的 String 对象
start - 此 SerialClob 对象中搜索开始的位置;第一个位置是 1;不得小于 1 且不得大于此 SerialClob 对象的长度
返回:
给定 String 对象开始的位置,从指定位置开始搜索;如果未找到给定的 String 对象或者开始位置超出限制,则返回 -1;返回值的位置编号从 1 开始
抛出:
SerialException - 如果在查找 String 签名时发生错误
SQLException - 如果从数据库访问 Blob 值时发生错误

position

public long position(Clob searchStr,
                     long start)
              throws SerialException,
                     SQLException
返回此 SerialClob 对象中给定 Clob 签名开始的位置,搜索从指定位置开始。如果未找到该模式,则此方法返回 -1

指定者:
接口 Clob 中的 position
参数:
searchStr - 要搜索的 Clob 对象
start - 此 SerialClob 对象中开始搜索的位置;第一个位置是 1;不得小于 1 且不得大于此 SerialClob 对象的长度
返回:
SerialClob 对象中的位置,给定的 Clob 对象从该位置开始,位于指定开始位置或该位置之后
抛出:
SerialException - 如果在查找 Clob 签名时发生错误
SQLException - 如果在从数据库访问 Blob 值时发生错误

setString

public int setString(long pos,
                     String str)
              throws SerialException
在位置 pos 处将给定 Java String 写入此 SerialClob 对象表示的 CLOB 值中。

指定者:
接口 Clob 中的 setString
参数:
pos - 开始写入此 SerialClob 对象所表示的 CLOB 值的位置;第一个位置是 1;不得小于 1 且不得大于此 SerialClob 对象的长度
str - 要写入此 SerialClob 对象所表示的 CLOB 值的字符串
返回:
写入的字符数
抛出:
SerialException - 如果在访问 CLOB 值时发生错误;如果设置了无效的位置;如果设置了无效的偏移量值;如果要写入的字节数大于 SerialClob 长度;如果长度与偏移量的组合值大于 Clob 缓冲区

setString

public int setString(long pos,
                     String str,
                     int offset,
                     int length)
              throws SerialException
strlen 个字符写入此 Clob 表示的 CLOB 值中,从字符 offset 开始。

指定者:
接口 Clob 中的 setString
参数:
pos - 开始写入此 SerialClob 对象所表示 CLOB 值的位置;第一个位置是 1;不得小于 1 且不得大于此 SerialClob 对象的长度
str - 要写入此 Clob 对象所表示 CLOB 值的字符串
offset - str 中开始读取要写入的字符的偏移量
length - 要写入的字符数
返回:
写入的字符数
抛出:
SerialException - 如果在访问 CLOB 值时发生错误;如果设置了无效的位置;如果设置了无效的偏移量值;如果要写入的字节数大于 SerialClob 长度;如果长度与偏移量的组合值大于 Clob 缓冲区

setAsciiStream

public OutputStream setAsciiStream(long pos)
                            throws SerialException,
                                   SQLException
获取用于将 Ascii 字符写入此 SerialClob 对象所表示的 Clob 值的流,从位置 pos 处开始。如果此 SerialClob 对象是使用 Clob 对象实例化的,则此方法将 getAsciiStream 调用转发到底层 Clob。如果此 SerialClob 是使用 char 数组实例化的,则抛出 SerialException

指定者:
接口 Clob 中的 setAsciiStream
参数:
pos - 开始写入此 CLOB 对象的位置
返回:
可写入 ASCII 编码字符的流
抛出:
SerialException - 如果 SerialClob 不是使用支持 setAsciiStream 的 Clob 对象实例化的
SQLException - 如果在访问 CLOB 值时发生错误
另请参见:
getAsciiStream()

setCharacterStream

public Writer setCharacterStream(long pos)
                          throws SerialException,
                                 SQLException
获取用于将 Unicode 字符流写入此 SerialClob 对象所表示的 CLOB 值(位置 pos 处)的流。如果此 SerialClob 对象是使用 Clob 对象实例化的,则此方法将 setCharacterStream() 调用转发到底层 Clob。如果此 SerialClob 是使用 char 数组实例化的,则抛出 SerialException

指定者:
接口 Clob 中的 setCharacterStream
参数:
pos - 开始写入 CLOB 值中的位置
返回:
可写入 Unicode 编码字符的流
抛出:
SerialException - 如果 SerialClob 不是使用支持 setCharacterStream 的 Clob 对象实例化的
SQLException - 如果在访问 CLOB 值时发生错误
另请参见:
getCharacterStream()

truncate

public void truncate(long length)
              throws SerialException
截取此 SerialClob 对象所表示的 CLOB 值,使其长度为 len 个字符。

SerialClob 对象截取至长度 0 相当于清除其内容。

指定者:
接口 Clob 中的 truncate
参数:
length - CLOB 值应被截取的字节长度
抛出:
SQLException - 如果访问 CLOB 值时发生错误
SerialException

getCharacterStream

public Reader getCharacterStream(long pos,
                                 long length)
                          throws SQLException
从接口 Clob 复制的描述
返回包含部分 Clob 值的 Reader 对象,该值从 pos 指定的字符开始,长度为 length 个字符。

指定者:
接口 Clob 中的 getCharacterStream
参数:
pos - 将获取的部分值第一个字符的偏移量。Clob 中的第一个字符在位置 1 处。
length - 要获取的部分值的字符长度。
返回:
Reader,可以通过它来读取部分 Clob 值。
抛出:
SQLException - 如果 pos 小于 1,或者 pos 大于 Clob 中的字符数,或者 pos + length 大于 Clob 中的字符数
SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

free

public void free()
          throws SQLException
从接口 Clob 复制的描述
此方法释放 Clob 对象以及它所占用的资源。调用 free 方法后,该对象无效。

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

指定者:
接口 Clob 中的 free
抛出:
SQLException - 如果释放 Clob 的资源时发生错误
SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策