libcore/luni/src/main/java/java/sql/Clob.java

   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 }