SerialClob.java revision 0
3767N/A * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 2362N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * A serialized mapping in the Java programming language of an SQL 0N/A * <code>CLOB</code> value. 0N/A * The <code>SerialClob</code> class provides a constructor for creating 0N/A * an instance from a <code>Clob</code> object. Note that the <code>Clob</code> 0N/A * object should have brought the SQL <code>CLOB</code> value's data over 0N/A * to the client before a <code>SerialClob</code> object 0N/A * is constructed from it. The data of an SQL <code>CLOB</code> value can 0N/A * be materialized on the client as a stream of Unicode characters. 0N/A * <code>SerialClob</code> methods make it possible to get a substring 0N/A * from a <code>SerialClob</code> object or to locate the start of 0N/A * a pattern of characters. 0N/A * @author Jonathan Bruce 0N/A * A serialized array of characters containing the data of the SQL 0N/A * <code>CLOB</code> value that this <code>SerialClob</code> object 893N/A * Internal Clob representation if SerialClob is intialized with a 893N/A * The length in characters of this <code>SerialClob</code> object's 893N/A * internal array of characters. 893N/A * The original length in characters of tgus <code>SerialClob</code> 893N/A * objects internal array of characters. 893N/A * Constructs a <code>SerialClob</code> object that is a serialized version of 893N/A * the given <code>char</code> array. 893N/A * The new <code>SerialClob</code> object is initialized with the data from the 893N/A * <code>char</code> array, thus allowing disconnected <code>RowSet</code> 893N/A * objects to establish a serialized <code>Clob</code> object without touching 893N/A * @param ch the char array representing the <code>Clob</code> object to be 893N/A * @throws SerialException if an error occurs during serialization 893N/A * @throws SQLException if a SQL error occurs 0N/A // %%% JMB. Agreed. Add code here to throw a SQLException if no 524N/A // support is available for locatorsUpdateCopy=false 893N/A // Serializing locators is not supported. 0N/A * Constructs a <code>SerialClob</code> object that is a serialized 0N/A * version of the given <code>Clob</code> object. 893N/A * The new <code>SerialClob</code> object is initialized with the 893N/A * data from the <code>Clob</code> object; therefore, the 893N/A * <code>Clob</code> object should have previously brought the 893N/A * SQL <code>CLOB</code> value's data over to the client from 893N/A * the database. Otherwise, the new <code>SerialClob</code> object 893N/A * object will contain no data. 893N/A * Note: The <code>Clob</code> object supplied to this constructor cannot 893N/A * return <code>null</code> for the <code>Clob.getCharacterStream()</code> 893N/A * and <code>Clob.getAsciiStream</code> methods. This <code>SerialClob</code> 893N/A * constructor cannot serialize a <code>Clob</code> object in this instance 893N/A * and will throw an <code>SQLException</code> object. 893N/A * @param clob the <code>Clob</code> object from which this 0N/A * <code>SerialClob</code> object is to be constructed; cannot be null 0N/A * @throws SerialException if an error occurs during serialization 0N/A * @throws SQLException if a SQL error occurs in capturing the CLOB; 0N/A * if the <code>Clob</code> object is a null; or if both the 893N/A * <code>Clob.getCharacterStream()</code> and <code>Clob.getAsciiStream()</code> 893N/A * methods on the <code>Clob</code> return a null 893N/A "object with a null Clob object");
893N/A "and getAsciiStream return null which cannot be serialized.");
893N/A * Retrieves the number of characters in this <code>SerialClob</code> 893N/A * object's array of characters. 0N/A * @return a <code>long</code> indicating the length in characters of this 0N/A * <code>SerialClob</code> object's array of character 0N/A * @throws SerialException if an error occurs 893N/A * Returns this <code>SerialClob</code> object's data as a stream 0N/A * of Unicode characters. Unlike the related method, <code>getAsciiStream</code>, 0N/A * a stream is produced regardless of whether the <code>SerialClob</code> object 0N/A * was created with a <code>Clob</code> object or a <code>char</code> array. 0N/A * @return a <code>java.io.Reader</code> object containing this 893N/A * <code>SerialClob</code> object's data 0N/A * @throws SerialException if an error occurs 893N/A * Retrieves the <code>CLOB</code> value designated by this <code>SerialClob</code> 893N/A * object as an ascii stream. This method forwards the <code>getAsciiStream</code> 893N/A * call to the underlying <code>Clob</code> object in the event that this 893N/A * <code>SerialClob</code> object is instantiated with a <code>Clob</code> 893N/A * object. If this <code>SerialClob</code> object is instantiated with 893N/A * a <code>char</code> array, a <code>SerialException</code> object is thrown. 893N/A * @return a <code>java.io.InputStream</code> object containing 893N/A * this <code>SerialClob</code> object's data 893N/A * @throws SerialException if this <code>SerialClob</code> object was not instantiated 893N/A * with a <code>Clob</code> object 893N/A * @throws SQLException if there is an error accessing the 893N/A * <code>CLOB</code> value represented by the <code>Clob</code> object that was 893N/A * used to create this <code>SerialClob</code> object 893N/A "return a the CLOB value as an ascii stream, unless instantiated " +
893N/A "with a fully implemented Clob object.");
893N/A * Returns a copy of the substring contained in this 893N/A * <code>SerialClob</code> object, starting at the given position 893N/A * and continuing for the specified number or characters. 893N/A * @param pos the position of the first character in the substring 893N/A * to be copied; the first character of the 893N/A * <code>SerialClob</code> object is at position 0N/A * <code>1</code>; must not be less than <code>1</code>, 0N/A * and the sum of the starting position and the length 893N/A * of the substring must be less than the length of this 0N/A * <code>SerialClob</code> object 893N/A * @param length the number of characters in the substring to be 0N/A * returned; must not be greater than the length of 524N/A * this <code>SerialClob</code> object, and the 893N/A * sum of the starting position and the length 893N/A * of the substring must be less than the length of this 893N/A * <code>SerialClob</code> object 893N/A * @return a <code>String</code> object containing a substring of 893N/A * this <code>SerialClob</code> object beginning at the 893N/A * given position and containing the specified number of 893N/A * consecutive characters 893N/A * @throws SerialException if either of the arguments is out of bounds 4632N/A * Returns the position in this <code>SerialClob</code> object 4632N/A * where the given <code>String</code> object begins, starting 4700N/A * the search at the specified position. This method returns 4632N/A * <code>-1</code> if the pattern is not found. 4700N/A * @param searchStr the <code>String</code> object for which to 4632N/A * @param start the position in this <code>SerialClob</code> object 4632N/A * at which to start the search; the first position is 4632N/A * <code>1</code>; must not be less than <code>1</code> nor 4632N/A * greater than the length of this <code>SerialClob</code> object 4632N/A * @return the position at which the given <code>String</code> object 4632N/A * begins, starting the search at the specified position; 4632N/A * <code>-1</code> if the given <code>String</code> object is 4632N/A * not found or the starting position is out of bounds; position 4632N/A * numbering for the return value starts at <code>1</code> 4632N/A * @throws SerialException if an error occurs locating the String signature 4632N/A * @throws SQLException if there is an error accessing the Blob value 4700N/A * Returns the position in this <code>SerialClob</code> object 4700N/A * where the given <code>Clob</code> signature begins, starting 4700N/A * the search at the specified position. This method returns 4700N/A * <code>-1</code> if the pattern is not found. 4632N/A * @param searchStr the <code>Clob</code> object for which to search 4632N/A * @param start the position in this <code>SerialClob</code> object 4700N/A * at which to begin the search; the first position is 4700N/A * <code>1</code>; must not be less than <code>1</code> nor 4632N/A * greater than the length of this <code>SerialClob</code> object 4632N/A * @return the position at which the given <code>Clob</code> 4632N/A * object begins in this <code>SerialClob</code> object, 4632N/A * at or after the specified starting position 4632N/A * @throws SerialException if an error occurs locating the Clob signature 4632N/A * @throws SQLException if there is an error accessing the Blob value 4632N/A * Writes the given Java <code>String</code> to the <code>CLOB</code> 4632N/A * value that this <code>SerialClob</code> object represents, at the position 4632N/A * @param pos the position at which to start writing to the <code>CLOB</code> 4632N/A * value that this <code>SerialClob</code> object represents; the first 4632N/A * position is <code>1</code>; must not be less than <code>1</code> nor 4632N/A * greater than the length of this <code>SerialClob</code> object 4632N/A * @param str the string to be written to the <code>CLOB</code> 4632N/A * value that this <code>SerialClob</code> object represents 4632N/A * @return the number of characters written 4632N/A * @throws SerialException if there is an error accessing the 893N/A * <code>CLOB</code> value; if an invalid position is set; if an 0N/A * invalid offset value is set; if number of bytes to be written 0N/A * is greater than the <code>SerialClob</code> length; or the combined 893N/A * values of the length and offset is greater than the Clob buffer 0N/A * Writes <code>len</code> characters of <code>str</code>, starting 0N/A * at character <code>offset</code>, to the <code>CLOB</code> value 0N/A * that this <code>Clob</code> represents. 0N/A * @param pos the position at which to start writing to the <code>CLOB</code> 0N/A * value that this <code>SerialClob</code> object represents; the first 0N/A * position is <code>1</code>; must not be less than <code>1</code> nor 0N/A * greater than the length of this <code>SerialClob</code> object 0N/A * @param str the string to be written to the <code>CLOB</code> 0N/A * value that this <code>Clob</code> object represents 0N/A * @param offset the offset into <code>str</code> to start reading 0N/A * the characters to be written 0N/A * @param length the number of characters to be written 0N/A * @return the number of characters written 0N/A * @throws SerialException if there is an error accessing the 0N/A * <code>CLOB</code> value; if an invalid position is set; if an 0N/A * invalid offset value is set; if number of bytes to be written 0N/A * is greater than the <code>SerialClob</code> length; or the combined 0N/A * values of the length and offset is greater than the Clob buffer 0N/A // need check to ensure length + offset !> bytes.length 0N/A " and length that is greater that the Blob buffer");
0N/A pos--;
//values in the array are at position one less 4632N/A * Retrieves a stream to be used to write Ascii characters to the 0N/A * <code>CLOB</code> value that this <code>SerialClob</code> object represents, 0N/A * starting at position <code>pos</code>. This method forwards the 0N/A * <code>setAsciiStream()</code> call to the underlying <code>Clob</code> object in 0N/A * the event that this <code>SerialClob</code> object is instantiated with a 0N/A * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated 0N/A * with a <code>char</code> array, a <code>SerialException</code> object is thrown. 441N/A * @param pos the position at which to start writing to the 441N/A * <code>CLOB</code> object 0N/A * @return the stream to which ASCII encoded characters can be written 0N/A * @throws SerialException if SerialClob is not instantiated with a 0N/A * Clob object that supports <code>setAsciiStream</code> 0N/A * @throws SQLException if there is an error accessing the 0N/A * <code>CLOB</code> value 0N/A * @see #getAsciiStream 1776N/A "return a writable ascii stream\n unless instantiated with a Clob object " +
1776N/A "that has a setAsciiStream() implementation");
0N/A * Retrieves a stream to be used to write a stream of Unicode characters 0N/A * to the <code>CLOB</code> value that this <code>SerialClob</code> object 0N/A * represents, at position <code>pos</code>. This method forwards the 0N/A * <code>setCharacterStream()</code> call to the underlying <code>Clob</code> 0N/A * object in the event that this <code>SerialClob</code> object is instantiated with a 893N/A * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated with 0N/A * a <code>char</code> array, a <code>SerialException</code> is thrown. 749N/A * @param pos the position at which to start writing to the 749N/A * <code>CLOB</code> value 0N/A * @return a stream to which Unicode encoded characters can be written 0N/A * @throws SerialException if the SerialClob is not instantiated with 0N/A * a Clob object that supports <code>setCharacterStream</code> 0N/A * @throws SQLException if there is an error accessing the 0N/A * <code>CLOB</code> value 0N/A * @see #getCharacterStream 0N/A "return a writable character stream\n unless instantiated with a Clob object " +
0N/A "that has a setCharacterStream implementation");
0N/A * Truncates the <code>CLOB</code> value that this <code>SerialClob</code> 0N/A * object represents so that it has a length of <code>len</code> 1776N/A * Truncating a <code>SerialClob</code> object to length 0 has the effect of 0N/A * clearing its contents. 0N/A * @param length the length, in bytes, to which the <code>CLOB</code> 0N/A * value should be truncated 1776N/A * @throws SQLException if there is an error accessing the 0N/A * <code>CLOB</code> value 0N/A (
"Length more than what can be truncated");
0N/A // re-size the buffer 0N/A * The identifier that assists in the serialization of this <code>SerialClob</code>