1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20import java.io.InputStream;
21import java.io.OutputStream;
22import java.io.Reader;
23import java.io.Writer;
24
25/**
26 * A Java interface mapping for the SQL CLOB type.
27 * <p>
28 * An SQL {@code CLOB} type stores a large array of characters as the value in a
29 * column of a database.
30 * <p>
31 * The {@code java.sql.Clob} interface provides methods for setting and
32 * retrieving data in the {@code Clob}, for querying {@code Clob} data length,
33 * for searching for data within the {@code Clob}.
34 */
35public interface Clob {
36
37    /**
38     * Gets the value of this {@code Clob} object as an ASCII stream.
39     *
40     * @return an ASCII {@code InputStream} giving access to the
41     *            {@code Clob} data.
42     * @throws SQLException
43     *             if an error occurs accessing the {@code Clob}.
44     */
45    public InputStream getAsciiStream() throws SQLException;
46
47    /**
48     * Gets the data of this {@code Clob} object in a {@code java.io.Reader}.
49     *
50     * @return a character stream Reader object giving access to the {@code
51     *         Clob} data.
52     * @throws SQLException
53     *             if an error occurs accessing the {@code Clob}.
54     */
55    public Reader getCharacterStream() throws SQLException;
56
57    /**
58     * Gets a copy of a specified substring in this {@code Clob}.
59     *
60     * @param pos
61     *            the index of the start of the substring in the {@code Clob}.
62     * @param length
63     *            the length of the data to retrieve.
64     * @return A string containing the requested data.
65     * @throws SQLException
66     *             if an error occurs accessing the {@code Clob}.
67     */
68    public String getSubString(long pos, int length) throws SQLException;
69
70    /**
71     * Retrieves the number of characters in this {@code Clob} object.
72     *
73     * @return a long value with the number of character in this {@code Clob}.
74     * @throws SQLException
75     *             if an error occurs accessing the {@code Clob}.
76     */
77    public long length() throws SQLException;
78
79    /**
80     * Retrieves the character position at which a specified {@code Clob} object
81     * appears in this {@code Clob} object.
82     *
83     * @param searchstr
84     *            the specified {@code Clob} to search for.
85     * @param start
86     *            the position within this {@code Clob} to start the search
87     * @return a long value with the position at which the specified {@code
88     *         Clob} occurs within this {@code Clob}.
89     * @throws SQLException
90     *             if an error occurs accessing the {@code Clob}.
91     */
92    public long position(Clob searchstr, long start) throws SQLException;
93
94    /**
95     * Retrieves the character position at which a specified substring appears
96     * in this {@code Clob} object.
97     *
98     * @param searchstr
99     *            the string to search for.
100     * @param start
101     *            the position at which to start the search within this {@code
102     *            Clob}.
103     * @return a long value with the position at which the specified string
104     *         occurs within this {@code Clob}.
105     * @throws SQLException
106     *             if an error occurs accessing the {@code Clob}.
107     */
108    public long position(String searchstr, long start) throws SQLException;
109
110    /**
111     * Retrieves a stream which can be used to write Ascii characters to this
112     * {@code 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 {@code Clob}.
118     * @throws SQLException
119     *             if an error occurs accessing the {@code 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 {@code 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     *         {@code Clob}.
131     * @throws SQLException
132     *             if an error occurs accessing the {@code Clob}.
133     */
134    public Writer setCharacterStream(long pos) throws SQLException;
135
136    /**
137     * Writes a given Java String to this {@code Clob} object at a specified
138     * position.
139     *
140     * @param pos
141     *            the position at which to start the writing.
142     * @param str
143     *            the string to write.
144     * @return the number of characters written.
145     * @throws SQLException
146     *             if an error occurs accessing the {@code Clob}.
147     */
148    public int setString(long pos, String str) throws SQLException;
149
150    /**
151     * Writes {@code len} characters of a string, starting at a specified
152     * character offset, to this {@code Clob}.
153     *
154     * @param pos
155     *            the position at which to start the writing.
156     * @param str
157     *            the String to write.
158     * @param offset
159     *            the offset within {@code str} to start writing from.
160     * @param len
161     *            the number of characters to write.
162     * @return the number of characters written.
163     * @throws SQLException
164     *             if an error occurs accessing the {@code Clob}.
165     */
166    public int setString(long pos, String str, int offset, int len)
167            throws SQLException;
168
169    /**
170     * Truncates this {@code Clob} after the specified number of characters.
171     *
172     * @param len
173     *            the length in characters giving the place to
174     *            truncate this {@code Clob}.
175     * @throws SQLException
176     *             if an error occurs accessing the {@code Clob}.
177     */
178    public void truncate(long len) throws SQLException;
179
180    /**
181     * Frees any resources held by this clob. After {@code free} is called, calling
182     * method other than {@code free} will throw {@code SQLException} (calling {@code free}
183     * repeatedly will do nothing).
184     *
185     * @throws SQLException
186     */
187    public void free() throws SQLException;
188
189    /**
190     * Returns a {@link Reader} that reads {@code length} characters from this clob, starting
191     * at 1-based offset {code pos}.
192     */
193    public Reader getCharacterStream(long pos, long length) throws SQLException;
194}
195