Module java.sql.rowset

Package javax.sql.rowset.serial

Class SerialClob

java.lang.Object

javax.sql.rowset.serial.SerialClob

所有已实现的接口:

Serializable, Cloneable, Clob

       public class SerialClob extends Object implements Clob, Serializable, Cloneable
      

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

SerialClob类提供了一个从Clob对象创建实例的构造函数。请注意，在从中构造SerialClob对象之前，Clob对象应该已经将SQL CLOB值的数据传输到客户端。SQL CLOB值的数据可以在客户端作为Unicode字符流实现。

SerialClob方法使得可以从SerialClob对象中获取子字符串或定位字符模式的起始位置。

线程安全性

SerialClob不适合多个并发线程使用。如果一个SerialClob将被多个线程使用，则应通过适当的同步来控制对SerialClob的访问。

自版本:

1.5

参见:

• 序列化形式

Constructor Summary

Constructors

Constructor	Description
SerialClob(char[] ch)	构造一个SerialClob对象，该对象是给定char数组的序列化版本。
SerialClob(Clob clob)	构造一个SerialClob对象，该对象是给定Clob对象的序列化版本。

Method Summary

Modifier and Type	Method	Description
Object	clone()	返回此SerialClob的克隆。
boolean	equals(Object obj)	将此SerialClob与指定对象进行比较。
void	free()	该方法释放SerialClob对象并释放其持有的资源。
InputStream	getAsciiStream()	检索由此SerialClob对象指定的CLOB值作为ASCII流。
Reader	getCharacterStream()	将此SerialClob对象的数据作为Unicode字符流返回。
Reader	getCharacterStream(long pos, long length)	返回一个Reader对象，其中包含一个部分SerialClob值，从指定位置pos开始，长度为length个字符。
String	getSubString(long pos, int length)	返回包含在此SerialClob对象中的子字符串的副本，从给定位置开始，继续指定数量的字符。
int	hashCode()	返回此SerialClob的哈希码。
long	length()	检索此SerialClob对象的字符数组中的字符数。
long	position(String searchStr, long start)	返回此SerialClob对象中给定String对象开始的位置，从指定位置开始搜索。
long	position(Clob searchStr, long start)	返回此SerialClob对象中给定Clob签名开始的位置，从指定位置开始搜索。
OutputStream	setAsciiStream(long pos)	检索一个流，用于将Ascii字符写入此SerialClob对象表示的CLOB值，从位置pos开始。
Writer	setCharacterStream(long pos)	检索一个流，用于将Unicode字符流写入此SerialClob对象表示的CLOB值，从位置pos开始。
int	setString(long pos, String str)	将给定的Java String写入此SerialClob对象表示的CLOB值，位置为pos。
int	setString(long pos, String str, int offset, int length)	将str的len个字符，从字符offset开始，写入此Clob表示的CLOB值。
void	truncate(long length)	截断此SerialClob对象表示的CLOB值，使其长度为len个字符。

Methods declared in class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SerialClob

             public SerialClob(char[] ch) throws SerialException, SQLException
            

构造一个SerialClob对象，该对象是给定char数组的序列化版本。

新的SerialClob对象使用char数组的数据进行初始化，从而允许断开连接的RowSet对象建立一个序列化的Clob对象而不触及数据源。

参数:

ch - 表示要序列化的Clob对象的char数组

抛出:

SerialException - 如果在序列化过程中发生错误

SQLException - 如果发生SQL错误

SerialClob

             public SerialClob(Clob clob) throws SerialException, SQLException
            

构造一个SerialClob对象，该对象是给定Clob对象的序列化版本。

新的SerialClob对象使用Clob对象的数据进行初始化；因此，Clob对象应该先将SQL CLOB值的数据从数据库传输到客户端。否则，新的SerialClob对象将不包含任何数据。

注意：提供给此构造函数的Clob对象必须对Clob.getCharacterStream()和Clob.getAsciiStream方法都返回非空值。在这种情况下，此SerialClob构造函数无法序列化Clob对象，并将抛出一个SQLException对象。

参数:

clob - 用于构造此SerialClob对象的Clob对象；不能为空

抛出:

SerialException - 如果在序列化过程中发生错误

SQLException - 如果在捕获CLOB时发生SQL错误；如果Clob对象为null；或者如果Clob的Clob.getCharacterStream()和Clob.getAsciiStream()方法中的任一方法返回null

参见:

• Clob

Method Details

length

             public long length() throws SerialException
            

检索此SerialClob对象的字符数组中的字符数。

指定者:

length 在接口 Clob中

返回:

一个long，表示此SerialClob对象的字符数组的长度

抛出:

SerialException - 如果发生错误；如果此对象之前已调用free

getCharacterStream

             public Reader getCharacterStream() throws SerialException
            

返回此SerialClob对象的数据作为Unicode字符流。与相关方法getAsciiStream不同，无论SerialClob对象是使用Clob对象还是char数组创建的，都会生成一个流。

指定者:

getCharacterStream 在接口 Clob中

返回:

包含此SerialClob对象数据的java.io.Reader对象

抛出:

SerialException - 如果发生错误；如果此对象之前已调用free

参见:

• Clob.setCharacterStream(long)

getAsciiStream

             public InputStream getAsciiStream() throws SerialException, SQLException
            

检索由此SerialClob对象指定的CLOB值作为ASCII流。如果此SerialClob对象是使用Clob对象实例化的，则此方法将getAsciiStream调用转发到底层的Clob对象。如果此SerialClob对象是使用char数组实例化的，则会抛出一个SerialException对象。

指定者:

getAsciiStream 在接口 Clob中

返回:

包含此SerialClob对象数据的java.io.InputStream对象

抛出:

SerialException - 如果此SerialClob对象不是使用Clob对象实例化的；如果此对象之前已调用free

SQLException - 如果访问由用于创建此SerialClob对象的Clob对象表示的CLOB值时发生错误

参见:

• Clob.setAsciiStream(long)

getSubString

             public String getSubString(long pos, int length) throws SerialException
            

返回包含在此SerialClob对象中的子字符串的副本，从给定位置开始，继续指定数量的字符。

指定者:

getSubString 在接口 Clob中

参数:

pos - 要复制的子字符串中第一个字符的位置；SerialClob对象的第一个字符位于位置1；不得小于1，且起始位置和子字符串长度的总和必须小于此SerialClob对象的长度

length - 要返回的子字符串中的字符数；不得大于此SerialClob对象的长度，并且起始位置和子字符串长度的总和必须小于此SerialClob对象的长度

返回:

包含从给定位置开始的此SerialClob对象的子字符串的String对象，包含指定数量的连续字符

抛出:

SerialException - 如果任一参数超出范围；如果此对象上先前调用了free

position

             public long position(String searchStr, long start) throws SerialException, SQLException
            

返回此SerialClob对象中给定String对象开始的位置，从指定位置开始搜索。如果未找到模式，则此方法返回-1。

指定者:

position 在接口 Clob中

参数:

searchStr - 要搜索的String对象

start - 在此SerialClob对象中开始搜索的位置；第一个位置为1；不得小于1，也不得大于此SerialClob对象的长度

返回:

给定String对象开始的位置，从指定位置开始搜索；如果未找到给定String对象或起始位置超出范围，则返回-1；返回值的位置编号从1开始

抛出:

SerialException - 如果先前在此对象上调用了free方法

SQLException - 如果访问数据库中的Clob值时出现错误

position

             public long position(Clob searchStr, long start) throws SerialException, SQLException
            

返回此SerialClob对象中给定Clob签名开始的位置，从指定位置开始搜索。如果未找到模式，则此方法返回-1。

指定者:

position 在接口 Clob中

参数:

searchStr - 要搜索的Clob对象

start - 在此SerialClob对象中开始搜索的位置；第一个位置为1；不得小于1，也不得大于此SerialClob对象的长度

返回:

此SerialClob对象中给定Clob对象开始的位置，从指定起始位置或之后开始

抛出:

SerialException - 如果定位Clob签名时发生错误；如果先前在此对象上调用了free方法

SQLException - 如果访问数据库中的Clob值时出现错误

setString

             public int setString(long pos, String str) throws SerialException
            

将给定的Java String写入此SerialClob对象表示的CLOB值，位置为pos。

指定者:

setString 在接口 Clob中

参数:

pos - 要开始写入此SerialClob对象表示的CLOB值的位置；第一个位置为1；不得小于1，也不得大于此SerialClob对象的长度+1

str - 要写入此SerialClob对象表示的CLOB值的字符串

返回:

写入的字符数

抛出:

SerialException - 如果访问CLOB值时出现错误；如果设置了无效位置；如果先前在此对象上调用了free方法

setString

             public int setString(long pos, String str, int offset, int length) throws SerialException
            

写入len个字符的str，从字符offset开始，到此Clob表示的CLOB值。

指定者:

setString 在接口 Clob中

参数:

pos - 要开始写入此SerialClob对象表示的CLOB值的位置；第一个位置为1；不得小于1，也不得大于此SerialClob对象的长度+1

str - 要写入此CLOB值的Clob对象表示的字符串

offset - 开始读取要写入的字符的str中的偏移量

length - 要写入的字符数

返回:

写入的字符数

抛出:

SerialException - 如果访问CLOB值时出现错误；如果设置了无效位置；如果设置了无效偏移值；或length和offset的组合值大于str的长度；如果先前在此对象上调用了free方法

setAsciiStream

             public OutputStream setAsciiStream(long pos) throws SerialException, SQLException
            

检索一个流，用于将Ascii字符写入此SerialClob对象表示的CLOB值，从位置pos开始。如果此SerialClob对象是使用Clob对象实例化的，则此方法将setAsciiStream()调用转发到底层Clob对象。如果此SerialClob对象是使用char数组实例化的，则会抛出SerialException对象。

指定者:

setAsciiStream 在接口 Clob中

参数:

pos - 要开始写入CLOB对象的位置

返回:

可以写入ASCII编码字符的流

抛出:

SerialException - 如果SerialClob未使用Clob对象实例化；如果先前在此对象上调用了free方法

SQLException - 如果访问CLOB值时出现错误

参见:

• getAsciiStream()

setCharacterStream

             public Writer setCharacterStream(long pos) throws SerialException, SQLException
            

检索一个流，用于将Unicode字符流写入此SerialClob对象表示的CLOB值，位置为pos。如果此SerialClob对象是使用Clob对象实例化的，则此方法将setCharacterStream()调用转发到底层Clob对象。如果此SerialClob对象是使用char数组实例化的，则会抛出SerialException。

指定者:

setCharacterStream 在接口 Clob中

参数:

pos - 要开始写入CLOB值的位置

返回:

可以写入Unicode编码字符的流

抛出:

SerialException - 如果SerialClob未使用Clob对象实例化；如果先前在此对象上调用了free方法

SQLException - 如果访问CLOB值时出现错误

参见:

• getCharacterStream()

truncate

             public void truncate(long length) throws SerialException
            

截断此SerialClob对象表示的CLOB值，使其长度为len个字符。

将SerialClob对象截断为长度为0的效果是清除其内容。

指定者:

truncate 在接口 Clob中

参数:

length - 应将CLOB值截断为的字节数

抛出:

SerialException - 如果访问CLOB值时出现错误；如果此对象之前已调用free方法

getCharacterStream

             public Reader getCharacterStream(long pos, long length) throws SQLException
            

返回一个包含部分SerialClob值的Reader对象，从指定位置开始，长度为length个字符。

指定者:

getCharacterStream 在接口 Clob中

参数:

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

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

返回:

通过该Reader可以读取部分SerialClob值。

抛出:

SQLException - 如果pos小于1，或者pos大于SerialClob中的字符数，或者pos + length大于SerialClob中的字符数；

SerialException - 如果此对象之前已调用free方法

自从:

1.6

free

             public void free() throws SQLException
            

该方法释放SerialClob对象并释放其持有的资源。一旦调用free方法，对象就无效。

如果多次调用free，则后续调用将被视为无操作。

指定者:

free 在接口 Clob中

抛出:

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

自从:

1.6

equals

             public boolean equals(Object obj)
            

将此SerialClob与指定对象进行比较。如果参数不为null且为表示与此对象相同字符序列的SerialClob对象，则结果为true。

覆盖:

equals 在类 Object中

参数:

obj - 要与此SerialClob进行比较的对象

返回:

如果给定对象表示与此SerialClob等效的SerialClob，则返回true，否则返回false

参见:

• Object.hashCode()
• HashMap

hashCode

             public int hashCode()
            

返回此SerialClob的哈希码。

覆盖:

hashCode 在类 Object中

返回:

此对象的哈希码值。

参见:

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

clone

             public Object clone()
            

返回此SerialClob的克隆。副本将包含对内部字符数组的克隆的引用，而不是对此SerialClob对象的原始内部字符数组的引用。底层Clob对象将设置为null。

覆盖:

clone 在类 Object中

返回:

此SerialClob的克隆

参见:

• Cloneable