KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > continuent > sequoia > common > protocol > StringClob


1 /**
2  * Sequoia: Database clustering technology.
3  * Copyright (C) 2002-2004 French National Institute For Research In Computer
4  * Science And Control (INRIA).
5  * Copyright (C) 2005 AmicoSoft, Inc. dba Emic Networks
6  * Contact: sequoia@continuent.org
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  *
20  * Initial developer(s): Nicolas Modrzyk.
21  * Contributor(s): Emmanuel Cecchet.
22  */
23
24 package org.continuent.sequoia.common.protocol;
25
26 import java.io.ByteArrayInputStream JavaDoc;
27 import java.io.OutputStream JavaDoc;
28 import java.io.Serializable JavaDoc;
29 import java.io.StringReader JavaDoc;
30 import java.io.Writer JavaDoc;
31 import java.sql.SQLException JavaDoc;
32
33 import org.continuent.sequoia.common.exceptions.NotImplementedException;
34
35 /**
36  * The representation (mapping) in the Java <sup><small>TM </small> </sup>
37  * programming language of an SQL <code>CLOB</code> value. An SQL
38  * <code>CLOB</code> is a built-in type that stores a Character Large Object
39  * as a column value in a row of a database table. By default drivers implement
40  * <code>Clob</code> using an SQL <code>locator(CLOB)</code>, which means
41  * that a <code>Clob</code> object contains a logical pointer to the SQL
42  * <code>CLOB</code> data rather than the data itself. A <code>Clob</code>
43  * object is valid for the duration of the transaction in which is was created.
44  * <p>
45  * Methods in the interfaces {@link java.sql.ResultSet},
46  * {@link java.sql.CallableStatement}, and {@link java.sql.PreparedStatement},
47  * such as <code>getClob</code> and <code>setClob</code> allow a programmer
48  * to access an SQL <code>CLOB</code> value. The <code>Clob</code> interface
49  * provides methods for getting the length of an SQL <code>CLOB</code>
50  * (Character Large Object) value, for materializing a <code>CLOB</code> value
51  * on the client, and for determining the position of a pattern of bytes within
52  * a <code>CLOB</code> value. In addition, this interface has methods for
53  * updating a <code>CLOB</code> value.
54  *
55  * @author <a HREF="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
56  * @author <a HREF="mailto:Emmanuel.Cecchet@emicnetworks.fr">Emmanuel Cecchet
57  * </a>
58  * @since JDK 1.2
59  */
60 public class StringClob implements java.sql.Clob JavaDoc, Serializable JavaDoc
61 {
62   private static final long serialVersionUID = 1832832422588968988L;
63
64   /** The data represented as a string of this <code>CLOB</code> */
65   private String JavaDoc stringData = null;
66
67   /**
68    * Creates a new <code>Clob</code> instance.
69    *
70    * @param data a <code>String</code> of character data
71    */
72   public StringClob(String JavaDoc data)
73   {
74     stringData = data;
75   }
76
77   /**
78    * Returns the size of the <code>CLOB</code> value designated by this
79    * <code>Clob</code> object
80    *
81    * @return length of the <code>CLOB</code> value that this <code>clob</code>
82    * represents
83    * @exception SQLException if there is an error accessing the length of the
84    * <code>CLOB</code>
85    * @since JDK 1.2
86    */
87   public long length() throws SQLException JavaDoc
88   {
89     return stringData.length();
90   }
91
92   /**
93    * Retrieves the <code>CLOB</code> value designated by this
94    * <code>Clob</code> instance as a stream.
95    *
96    * @return a stream containing the <code>CLOB</code> data
97    * @exception SQLException if there is an error accessing the
98    * <code>CLOB</code> value
99    * @since JDK 1.2
100    */
101   public java.io.InputStream JavaDoc getAsciiStream() throws SQLException JavaDoc
102   {
103     return new ByteArrayInputStream JavaDoc(stringData.getBytes());
104   }
105
106   /**
107    * Materializes the <code>CLOB</code> value designated by this <Code>object
108    * as a stream of Unicode character.
109    *
110    * @return A reader object with all the data in the <code>CLOB</code> value
111    * designated by this clob object as unicode characters.
112    * @exception SQLException if there is an error accessing the
113    * <code>CLOB</code> value
114    */
115   public java.io.Reader JavaDoc getCharacterStream() throws SQLException JavaDoc
116   {
117     return new StringReader JavaDoc(stringData);
118   }
119
120   /**
121    * @see java.sql.Clob#getSubString(long, int)
122    */
123   public String JavaDoc getSubString(long sqlPos, int wantedLength) throws SQLException JavaDoc
124   {
125     ByteArrayBlob.checkSQLRangeIsSupported(sqlPos, wantedLength);
126     // SQL counts from one, whereas real languages count from zero
127 int endIndex = Math.min(
128     // no further than what we have
129 stringData.length() - 1,
130         // no further than what is asked
131 (int) (sqlPos - 1) + wantedLength - 1);
132     return stringData.substring((int) sqlPos - 1, endIndex);
133   }
134
135   /**
136    * Retrieves the character position at which the specified string
137    * <code>searchstr</code> begins within the <code>CLOB</code> value that
138    * this <code>Clob</code> object represents. The search for
139    * <code>searchstr</code> begins at position <code>start</code>.
140    *
141    * @param searchstr the byte array for which to search
142    * @param start the position at which to begin searching; the first position
143    * is 1
144    * @return the position at which the pattern appears, else -1
145    * @exception SQLException if there is an error accessing the
146    * <code>CLOB</code>
147    * @since JDK 1.2
148    */
149   public long position(String JavaDoc searchstr, long start) throws SQLException JavaDoc
150   {
151     return stringData.indexOf(searchstr, (int) start);
152   }
153
154   /**
155    * Retrieves the character position at which the specified <code>Clob</code>
156    * object <code>searchstr</code> begins within the <code>CLOB</code> value
157    * that this <code>Clob</code> object represents. The search for
158    * <code>searchstr</code> begins at position <code>start</code>.
159    *
160    * @param searchstr the byte array for which to search
161    * @param start the position at which to begin searching; the first position
162    * is 1
163    * @return the position at which the pattern appears, else -1
164    * @exception SQLException if there is an error accessing the
165    * <code>CLOB</code>
166    * @since JDK 1.2
167    */
168   public long position(java.sql.Clob JavaDoc searchstr, long start) throws SQLException JavaDoc
169   {
170     return position(searchstr.getSubString(0, (int) searchstr.length()),
171         (int) start);
172   }
173
174   // -------------------------- JDBC 3.0 -----------------------------------
175
176   /**
177    * Retrieves a stream to be used to write Ascii characters to the CLOB value
178    * that this Clob object represents, starting at position pos.
179    *
180    * @param pos the position where to start the stream
181    * @return the ascii outputstream to this <code>clob</code> object
182    * @throws SQLException if there is an error accessing the <code>clob</code>
183    */
184   public OutputStream JavaDoc setAsciiStream(long pos) throws SQLException JavaDoc
185   {
186     throw new NotImplementedException("setAsciiStream");
187   }
188
189   /**
190    * Retrieves a stream to be used to write a stream of Unicode characters to
191    * the CLOB value that this Clob object represents, at position pos.
192    *
193    * @param pos the position where to start the writer
194    * @return the writer to this <code>clob</code> object
195    * @throws SQLException if there is an error accessing the <code>clob</code>
196    */
197   public Writer JavaDoc setCharacterStream(long pos) throws SQLException JavaDoc
198   {
199     throw new NotImplementedException("setCharacterStream");
200   }
201
202   /**
203    * Writes the given Java String to the CLOB value that this Clob object
204    * designates at the position pos.
205    *
206    * @param pos the position where to set the string
207    * @param str string to insert in the <code>clob</code>
208    * @return return value
209    * @throws SQLException if there is an error accessing the <code>clob</code>
210    */
211   public int setString(long pos, String JavaDoc str) throws SQLException JavaDoc
212   {
213     throw new NotImplementedException("setString");
214   }
215
216   /**
217    * Writes len characters of str, starting at character offset, to the CLOB
218    * value that this Clob represents.
219    *
220    * @param pos the position
221    * @param str the string
222    * @param offset the offset
223    * @param len the length
224    * @return return value
225    * @throws SQLException if there is an error accessing the <code>clob</code>
226    */
227   public int setString(long pos, String JavaDoc str, int offset, int len)
228       throws SQLException JavaDoc
229   {
230     throw new NotImplementedException("setString");
231   }
232
233   /**
234    * Truncates the CLOB value that this Clob designates to have a length of len
235    * characters.
236    *
237    * @param len the length
238    * @throws SQLException if there is an error accessing the <code>clob</code>
239    */
240   public void truncate(long len) throws SQLException JavaDoc
241   {
242     throw new NotImplementedException("truncate");
243   }
244 }
Popular Tags