001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: import java.io.InputStream;
021: import java.io.Reader;
022: import java.io.OutputStream;
023: import java.io.Writer;
024:
025: /**
026: * A Java interface mapping for the SQL CLOB type.
027: * <p>
028: * An SQL CLOB type stores a large array of characters as the value in a column
029: * of a database.
030: * <p>
031: * The java.sql.Clob interface provides methods for setting and retrieving data
032: * in the Clob, for querying Clob data length, for searching for data within the
033: * Clob.
034: */
035: public interface Clob {
036:
037: /**
038: * Gets the value of this Clob object as an ASCII stream.
039: *
040: * @return an ASCII InputStream giving access to the Clob data
041: * @throws SQLException
042: * if an error occurs accessing the Clob
043: */
044: public InputStream getAsciiStream() throws SQLException;
045:
046: /**
047: * Gets the value of this Clob object as a java.io.Reader.
048: *
049: * @return a character stream Reader object giving access to the Clob data
050: * @throws SQLException
051: * if an error occurs accessing the Clob
052: */
053: public Reader getCharacterStream() throws SQLException;
054:
055: /**
056: * Gets a copy of a specified substring in this Clob.
057: *
058: * @param pos
059: * the index of the start of the substring in the Clob
060: * @param length
061: * the length of the data to retrieve
062: * @return A String containing the requested data
063: * @throws SQLException
064: * if an error occurs accessing the Clob
065: */
066: public String getSubString(long pos, int length)
067: throws SQLException;
068:
069: /**
070: * Retrieves the number of characters in this Clob object.
071: *
072: * @return a long value with the number of character in this Clob.
073: * @throws SQLException
074: * if an error occurs accessing the Clob
075: */
076: public long length() throws SQLException;
077:
078: /**
079: * Retrieves the character position at which a specified Clob object appears
080: * in this Clob object.
081: *
082: * @param searchstr
083: * the specified Clob to search for
084: * @param start
085: * the position within this Clob to start the search
086: * @return a long value with the position at which the specified Clob occurs
087: * within this Clob.
088: * @throws SQLException
089: * if an error occurs accessing the Clob
090: */
091: public long position(Clob searchstr, long start)
092: throws SQLException;
093:
094: /**
095: * Retrieves the character position at which a specified substring appears
096: * in this Clob object.
097: *
098: * @param searchstr
099: * th String to search for
100: * @param start
101: * the position at which to start the search within this Clob.
102: * @return a long value with the position at which the specified String
103: * occurs within this Clob.
104: * @throws SQLException
105: * if an error occurs accessing the Clob
106: */
107: public long position(String searchstr, long start)
108: throws SQLException;
109:
110: /**
111: * Retrieves a stream which can be used to write Ascii characters to this
112: * Clob object, starting at specified position.
113: *
114: * @param pos
115: * the position at which to start the writing
116: * @return an OutputStream which can be used to write ASCII characters to
117: * this Clob.
118: * @throws SQLException
119: * if an error occurs accessing the Clob
120: */
121: public OutputStream setAsciiStream(long pos) throws SQLException;
122:
123: /**
124: * Retrieves a stream which can be used to write a stream of Unicode
125: * characters to this Clob object, at a specified position.
126: *
127: * @param pos
128: * the position at which to start the writing
129: * @return a Writer which can be used to write Unicode characters to this
130: * Clob.
131: * @throws SQLException
132: * if an error occurs accessing the Clob
133: */
134: public Writer setCharacterStream(long pos) throws SQLException;
135:
136: /**
137: * Writes a given Java String to this Clob object at a specified position.
138: *
139: * @param pos
140: * the position at which to start the writing
141: * @param str
142: * the String to write
143: * @return the number of characters written
144: * @throws SQLException
145: * if an error occurs accessing the Clob
146: */
147: public int setString(long pos, String str) throws SQLException;
148:
149: /**
150: * Writes len characters of String, starting at a specified character
151: * offset, to this Clob.
152: *
153: * @param pos
154: * the position at which to start the writing
155: * @param str
156: * the String to write
157: * @param offset
158: * the offset within str to start writing from
159: * @param len
160: * the number of characters to write
161: * @return the number of characters written
162: * @throws SQLException
163: * if an error occurs accessing the Clob
164: */
165: public int setString(long pos, String str, int offset, int len)
166: throws SQLException;
167:
168: /**
169: * Truncates this Clob to have a specified length of characters.
170: *
171: * @param len
172: * the length in characters to truncate this Clob
173: * @throws SQLException
174: * if an error occurs accessing the Clob
175: */
176: public void truncate(long len) throws SQLException;
177: }
|