/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.sql;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Reader;
import java.io.Writer;
/**
* A Java interface mapping for the SQL CLOB type.
* <p>
* An SQL {@code CLOB} type stores a large array of characters as the value in a
* column of a database.
* <p>
* The {@code java.sql.Clob} interface provides methods for setting and
* retrieving data in the {@code Clob}, for querying {@code Clob} data length,
* for searching for data within the {@code Clob}.
*/
public interface Clob {
/**
* Gets the value of this {@code Clob} object as an ASCII stream.
*
* @return an ASCII {@code InputStream} giving access to the
* {@code Clob} data.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public InputStream getAsciiStream() throws SQLException;
/**
* Gets the data of this {@code Clob} object in a {@code java.io.Reader}.
*
* @return a character stream Reader object giving access to the {@code
* Clob} data.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public Reader getCharacterStream() throws SQLException;
/**
* Gets a copy of a specified substring in this {@code Clob}.
*
* @param pos
* the index of the start of the substring in the {@code Clob}.
* @param length
* the length of the data to retrieve.
* @return A string containing the requested data.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public String getSubString(long pos, int length) throws SQLException;
/**
* Retrieves the number of characters in this {@code Clob} object.
*
* @return a long value with the number of character in this {@code Clob}.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public long length() throws SQLException;
/**
* Retrieves the character position at which a specified {@code Clob} object
* appears in this {@code Clob} object.
*
* @param searchstr
* the specified {@code Clob} to search for.
* @param start
* the position within this {@code Clob} to start the search
* @return a long value with the position at which the specified {@code
* Clob} occurs within this {@code Clob}.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public long position(Clob searchstr, long start) throws SQLException;
/**
* Retrieves the character position at which a specified substring appears
* in this {@code Clob} object.
*
* @param searchstr
* the string to search for.
* @param start
* the position at which to start the search within this {@code
* Clob}.
* @return a long value with the position at which the specified string
* occurs within this {@code Clob}.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public long position(String searchstr, long start) throws SQLException;
/**
* Retrieves a stream which can be used to write Ascii characters to this
* {@code Clob} object, starting at specified position.
*
* @param pos
* the position at which to start the writing.
* @return an OutputStream which can be used to write ASCII characters to
* this {@code Clob}.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public OutputStream setAsciiStream(long pos) throws SQLException;
/**
* Retrieves a stream which can be used to write a stream of unicode
* characters to this {@code Clob} object, at a specified position.
*
* @param pos
* the position at which to start the writing.
* @return a Writer which can be used to write unicode characters to this
* {@code Clob}.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public Writer setCharacterStream(long pos) throws SQLException;
/**
* Writes a given Java String to this {@code Clob} object at a specified
* position.
*
* @param pos
* the position at which to start the writing.
* @param str
* the string to write.
* @return the number of characters written.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public int setString(long pos, String str) throws SQLException;
/**
* Writes {@code len} characters of a string, starting at a specified
* character offset, to this {@code Clob}.
*
* @param pos
* the position at which to start the writing.
* @param str
* the String to write.
* @param offset
* the offset within {@code str} to start writing from.
* @param len
* the number of characters to write.
* @return the number of characters written.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public int setString(long pos, String str, int offset, int len)
throws SQLException;
/**
* Truncates this {@code Clob} after the specified number of characters.
*
* @param len
* the length in characters giving the place to
* truncate this {@code Clob}.
* @throws SQLException
* if an error occurs accessing the {@code Clob}.
*/
public void truncate(long len) throws SQLException;
/**
* Frees any resources held by this clob. After {@code free} is called, calling
* method other than {@code free} will throw {@code SQLException} (calling {@code free}
* repeatedly will do nothing).
*
* @throws SQLException
*/
public void free() throws SQLException;
/**
* Returns a {@link Reader} that reads {@code length} characters from this clob, starting
* at 1-based offset {code pos}.
*/
public Reader getCharacterStream(long pos, long length) throws SQLException;
}