public class SerialClob extends Object implements Clob, Serializable, Cloneable
CLOB value.
The SerialClob class provides a constructor for creating
an instance from a Clob object. Note that the Clob
object should have brought the SQL CLOB value's data over
to the client before a SerialClob object
is constructed from it. The data of an SQL CLOB value can
be materialized on the client as a stream of Unicode characters.
SerialClob methods make it possible to get a substring
from a SerialClob object or to locate the start of
a pattern of characters.
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.
| Constructor and Description |
|---|
SerialClob(char[] ch)
Constructs a
SerialClob object that is a serialized version of
the given char array. |
SerialClob(Clob clob)
Constructs a
SerialClob object that is a serialized
version of the given Clob object. |
| Modifier and Type | Method and Description |
|---|---|
Object |
clone()
Returns a clone of this
SerialClob. |
boolean |
equals(Object obj)
Compares this SerialClob to the specified object.
|
void |
free()
This method frees the
SeriableClob object and releases the
resources that it holds. |
InputStream |
getAsciiStream()
Retrieves the
CLOB value designated by this SerialClob
object as an ascii stream. |
Reader |
getCharacterStream()
Returns this
SerialClob object's data as a stream
of Unicode characters. |
Reader |
getCharacterStream(long pos,
long length)
Returns a
Reader object that contains a partial
SerialClob value, starting
with the character specified by pos, which is length characters in length. |
String |
getSubString(long pos,
int length)
Returns a copy of the substring contained in this
SerialClob object, starting at the given position
and continuing for the specified number or characters. |
int |
hashCode()
Returns a hash code for this
SerialClob. |
long |
length()
Retrieves the number of characters in this
SerialClob
object's array of characters. |
long |
position(Clob searchStr,
long start)
Returns the position in this
SerialClob object
where the given Clob signature begins, starting
the search at the specified position. |
long |
position(String searchStr,
long start)
Returns the position in this
SerialClob object
where the given String object begins, starting
the search at the specified position. |
OutputStream |
setAsciiStream(long pos)
Retrieves a stream to be used to write Ascii characters to the
CLOB value that this SerialClob object represents,
starting at position pos. |
Writer |
setCharacterStream(long pos)
Retrieves a stream to be used to write a stream of Unicode characters
to the
CLOB value that this SerialClob object
represents, at position pos. |
int |
setString(long pos,
String str)
Writes the given Java
String to the CLOB
value that this SerialClob object represents, at the position
pos. |
int |
setString(long pos,
String str,
int offset,
int length)
Writes
len characters of str, starting
at character offset, to the CLOB value
that this Clob represents. |
void |
truncate(long length)
Truncates the
CLOB value that this SerialClob
object represents so that it has a length of len
characters. |
public SerialClob(char[] ch)
throws SerialException,
SQLException
SerialClob object that is a serialized version of
the given char array.
The new SerialClob object is initialized with the data from the
char array, thus allowing disconnected RowSet
objects to establish a serialized Clob object without touching
the data source.
ch - the char array representing the Clob object to be
serializedSerialException - if an error occurs during serializationSQLException - if a SQL error occurspublic SerialClob(Clob clob) throws SerialException, SQLException
SerialClob object that is a serialized
version of the given Clob object.
The new SerialClob object is initialized with the
data from the Clob object; therefore, the
Clob object should have previously brought the
SQL CLOB value's data over to the client from
the database. Otherwise, the new SerialClob object
object will contain no data.
Note: The Clob object supplied to this constructor must
return non-null for both the Clob.getCharacterStream()
and Clob.getAsciiStream methods. This SerialClob
constructor cannot serialize a Clob object in this instance
and will throw an SQLException object.
clob - the Clob object from which this
SerialClob object is to be constructed; cannot be nullSerialException - if an error occurs during serializationSQLException - if a SQL error occurs in capturing the CLOB;
if the Clob object is a null; or if either of the
Clob.getCharacterStream() and Clob.getAsciiStream()
methods on the Clob returns a nullClobpublic long length()
throws SerialException
SerialClob
object's array of characters.length in interface Cloblong indicating the length in characters of this
SerialClob object's array of characterSerialException - if an error occurs;
if free had previously been called on this objectpublic Reader getCharacterStream() throws SerialException
SerialClob object's data as a stream
of Unicode characters. Unlike the related method, getAsciiStream,
a stream is produced regardless of whether the SerialClob object
was created with a Clob object or a char array.getCharacterStream in interface Clobjava.io.Reader object containing this
SerialClob object's dataSerialException - if an error occurs;
if free had previously been called on this objectClob.setCharacterStream(long)public InputStream getAsciiStream() throws SerialException, SQLException
CLOB value designated by this SerialClob
object as an ascii stream. This method forwards the getAsciiStream
call to the underlying Clob object in the event that this
SerialClob object is instantiated with a Clob
object. If this SerialClob object is instantiated with
a char array, a SerialException object is thrown.getAsciiStream in interface Clobjava.io.InputStream object containing
this SerialClob object's dataSerialException - if this SerialClob object was not
instantiated with a Clob object;
if free had previously been called on this objectSQLException - if there is an error accessing the
CLOB value represented by the Clob object
that was used to create this SerialClob objectClob.setAsciiStream(long)public String getSubString(long pos, int length) throws SerialException
SerialClob object, starting at the given position
and continuing for the specified number or characters.getSubString in interface Clobpos - the position of the first character in the substring
to be copied; the first character of the
SerialClob object is at position
1; must not be less than 1,
and the sum of the starting position and the length
of the substring must be less than the length of this
SerialClob objectlength - the number of characters in the substring to be
returned; must not be greater than the length of
this SerialClob object, and the
sum of the starting position and the length
of the substring must be less than the length of this
SerialClob objectString object containing a substring of
this SerialClob object beginning at the
given position and containing the specified number of
consecutive charactersSerialException - if either of the arguments is out of bounds;
if free had previously been called on this objectpublic long position(String searchStr, long start) throws SerialException, SQLException
SerialClob object
where the given String object begins, starting
the search at the specified position. This method returns
-1 if the pattern is not found.position in interface ClobsearchStr - the String object for which to
searchstart - the position in this SerialClob object
at which to start the search; the first position is
1; must not be less than 1 nor
greater than the length of this SerialClob objectString object
begins, starting the search at the specified position;
-1 if the given String object is
not found or the starting position is out of bounds; position
numbering for the return value starts at 1SerialException - if the free method had been
previously called on this objectSQLException - if there is an error accessing the Clob value
from the database.public long position(Clob searchStr, long start) throws SerialException, SQLException
SerialClob object
where the given Clob signature begins, starting
the search at the specified position. This method returns
-1 if the pattern is not found.position in interface ClobsearchStr - the Clob object for which to searchstart - the position in this SerialClob object
at which to begin the search; the first position is
1; must not be less than 1 nor
greater than the length of this SerialClob objectClob
object begins in this SerialClob object,
at or after the specified starting positionSerialException - if an error occurs locating the Clob signature;
if the free method had been previously called on this objectSQLException - if there is an error accessing the Clob value
from the databasepublic int setString(long pos,
String str)
throws SerialException
String to the CLOB
value that this SerialClob object represents, at the position
pos.setString in interface Clobpos - the position at which to start writing to the CLOB
value that this SerialClob object represents; the first
position is 1; must not be less than 1 nor
greater than the length of this SerialClob objectstr - the string to be written to the CLOB
value that this SerialClob object representsSerialException - if there is an error accessing the
CLOB value; if an invalid position is set; if an
invalid offset value is set; if number of bytes to be written
is greater than the SerialClob length; or the combined
values of the length and offset is greater than the Clob buffer;
if the free method had been previously called on this objectpublic int setString(long pos,
String str,
int offset,
int length)
throws SerialException
len characters of str, starting
at character offset, to the CLOB value
that this Clob represents.setString in interface Clobpos - the position at which to start writing to the CLOB
value that this SerialClob object represents; the first
position is 1; must not be less than 1 nor
greater than the length of this SerialClob objectstr - the string to be written to the CLOB
value that this Clob object representsoffset - the offset into str to start reading
the characters to be writtenlength - the number of characters to be writtenSerialException - if there is an error accessing the
CLOB value; if an invalid position is set; if an
invalid offset value is set; if number of bytes to be written
is greater than the SerialClob length; or the combined
values of the length and offset is greater than the Clob buffer;
if the free method had been previously called on this objectpublic OutputStream setAsciiStream(long pos) throws SerialException, SQLException
CLOB value that this SerialClob object represents,
starting at position pos. This method forwards the
setAsciiStream() call to the underlying Clob object in
the event that this SerialClob object is instantiated with a
Clob object. If this SerialClob object is instantiated
with a char array, a SerialException object is thrown.setAsciiStream in interface Clobpos - the position at which to start writing to the
CLOB objectSerialException - if SerialClob is not instantiated with a
Clob object;
if the free method had been previously called on this objectSQLException - if there is an error accessing the
CLOB valuegetAsciiStream()public Writer setCharacterStream(long pos) throws SerialException, SQLException
CLOB value that this SerialClob object
represents, at position pos. This method forwards the
setCharacterStream() call to the underlying Clob
object in the event that this SerialClob object is instantiated with a
Clob object. If this SerialClob object is instantiated with
a char array, a SerialException is thrown.setCharacterStream in interface Clobpos - the position at which to start writing to the
CLOB valueSerialException - if the SerialClob is not instantiated with
a Clob object;
if the free method had been previously called on this objectSQLException - if there is an error accessing the
CLOB valuegetCharacterStream()public void truncate(long length)
throws SerialException
CLOB value that this SerialClob
object represents so that it has a length of len
characters.
Truncating a SerialClob object to length 0 has the effect of
clearing its contents.
truncate in interface Cloblength - the length, in bytes, to which the CLOB
value should be truncatedSerialException - if there is an error accessing the
CLOB value;
if the free method had been previously called on this objectpublic Reader getCharacterStream(long pos, long length) throws SQLException
Reader object that contains a partial
SerialClob value, starting
with the character specified by pos, which is length characters in length.getCharacterStream in interface Clobpos - the offset to the first character of the partial value to
be retrieved. The first character in the SerialClob is at position 1.length - the length in characters of the partial value to be retrieved.Reader through which the partial SerialClob
value can be read.SQLException - if pos is less than 1 or if pos is greater than the
number of characters in the SerialClob or if pos + length
is greater than the number of characters in the SerialClob;SerialException - if the free method had been previously
called on this objectpublic void free()
throws SQLException
SeriableClob object and releases the
resources that it holds.
The object is invalid once the free method is called.
If free is called multiple times, the subsequent
calls to free are treated as a no-op.
free in interface ClobSQLException - if an error occurs releasing
the Clob's resourcespublic boolean equals(Object obj)
true if and only if the argument is not null and is a SerialClob object that represents the same sequence of characters as this
object.equals in class Objectobj - The object to compare this SerialClob againsttrue if the given object represents a SerialClob
equivalent to this SerialClob, false otherwiseObject.hashCode(),
HashMappublic int hashCode()
SerialClob.hashCode in class ObjectObject.equals(java.lang.Object),
System.identityHashCode(java.lang.Object)public Object clone()
SerialClob. The copy will contain a
reference to a clone of the internal character array, not a reference
to the original internal character array of this SerialClob object.
The underlying Clob object will be set to null. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2025, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.