KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > cjdbc > driver > Clob


1 /**
2  * C-JDBC: Clustered JDBC.
3  * Copyright (C) 2002-2005 French National Institute For Research In Computer
4  * Science And Control (INRIA).
5  * Contact: c-jdbc@objectweb.org
6  *
7  * This library is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as published by the
9  * Free Software Foundation; either version 2.1 of the License, or any later
10  * version.
11  *
12  * This library is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
15  * for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License
18  * along with this library; if not, write to the Free Software Foundation,
19  * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
20  *
21  * Initial developer(s): Nicolas Modrzyk.
22  * Contributor(s): Emmanuel Cecchet.
23  */
24
25 package org.objectweb.cjdbc.driver;
26
27 import java.io.ByteArrayInputStream JavaDoc;
28 import java.io.OutputStream JavaDoc;
29 import java.io.Serializable JavaDoc;
30 import java.io.StringReader JavaDoc;
31 import java.io.Writer JavaDoc;
32 import java.sql.SQLException JavaDoc;
33
34 import org.objectweb.cjdbc.common.exceptions.NotImplementedException;
35
36 /**
37  * The representation (mapping) in the Java <sup><small>TM </small> </sup>
38  * programming language of an SQL <code>CLOB</code> value. An SQL
39  * <code>CLOB</code> is a built-in type that stores a Character Large Object
40  * as a column value in a row of a database table. By default drivers implement
41  * <code>Clob</code> using an SQL <code>locator(CLOB)</code>, which means
42  * that a <code>Clob</code> object contains a logical pointer to the SQL
43  * <code>CLOB</code> data rather than the data itself. A <code>Clob</code>
44  * object is valid for the duration of the transaction in which is was created.
45  * <p>
46  * Methods in the interfaces {@link DriverResultSet},{@link CallableStatement},
47  * and {@link PreparedStatement}, such as <code>getClob</code> and
48  * <code>setClob</code> allow a programmer to access an SQL <code>CLOB</code>
49  * value. The <code>Clob</code> interface provides methods for getting the
50  * length of an SQL <code>CLOB</code> (Character Large Object) value, for
51  * materializing a <code>CLOB</code> value on the client, and for determining
52  * the position of a pattern of bytes within a <code>CLOB</code> value. In
53  * addition, this interface has methods for updating a <code>CLOB</code>
54  * value.
55  *
56  * @author <a HREF="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
57  * @author <a HREF="mailto:Emmanuel.Cecchet@emicnetworks.fr">Emmanuel Cecchet
58  * </a>
59  * @since JDK 1.2
60  */
61 public class Clob implements java.sql.Clob JavaDoc, Serializable JavaDoc
62 {
63   private static final long serialVersionUID = 1832832422588968988L;
64
65   /** The data represented as a string of this <code>CLOB</code> */
66   private String JavaDoc stringData = null;
67
68   /**
69    * Creates a new <code>Clob</code> instance.
70    *
71    * @param data a <code>String</code> of character data
72    */
73   public Clob(String JavaDoc data)
74   {
75     stringData = data;
76   }
77
78   /**
79    * Returns the size of the <code>CLOB</code> value designated by this
80    * <code>Clob</code> object
81    *
82    * @return length of the <code>CLOB</code> value that this <code>clob</code>
83    * represents
84    * @exception SQLException if there is an error accessing the length of the
85    * <code>CLOB</code>
86    * @since JDK 1.2
87    */
88   public long length() throws SQLException JavaDoc
89   {
90     return stringData.length();
91   }
92
93   /**
94    * Retrieves the <code>CLOB</code> value designated by this
95    * <code>Clob</code> instance as a stream.
96    *
97    * @return a stream containing the <code>CLOB</code> data
98    * @exception SQLException if there is an error accessing the
99    * <code>CLOB</code> value
100    * @since JDK 1.2
101    */
102   public java.io.InputStream JavaDoc getAsciiStream() throws SQLException JavaDoc
103   {
104     return new ByteArrayInputStream JavaDoc(stringData.getBytes());
105   }
106
107   /**
108    * Materializes the <code>CLOB</code> value designated by this <Code>object
109    * as a stream of Unicode character.
110    *
111    * @return A reader object with all the data in the <code>CLOB</code> value
112    * designated by this clob object as unicode characters.
113    * @exception SQLException if there is an error accessing the
114    * <code>CLOB</code> value
115    */
116   public java.io.Reader JavaDoc getCharacterStream() throws SQLException JavaDoc
117   {
118     return new StringReader JavaDoc(stringData);
119   }
120
121   /**
122    * Returns a copy of the portion of the <code>CLOB</code> value represented
123    * by this <code>CLOB</code> object that starts at position <i>position </i>
124    * and has ip to <i>length </i> consecutive characters.
125    *
126    * @param pos the position where to get the substring from
127    * @param length the length of the substring
128    * @return the substring
129    * @exception SQLException if there is an error accessing the
130    * <code>CLOB</code>
131    * @since JDK 1.2
132    */
133   public String JavaDoc getSubString(long pos, int length) throws SQLException JavaDoc
134   {
135     if (length > stringData.length())
136       throw new SQLException JavaDoc("Clob contains only " + stringData.length()
137           + " characters (asking for " + length + ").");
138     return stringData.substring((int) pos, length);
139   }
140
141   /**
142    * Retrieves the character position at which the specified string
143    * <code>searchstr</code> begins within the <code>CLOB</code> value that
144    * this <code>Clob</code> object represents. The search for
145    * <code>searchstr</code> begins at position <code>start</code>.
146    *
147    * @param searchstr the byte array for which to search
148    * @param start the position at which to begin searching; the first position
149    * is 1
150    * @return the position at which the pattern appears, else -1
151    * @exception SQLException if there is an error accessing the
152    * <code>CLOB</code>
153    * @since JDK 1.2
154    */
155   public long position(String JavaDoc searchstr, long start) throws SQLException JavaDoc
156   {
157     return stringData.indexOf(searchstr, (int) start);
158   }
159
160   /**
161    * Retrieves the character position at which the specified <code>Clob</code>
162    * object <code>searchstr</code> begins within the <code>CLOB</code> value
163    * that this <code>Clob</code> object represents. The search for
164    * <code>searchstr</code> begins at position <code>start</code>.
165    *
166    * @param searchstr the byte array for which to search
167    * @param start the position at which to begin searching; the first position
168    * is 1
169    * @return the position at which the pattern appears, else -1
170    * @exception SQLException if there is an error accessing the
171    * <code>CLOB</code>
172    * @since JDK 1.2
173    */
174   public long position(java.sql.Clob JavaDoc searchstr, long start) throws SQLException JavaDoc
175   {
176     return position(searchstr.getSubString(0, (int) searchstr.length()),
177         (int) start);
178   }
179
180   // -------------------------- JDBC 3.0 -----------------------------------
181
182   /**
183    * Retrieves a stream to be used to write Ascii characters to the CLOB value
184    * that this Clob object represents, starting at position pos.
185    *
186    * @param pos the position where to start the stream
187    * @return the ascii outputstream to this <code>clob</code> object
188    * @throws SQLException if there is an error accessing the <code>clob</code>
189    */
190   public OutputStream JavaDoc setAsciiStream(long pos) throws SQLException JavaDoc
191   {
192     throw new NotImplementedException("setAsciiStream");
193   }
194
195   /**
196    * Retrieves a stream to be used to write a stream of Unicode characters to
197    * the CLOB value that this Clob object represents, at position pos.
198    *
199    * @param pos the position where to start the writer
200    * @return the writer to this <code>clob</code> object
201    * @throws SQLException if there is an error accessing the <code>clob</code>
202    */
203   public Writer JavaDoc setCharacterStream(long pos) throws SQLException JavaDoc
204   {
205     throw new NotImplementedException("setCharacterStream");
206   }
207
208   /**
209    * Writes the given Java String to the CLOB value that this Clob object
210    * designates at the position pos.
211    *
212    * @param pos the position where to set the string
213    * @param str string to insert in the <code>clob</code>
214    * @return return value
215    * @throws SQLException if there is an error accessing the <code>clob</code>
216    */
217   public int setString(long pos, String JavaDoc str) throws SQLException JavaDoc
218   {
219     throw new NotImplementedException("setString");
220   }
221
222   /**
223    * Writes len characters of str, starting at character offset, to the CLOB
224    * value that this Clob represents.
225    *
226    * @param pos the position
227    * @param str the string
228    * @param offset the offset
229    * @param len the length
230    * @return return value
231    * @throws SQLException if there is an error accessing the <code>clob</code>
232    */
233   public int setString(long pos, String JavaDoc str, int offset, int len)
234       throws SQLException JavaDoc
235   {
236     throw new NotImplementedException("setString");
237   }
238
239   /**
240    * Truncates the CLOB value that this Clob designates to have a length of len
241    * characters.
242    *
243    * @param len the length
244    * @throws SQLException if there is an error accessing the <code>clob</code>
245    */
246   public void truncate(long len) throws SQLException JavaDoc
247   {
248     throw new NotImplementedException("truncate");
249   }
250 }
Popular Tags