- java.lang.Object
-
- javax.sql.rowset.serial.SerialClob
-
- All Implemented Interfaces:
Serializable,Cloneable,Clob
public class SerialClob extends Object implements Clob, Serializable, Cloneable
A serialized mapping in the Java programming language of an SQLCLOBvalue.The
SerialClobclass provides a constructor for creating an instance from aClobobject. Note that theClobobject should have brought the SQLCLOBvalue's data over to the client before aSerialClobobject is constructed from it. The data of an SQLCLOBvalue can be materialized on the client as a stream of Unicode characters.SerialClobmethods make it possible to get a substring from aSerialClobobject or to locate the start of a pattern of characters.Thread safety
A SerialClob is not safe for use by multiple concurrent threads. If a SerialClob is to be used by more than one thread then access to the SerialClob should be controlled by appropriate synchronization.
- Since:
- 1.5
- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description SerialClob(char[] ch)Constructs aSerialClobobject that is a serialized version of the givenchararray.SerialClob(Clob clob)Constructs aSerialClobobject that is a serialized version of the givenClobobject.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Objectclone()Returns a clone of thisSerialClob.booleanequals(Object obj)Compares this SerialClob to the specified object.voidfree()This method frees theSerialClobobject and releases the resources that it holds.InputStreamgetAsciiStream()Retrieves theCLOBvalue designated by thisSerialClobobject as an ascii stream.ReadergetCharacterStream()Returns thisSerialClobobject's data as a stream of Unicode characters.ReadergetCharacterStream(long pos, long length)Returns aReaderobject that contains a partialSerialClobvalue, starting with the character specified by pos, which is length characters in length.StringgetSubString(long pos, int length)Returns a copy of the substring contained in thisSerialClobobject, starting at the given position and continuing for the specified number or characters.inthashCode()Returns a hash code for thisSerialClob.longlength()Retrieves the number of characters in thisSerialClobobject's array of characters.longposition(String searchStr, long start)Returns the position in thisSerialClobobject where the givenStringobject begins, starting the search at the specified position.longposition(Clob searchStr, long start)Returns the position in thisSerialClobobject where the givenClobsignature begins, starting the search at the specified position.OutputStreamsetAsciiStream(long pos)Retrieves a stream to be used to write Ascii characters to theCLOBvalue that thisSerialClobobject represents, starting at positionpos.WritersetCharacterStream(long pos)Retrieves a stream to be used to write a stream of Unicode characters to theCLOBvalue that thisSerialClobobject represents, at positionpos.intsetString(long pos, String str)Writes the given JavaStringto theCLOBvalue that thisSerialClobobject represents, at the positionpos.intsetString(long pos, String str, int offset, int length)Writeslencharacters ofstr, starting at characteroffset, to theCLOBvalue that thisClobrepresents.voidtruncate(long length)Truncates theCLOBvalue that thisSerialClobobject represents so that it has a length oflencharacters.
-
-
-
Constructor Detail
-
SerialClob
public SerialClob(char[] ch) throws SerialException, SQLExceptionConstructs aSerialClobobject that is a serialized version of the givenchararray.The new
SerialClobobject is initialized with the data from thechararray, thus allowing disconnectedRowSetobjects to establish a serializedClobobject without touching the data source.- Parameters:
ch- the char array representing theClobobject to be serialized- Throws:
SerialException- if an error occurs during serializationSQLException- if a SQL error occurs
-
SerialClob
public SerialClob(Clob clob) throws SerialException, SQLException
Constructs aSerialClobobject that is a serialized version of the givenClobobject.The new
SerialClobobject is initialized with the data from theClobobject; therefore, theClobobject should have previously brought the SQLCLOBvalue's data over to the client from the database. Otherwise, the newSerialClobobject object will contain no data.Note: The
Clobobject supplied to this constructor must return non-null for both theClob.getCharacterStream()andClob.getAsciiStreammethods. ThisSerialClobconstructor cannot serialize aClobobject in this instance and will throw anSQLExceptionobject.- Parameters:
clob- theClobobject from which thisSerialClobobject is to be constructed; cannot be null- Throws:
SerialException- if an error occurs during serializationSQLException- if a SQL error occurs in capturing the CLOB; if theClobobject is a null; or if either of theClob.getCharacterStream()andClob.getAsciiStream()methods on theClobreturns a null- See Also:
Clob
-
-
Method Detail
-
length
public long length() throws SerialExceptionRetrieves the number of characters in thisSerialClobobject's array of characters.- Specified by:
lengthin interfaceClob- Returns:
- a
longindicating the length in characters of thisSerialClobobject's array of character - Throws:
SerialException- if an error occurs; iffreehad previously been called on this object
-
getCharacterStream
public Reader getCharacterStream() throws SerialException
Returns thisSerialClobobject's data as a stream of Unicode characters. Unlike the related method,getAsciiStream, a stream is produced regardless of whether theSerialClobobject was created with aClobobject or achararray.- Specified by:
getCharacterStreamin interfaceClob- Returns:
- a
java.io.Readerobject containing thisSerialClobobject's data - Throws:
SerialException- if an error occurs; iffreehad previously been called on this object- See Also:
Clob.setCharacterStream(long)
-
getAsciiStream
public InputStream getAsciiStream() throws SerialException, SQLException
Retrieves theCLOBvalue designated by thisSerialClobobject as an ascii stream. This method forwards thegetAsciiStreamcall to the underlyingClobobject in the event that thisSerialClobobject is instantiated with aClobobject. If thisSerialClobobject is instantiated with achararray, aSerialExceptionobject is thrown.- Specified by:
getAsciiStreamin interfaceClob- Returns:
- a
java.io.InputStreamobject containing thisSerialClobobject's data - Throws:
SerialException- if thisSerialClobobject was not instantiated with aClobobject; iffreehad previously been called on this objectSQLException- if there is an error accessing theCLOBvalue represented by theClobobject that was used to create thisSerialClobobject- See Also:
Clob.setAsciiStream(long)
-
getSubString
public String getSubString(long pos, int length) throws SerialException
Returns a copy of the substring contained in thisSerialClobobject, starting at the given position and continuing for the specified number or characters.- Specified by:
getSubStringin interfaceClob- Parameters:
pos- the position of the first character in the substring to be copied; the first character of theSerialClobobject is at position1; must not be less than1, and the sum of the starting position and the length of the substring must be less than the length of thisSerialClobobjectlength- the number of characters in the substring to be returned; must not be greater than the length of thisSerialClobobject, and the sum of the starting position and the length of the substring must be less than the length of thisSerialClobobject- Returns:
- a
Stringobject containing a substring of thisSerialClobobject beginning at the given position and containing the specified number of consecutive characters - Throws:
SerialException- if either of the arguments is out of bounds; iffreehad previously been called on this object
-
position
public long position(String searchStr, long start) throws SerialException, SQLException
Returns the position in thisSerialClobobject where the givenStringobject begins, starting the search at the specified position. This method returns-1if the pattern is not found.- Specified by:
positionin interfaceClob- Parameters:
searchStr- theStringobject for which to searchstart- the position in thisSerialClobobject at which to start the search; the first position is1; must not be less than1nor greater than the length of thisSerialClobobject- Returns:
- the position at which the given
Stringobject begins, starting the search at the specified position;-1if the givenStringobject is not found or the starting position is out of bounds; position numbering for the return value starts at1 - Throws:
SerialException- if thefreemethod had been previously called on this objectSQLException- if there is an error accessing the Clob value from the database.
-
position
public long position(Clob searchStr, long start) throws SerialException, SQLException
Returns the position in thisSerialClobobject where the givenClobsignature begins, starting the search at the specified position. This method returns-1if the pattern is not found.- Specified by:
positionin interfaceClob- Parameters:
searchStr- theClobobject for which to searchstart- the position in thisSerialClobobject at which to begin the search; the first position is1; must not be less than1nor greater than the length of thisSerialClobobject- Returns:
- the position at which the given
Clobobject begins in thisSerialClobobject, at or after the specified starting position - Throws:
SerialException- if an error occurs locating the Clob signature; if thefreemethod had been previously called on this objectSQLException- if there is an error accessing the Clob value from the database
-
setString
public int setString(long pos, String str) throws SerialExceptionWrites the given JavaStringto theCLOBvalue that thisSerialClobobject represents, at the positionpos.- Specified by:
setStringin interfaceClob- Parameters:
pos- the position at which to start writing to theCLOBvalue that thisSerialClobobject represents; the first position is1; must not be less than1nor greater than the length of thisSerialClobobjectstr- the string to be written to theCLOBvalue that thisSerialClobobject represents- Returns:
- the number of characters written
- Throws:
SerialException- if there is an error accessing theCLOBvalue; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than theSerialCloblength; or the combined values of the length and offset is greater than the Clob buffer; if thefreemethod had been previously called on this object
-
setString
public int setString(long pos, String str, int offset, int length) throws SerialExceptionWriteslencharacters ofstr, starting at characteroffset, to theCLOBvalue that thisClobrepresents.- Specified by:
setStringin interfaceClob- Parameters:
pos- the position at which to start writing to theCLOBvalue that thisSerialClobobject represents; the first position is1; must not be less than1nor greater than the length of thisSerialClobobjectstr- the string to be written to theCLOBvalue that thisClobobject representsoffset- the offset intostrto start reading the characters to be writtenlength- the number of characters to be written- Returns:
- the number of characters written
- Throws:
SerialException- if there is an error accessing theCLOBvalue; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than theSerialCloblength; or the combined values of the length and offset is greater than the Clob buffer; if thefreemethod had been previously called on this object
-
setAsciiStream
public OutputStream setAsciiStream(long pos) throws SerialException, SQLException
Retrieves a stream to be used to write Ascii characters to theCLOBvalue that thisSerialClobobject represents, starting at positionpos. This method forwards thesetAsciiStream()call to the underlyingClobobject in the event that thisSerialClobobject is instantiated with aClobobject. If thisSerialClobobject is instantiated with achararray, aSerialExceptionobject is thrown.- Specified by:
setAsciiStreamin interfaceClob- Parameters:
pos- the position at which to start writing to theCLOBobject- Returns:
- the stream to which ASCII encoded characters can be written
- Throws:
SerialException- if SerialClob is not instantiated with a Clob object; if thefreemethod had been previously called on this objectSQLException- if there is an error accessing theCLOBvalue- See Also:
getAsciiStream()
-
setCharacterStream
public Writer setCharacterStream(long pos) throws SerialException, SQLException
Retrieves a stream to be used to write a stream of Unicode characters to theCLOBvalue that thisSerialClobobject represents, at positionpos. This method forwards thesetCharacterStream()call to the underlyingClobobject in the event that thisSerialClobobject is instantiated with aClobobject. If thisSerialClobobject is instantiated with achararray, aSerialExceptionis thrown.- Specified by:
setCharacterStreamin interfaceClob- Parameters:
pos- the position at which to start writing to theCLOBvalue- Returns:
- a stream to which Unicode encoded characters can be written
- Throws:
SerialException- if the SerialClob is not instantiated with a Clob object; if thefreemethod had been previously called on this objectSQLException- if there is an error accessing theCLOBvalue- See Also:
getCharacterStream()
-
truncate
public void truncate(long length) throws SerialExceptionTruncates theCLOBvalue that thisSerialClobobject represents so that it has a length oflencharacters.Truncating a
SerialClobobject to length 0 has the effect of clearing its contents.- Specified by:
truncatein interfaceClob- Parameters:
length- the length, in bytes, to which theCLOBvalue should be truncated- Throws:
SerialException- if there is an error accessing theCLOBvalue; if thefreemethod had been previously called on this object
-
getCharacterStream
public Reader getCharacterStream(long pos, long length) throws SQLException
Returns aReaderobject that contains a partialSerialClobvalue, starting with the character specified by pos, which is length characters in length.- Specified by:
getCharacterStreamin interfaceClob- Parameters:
pos- the offset to the first character of the partial value to be retrieved. The first character in theSerialClobis at position 1.length- the length in characters of the partial value to be retrieved.- Returns:
Readerthrough which the partialSerialClobvalue can be read.- Throws:
SQLException- if pos is less than 1 or if pos is greater than the number of characters in theSerialClobor if pos + length is greater than the number of characters in theSerialClob;SerialException- if thefreemethod had been previously called on this object- Since:
- 1.6
-
free
public void free() throws SQLExceptionThis method frees theSerialClobobject and releases the resources that it holds. The object is invalid once thefreemethod is called.If
freeis called multiple times, the subsequent calls tofreeare treated as a no-op.- Specified by:
freein interfaceClob- Throws:
SQLException- if an error occurs releasing the Clob's resources- Since:
- 1.6
-
equals
public boolean equals(Object obj)
Compares this SerialClob to the specified object. The result istrueif and only if the argument is notnulland is aSerialClobobject that represents the same sequence of characters as this object.- Overrides:
equalsin classObject- Parameters:
obj- The object to compare thisSerialClobagainst- Returns:
trueif the given object represents aSerialClobequivalent to this SerialClob,falseotherwise- See Also:
Object.hashCode()
-
hashCode
public int hashCode()
Returns a hash code for thisSerialClob.- Overrides:
hashCodein classObject- Returns:
- a hash code value for this object.
- See Also:
Object.equals(java.lang.Object)
-
clone
public Object clone()
Returns a clone of thisSerialClob. The copy will contain a reference to a clone of the internal character array, not a reference to the original internal character array of thisSerialClobobject. The underlyingClobobject will be set to null.
-
-