00001 /** 00002 * C-JDBC: Clustered JDBC. 00003 * Copyright (C) 2002-2004 French National Institute For Research In Computer 00004 * Science And Control (INRIA). 00005 * Contact: c-jdbc@objectweb.org 00006 * 00007 * This library is free software; you can redistribute it and/or modify it 00008 * under the terms of the GNU Lesser General Public License as published by the 00009 * Free Software Foundation; either version 2.1 of the License, or any later 00010 * version. 00011 * 00012 * This library is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00014 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 00015 * for more details. 00016 * 00017 * You should have received a copy of the GNU Lesser General Public License 00018 * along with this library; if not, write to the Free Software Foundation, 00019 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 00020 * 00021 * Initial developer(s): Nicolas Modrzyk. 00022 * Contributor(s): ______________________________________. 00023 */ 00024 00025 package org.objectweb.cjdbc.driver; 00026 00027 import java.io.ByteArrayInputStream; 00028 import java.io.OutputStream; 00029 import java.io.Serializable; 00030 import java.io.StringReader; 00031 import java.io.Writer; 00032 import java.sql.SQLException; 00033 00034 import org.objectweb.cjdbc.common.sql.NotImplementedException; 00035 00036 /** 00037 * The representation (mapping) in the Java <sup><small>TM </small> </sup> 00038 * programming language of an SQL <code>CLOB</code> value. An SQL 00039 * <code>CLOB</code> is a built-in type that stores a Character Large Object 00040 * as a column value in a row of a database table. By default drivers implement 00041 * <code>Clob</code> using an SQL <code>locator(CLOB)</code>, which means 00042 * that a <code>Clob</code> object contains a logical pointer to the SQL 00043 * <code>CLOB</code> data rather than the data itself. A <code>Clob</code> 00044 * object is valid for the duration of the transaction in which is was created. 00045 * <p> 00046 * Methods in the interfaces {@link DriverResultSet},{@link CallableStatement}, 00047 * and {@link PreparedStatement}, such as <code>getClob</code> and 00048 * <code>setClob</code> allow a programmer to access an SQL <code>CLOB</code> 00049 * value. The <code>Clob</code> interface provides methods for getting the 00050 * length of an SQL <code>CLOB</code> (Character Large Object) value, for 00051 * materializing a <code>CLOB</code> value on the client, and for determining 00052 * the position of a pattern of bytes within a <code>CLOB</code> value. In 00053 * addition, this interface has methods for updating a <code>CLOB</code> 00054 * value. 00055 * 00056 * @author <a href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a> 00057 * @since JDK 1.2 00058 */ 00059 public class Clob implements java.sql.Clob, Serializable 00060 { 00061 /** The data represented as a string of this <code>CLOB</code> */ 00062 private String stringData = null; 00063 00064 /** 00065 * Creates a new <code>Clob</code> instance. 00066 * 00067 * @param data a <code>String</code> of character data 00068 */ 00069 public Clob(String data) 00070 { 00071 stringData = data; 00072 } 00073 00074 /** 00075 * Returns the size of the <code>CLOB</code> value designated by this 00076 * <code>Clob</code> object 00077 * 00078 * @return length of the <code>CLOB</code> value that this <code>clob</code> 00079 * represents 00080 * @exception SQLException if there is an error accessing the length of the 00081 * <code>CLOB</code> 00082 * @since JDK 1.2 00083 */ 00084 public long length() throws SQLException 00085 { 00086 return stringData.length(); 00087 } 00088 00089 /** 00090 * Retrieves the <code>CLOB</code> value designated by this 00091 * <code>Clob</code> instance as a stream. 00092 * 00093 * @return a stream containing the <code>CLOB</code> data 00094 * @exception SQLException if there is an error accessing the 00095 * <code>CLOB</code> value 00096 * @since JDK 1.2 00097 */ 00098 public java.io.InputStream getAsciiStream() throws SQLException 00099 { 00100 return new ByteArrayInputStream(stringData.getBytes()); 00101 } 00102 00103 /** 00104 * Materializes the <code>CLOB</code> value designated by this <Code>object 00105 * as a stream of Unicode character. 00106 * 00107 * @return A reader object with all the data in the <code>CLOB</code> value 00108 * designated by this clob object as unicode characters. 00109 * @exception SQLException if there is an error accessing the 00110 * <code>CLOB</code> value 00111 */ 00112 public java.io.Reader getCharacterStream() throws SQLException 00113 { 00114 return new StringReader(stringData); 00115 } 00116 00117 /** 00118 * Returns a copy of the portion of the <code>CLOB</code> value represented 00119 * by this <code>CLOB</code> object that starts at position <i>position </i> 00120 * and has ip to <i>length </i> consecutive characters. 00121 * 00122 * @param pos the position where to get the substring from 00123 * @param length the length of the substring 00124 * @return the substring 00125 * @exception SQLException if there is an error accessing the 00126 * <code>CLOB</code> 00127 * @since JDK 1.2 00128 */ 00129 public String getSubString(long pos, int length) throws SQLException 00130 { 00131 if (length > stringData.length()) 00132 throw new SQLException("Clob contains only " + stringData.length() 00133 + " characters (asking for " + length + ")."); 00134 return stringData.substring((int) pos, length); 00135 } 00136 00137 /** 00138 * Retrieves the character position at which the specified string 00139 * <code>searchstr</code> begins within the <code>CLOB</code> value that 00140 * this <code>Clob</code> object represents. The search for 00141 * <code>searchstr</code> begins at position <code>start</code>. 00142 * 00143 * @param searchstr the byte array for which to search 00144 * @param start the position at which to begin searching; the first position 00145 * is 1 00146 * @return the position at which the pattern appears, else -1 00147 * @exception SQLException if there is an error accessing the 00148 * <code>CLOB</code> 00149 * @since JDK 1.2 00150 */ 00151 public long position(String searchstr, long start) throws SQLException 00152 { 00153 return stringData.indexOf(searchstr, (int) start); 00154 } 00155 00156 /** 00157 * Retrieves the character position at which the specified <code>Clob</code> 00158 * object <code>searchstr</code> begins within the <code>CLOB</code> value 00159 * that this <code>Clob</code> object represents. The search for 00160 * <code>searchstr</code> begins at position <code>start</code>. 00161 * 00162 * @param searchstr the byte array for which to search 00163 * @param start the position at which to begin searching; the first position 00164 * is 1 00165 * @return the position at which the pattern appears, else -1 00166 * @exception SQLException if there is an error accessing the 00167 * <code>CLOB</code> 00168 * @since JDK 1.2 00169 */ 00170 public long position(java.sql.Clob searchstr, long start) throws SQLException 00171 { 00172 return position(searchstr.getSubString(0, (int) searchstr.length()), 00173 (int) start); 00174 } 00175 00176 // -------------------------- JDBC 3.0 ----------------------------------- 00177 00178 /** 00179 * Retrieves a stream to be used to write Ascii characters to the CLOB value 00180 * that this Clob object represents, starting at position pos. 00181 * 00182 * @param pos the position where to start the stream 00183 * @return the ascii outputstream to this <code>clob</code> object 00184 * @throws SQLException if there is an error accessing the <code>clob</code> 00185 */ 00186 public OutputStream setAsciiStream(long pos) throws SQLException 00187 { 00188 throw new NotImplementedException("setAsciiStream"); 00189 } 00190 00191 /** 00192 * Retrieves a stream to be used to write a stream of Unicode characters to 00193 * the CLOB value that this Clob object represents, at position pos. 00194 * 00195 * @param pos the position where to start the writer 00196 * @return the writer to this <code>clob</code> object 00197 * @throws SQLException if there is an error accessing the <code>clob</code> 00198 */ 00199 public Writer setCharacterStream(long pos) throws SQLException 00200 { 00201 throw new NotImplementedException("setCharacterStream"); 00202 } 00203 00204 /** 00205 * Writes the given Java String to the CLOB value that this Clob object 00206 * designates at the position pos. 00207 * 00208 * @param pos the position where to set the string 00209 * @param str string to insert in the <code>clob</code> 00210 * @return return value 00211 * @throws SQLException if there is an error accessing the <code>clob</code> 00212 */ 00213 public int setString(long pos, String str) throws SQLException 00214 { 00215 throw new NotImplementedException("setString"); 00216 } 00217 00218 /** 00219 * Writes len characters of str, starting at character offset, to the CLOB 00220 * value that this Clob represents. 00221 * 00222 * @param pos the position 00223 * @param str the string 00224 * @param offset the offset 00225 * @param len the length 00226 * @return return value 00227 * @throws SQLException if there is an error accessing the <code>clob</code> 00228 */ 00229 public int setString(long pos, String str, int offset, int len) 00230 throws SQLException 00231 { 00232 throw new NotImplementedException("setString"); 00233 } 00234 00235 /** 00236 * Truncates the CLOB value that this Clob designates to have a length of len 00237 * characters. 00238 * 00239 * @param len the length 00240 * @throws SQLException if there is an error accessing the <code>clob</code> 00241 */ 00242 public void truncate(long len) throws SQLException 00243 { 00244 throw new NotImplementedException("truncate"); 00245 } 00246 }