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 18 package java.sql; 19 20 import java.io.InputStream; 21 import java.io.OutputStream; 22 import java.io.Reader; 23 import 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 */ 35 public 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
