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.
*
* @author Jonathan Bruce
*/
public class SerialClob implements Clob, Serializable, Cloneable {
/**
* A serialized array of characters containing the data of the SQL
* CLOB value that this SerialClob object
* represents.
*
* @serial
*/
private char buf[];
/**
* Internal Clob representation if SerialClob is initialized with a
* Clob. Null if SerialClob is initialized with a char[].
*/
private final Clob clob;
/**
* The length in characters of this SerialClob object's
* internal array of characters.
*
* @serial
*/
private long len;
/**
* The original length in characters of this SerialClob
* object's internal array of characters.
*
* @serial
*/
private final long origLen;
/**
* Constructs a 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.
*
* @param ch the char array representing the Clob object to be
* serialized
* @throws SerialException if an error occurs during serialization
* @throws SQLException if a SQL error occurs
*/
public SerialClob(char ch[]) throws SerialException, SQLException {
// %%% JMB. Agreed. Add code here to throw a SQLException if no
// support is available for locatorsUpdateCopy=false
// Serializing locators is not supported.
len = ch.length;
buf = new char[(int)len];
for (int i = 0; i < len ; i++){
buf[i] = ch[i];
}
origLen = len;
clob = null;
}
/**
* Constructs a 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.
*
* @param clob the Clob object from which this
* SerialClob object is to be constructed; cannot be null
* @throws SerialException if an error occurs during serialization
* @throws SQLException 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 null
* @see java.sql.Clob
*/
public SerialClob(Clob clob) throws SerialException, SQLException {
if (clob == null) {
throw new SQLException("Cannot instantiate a SerialClob " +
"object with a null Clob object");
}
len = clob.length();
this.clob = clob;
buf = new char[(int)len];
int read = 0;
int offset = 0;
try (Reader charStream = clob.getCharacterStream()) {
if (charStream == null) {
throw new SQLException("Invalid Clob object. The call to getCharacterStream " +
"returned null which cannot be serialized.");
}
// Note: get an ASCII stream in order to null-check it,
// even though we don't do anything with it.
try (InputStream asciiStream = clob.getAsciiStream()) {
if (asciiStream == null) {
throw new SQLException("Invalid Clob object. The call to getAsciiStream " +
"returned null which cannot be serialized.");
}
}
try (Reader reader = new BufferedReader(charStream)) {
do {
read = reader.read(buf, offset, (int)(len - offset));
offset += read;
} while (read > 0);
}
} catch (java.io.IOException ex) {
throw new SerialException("SerialClob: " + ex.getMessage());
}
origLen = len;
}
/**
* Retrieves the number of characters in this SerialClob
* object's array of characters.
*
* @return a long indicating the length in characters of this
* SerialClob object's array of character
* @throws SerialException if an error occurs
*/
public long length() throws SerialException {
return len;
}
/**
* Returns this 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.
*
* @return a java.io.Reader object containing this
* SerialClob object's data
* @throws SerialException if an error occurs
*/
public java.io.Reader getCharacterStream() throws SerialException {
return (java.io.Reader) new CharArrayReader(buf);
}
/**
* Retrieves the 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.
*
* @return a java.io.InputStream object containing
* this SerialClob object's data
* @throws SerialException if this SerialClob object was not instantiated
* with a Clob object
* @throws SQLException if there is an error accessing the
* CLOB value represented by the Clob object that was
* used to create this SerialClob object
*/
public java.io.InputStream getAsciiStream() throws SerialException, SQLException {
if (this.clob != null) {
return this.clob.getAsciiStream();
} else {
throw new SerialException("Unsupported operation. SerialClob cannot " +
"return a the CLOB value as an ascii stream, unless instantiated " +
"with a fully implemented Clob object.");
}
}
/**
* Returns a copy of the substring contained in this
* SerialClob object, starting at the given position
* and continuing for the specified number or characters.
*
* @param pos 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 object
* @param length 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 object
* @return a String object containing a substring of
* this SerialClob object beginning at the
* given position and containing the specified number of
* consecutive characters
* @throws SerialException if either of the arguments is out of bounds
*/
public String getSubString(long pos, int length) throws SerialException {
if (pos < 1 || pos > this.length()) {
throw new SerialException("Invalid position in BLOB object set");
}
if ((pos-1) + length > this.length()) {
throw new SerialException("Invalid position and substring length");
}
try {
return new String(buf, (int)pos - 1, length);
} catch (StringIndexOutOfBoundsException e) {
throw new SerialException("StringIndexOutOfBoundsException: " +
e.getMessage());
}
}
/**
* Returns the position in this 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.
*
* @param searchStr the String object for which to
* search
* @param start 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 object
* @return the position at which the given String 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 1
* @throws SerialException if an error occurs locating the String signature
* @throws SQLException if there is an error accessing the Blob value
* from the database.
*/
public long position(String searchStr, long start)
throws SerialException, SQLException {
if (start < 1 || start > len) {
return -1;
}
char pattern[] = searchStr.toCharArray();
int pos = (int)start-1;
int i = 0;
long patlen = pattern.length;
while (pos < len) {
if (pattern[i] == buf[pos]) {
if (i + 1 == patlen) {
return (pos + 1) - (patlen - 1);
}
i++; pos++; // increment pos, and i
} else if (pattern[i] != buf[pos]) {
pos++; // increment pos only
}
}
return -1; // not found
}
/**
* Returns the position in this 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.
*
* @param searchStr the Clob object for which to search
* @param start 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 object
* @return the position at which the given Clob
* object begins in this SerialClob object,
* at or after the specified starting position
* @throws SerialException if an error occurs locating the Clob signature
* @throws SQLException if there is an error accessing the Blob value
* from the database
*/
public long position(Clob searchStr, long start)
throws SerialException, SQLException {
return position(searchStr.getSubString(1,(int)searchStr.length()), start);
}
/**
* Writes the given Java String to the CLOB
* value that this SerialClob object represents, at the position
* pos.
*
* @param pos 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 object
* @param str the string to be written to the CLOB
* value that this SerialClob object represents
* @return the number of characters written
* @throws SerialException 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
*/
public int setString(long pos, String str) throws SerialException {
return (setString(pos, str, 0, str.length()));
}
/**
* Writes len characters of str, starting
* at character offset, to the CLOB value
* that this Clob represents.
*
* @param pos 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 object
* @param str the string to be written to the CLOB
* value that this Clob object represents
* @param offset the offset into str to start reading
* the characters to be written
* @param length the number of characters to be written
* @return the number of characters written
* @throws SerialException 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
*/
public int setString(long pos, String str, int offset, int length)
throws SerialException {
String temp = str.substring(offset);
char cPattern[] = temp.toCharArray();
if (offset < 0 || offset > str.length()) {
throw new SerialException("Invalid offset in byte array set");
}
if (pos < 1 || pos > this.length()) {
throw new SerialException("Invalid position in BLOB object set");
}
if ((long)(length) > origLen) {
throw new SerialException("Buffer is not sufficient to hold the value");
}
if ((length + offset) > str.length()) {
// need check to ensure length + offset !> bytes.length
throw new SerialException("Invalid OffSet. Cannot have combined offset " +
" and length that is greater that the Blob buffer");
}
int i = 0;
pos--; //values in the array are at position one less
while ( i < length || (offset + i +1) < (str.length() - offset ) ) {
this.buf[(int)pos + i ] = cPattern[offset + i ];
i++;
}
return i;
}
/**
* Retrieves a stream to be used to write Ascii characters to the
* 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.
*
* @param pos the position at which to start writing to the
* CLOB object
* @return the stream to which ASCII encoded characters can be written
* @throws SerialException if SerialClob is not instantiated with a
* Clob object that supports setAsciiStream
* @throws SQLException if there is an error accessing the
* CLOB value
* @see #getAsciiStream
*/
public java.io.OutputStream setAsciiStream(long pos)
throws SerialException, SQLException {
if (this.clob.setAsciiStream(pos) != null) {
return this.clob.setAsciiStream(pos);
} else {
throw new SerialException("Unsupported operation. SerialClob cannot " +
"return a writable ascii stream\n unless instantiated with a Clob object " +
"that has a setAsciiStream() implementation");
}
}
/**
* 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. 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.
*
* @param pos the position at which to start writing to the
* CLOB value
*
* @return a stream to which Unicode encoded characters can be written
* @throws SerialException if the SerialClob is not instantiated with
* a Clob object that supports setCharacterStream
* @throws SQLException if there is an error accessing the
* CLOB value
* @see #getCharacterStream
*/
public java.io.Writer setCharacterStream(long pos)
throws SerialException, SQLException {
if (this.clob.setCharacterStream(pos) != null) {
return this.clob.setCharacterStream(pos);
} else {
throw new SerialException("Unsupported operation. SerialClob cannot " +
"return a writable character stream\n unless instantiated with a Clob object " +
"that has a setCharacterStream implementation");
}
}
/**
* Truncates the 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.
*
* @param length the length, in bytes, to which the CLOB
* value should be truncated
* @throws SQLException if there is an error accessing the
* CLOB value
*/
public void truncate(long length) throws SerialException {
if (length > len) {
throw new SerialException
("Length more than what can be truncated");
} else {
len = length;
// re-size the buffer
if (len == 0) {
buf = new char[] {};
} else {
buf = (this.getSubString(1, (int)len)).toCharArray();
}
}
}
public Reader getCharacterStream(long pos, long length) throws SQLException {
throw new java.lang.UnsupportedOperationException("Not supported");
}
public void free() throws SQLException {
throw new java.lang.UnsupportedOperationException("Not supported");
}
/**
* The identifier that assists in the serialization of this SerialClob
* object.
*/
static final long serialVersionUID = -1662519690087375313L;
}