/*
 * 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;
}