/*
* 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;
/**
* A Java interface representing the SQL {@code BLOB} type.
* <p>
* An SQL {@code BLOB} type stores a large array of binary data (bytes) as the
* value in a column of a database.
* <p>
* The {@code java.sql.Blob} interface provides methods for setting and
* retrieving data in the {@code Blob}, for querying {@code Blob} data length,
* and for searching for data within the {@code Blob}.
*/
public interface Blob {
/**
* Retrieves this {@code Blob} object as a binary stream.
*
* @return a binary {@code InputStream} giving access to the {@code Blob}
* data.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public InputStream getBinaryStream() throws SQLException;
/**
* Retrieves {@code length} bytes from this {@code Blob}, starting at 1-based
* offset {@code pos}, and returns them as a binary stream.
*
* @return a binary {@code InputStream} giving access to the {@code Blob}
* data.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public InputStream getBinaryStream(long pos, long length) throws SQLException;
/**
* Gets a portion of the value of this {@code Blob} as an array of bytes.
*
* @param pos
* the position of the first byte in the {@code Blob} to get,
* where the first byte in the {@code Blob} has position 1.
* @param length
* the number of bytes to get.
* @return a byte array containing the data from the {@code Blob}, starting
* at {@code pos} and is up to {@code length} bytes long.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public byte[] getBytes(long pos, int length) throws SQLException;
/**
* Gets the number of bytes in this {@code Blob} object.
*
* @return a {@code long} value with the length of the {@code Blob} in
* bytes.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public long length() throws SQLException;
/**
* Search for the position in this {@code Blob} at which a specified pattern
* begins, starting at a specified position within the {@code Blob}.
*
* @param pattern
* a {@code Blob} containing the pattern of data to search for in
* this {@code Blob}.
* @param start
* the position within this {@code Blob} to start the search,
* where the first position in the {@code Blob} is {@code 1}.
* @return a {@code long} value with the position at which the pattern
* begins. Returns {@code -1} if the pattern is not found in this
* {@code Blob}.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public long position(Blob pattern, long start) throws SQLException;
/**
* Search for the position in this {@code Blob} at which the specified
* pattern begins, starting at a specified position within the {@code Blob}.
*
* @param pattern
* a byte array containing the pattern of data to search for in
* this {@code Blob}.
* @param start
* the position within this {@code Blob} to start the search,
* where the first position in the {@code Blob} is {@code 1}.
* @return a {@code long} value with the position at which the pattern
* begins. Returns {@code -1} if the pattern is not found in this
* {@code Blob}.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public long position(byte[] pattern, long start) throws SQLException;
/**
* Gets a stream that can be used to write binary data to this {@code Blob}.
*
* @param pos
* the position within this {@code Blob} at which to start
* writing, where the first position in the {@code Blob} is
* {@code 1}.
* @return a binary {@code InputStream} which can be used to write data into
* the {@code Blob} starting at the specified position.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public OutputStream setBinaryStream(long pos) throws SQLException;
/**
* Writes a specified array of bytes to this {@code Blob} object, starting
* at a specified position. Returns the number of bytes written.
*
* @param pos
* the position within this {@code Blob} at which to start
* writing, where the first position in the {@code Blob} is
* {@code 1}.
* @param theBytes
* an array of bytes to write into the {@code Blob}.
* @return an integer containing the number of bytes written to the {@code
* Blob}.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public int setBytes(long pos, byte[] theBytes) throws SQLException;
/**
* Writes a portion of a specified byte array to this {@code Blob}. Returns
* the number of bytes written.
*
* @param pos
* the position within this {@code Blob} at which to start
* writing, where the first position in the {@code Blob} is
* {@code 1}.
* @param theBytes
* an array of bytes to write into the {@code Blob}.
* @param offset
* the offset into the byte array from which to start writing
* data - the first byte in the array has offset {@code 0}.
* @param len
* the length of data to write in number of bytes.
* @return an integer containing the number of bytes written to the {@code
* Blob}.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public int setBytes(long pos, byte[] theBytes, int offset, int len)
throws SQLException;
/**
* Truncate the value of this {@code Blob} object to a specified length in
* bytes.
*
* @param len
* the length of data in bytes after which this {@code Blob}
* is to be truncated.
* @throws SQLException
* if an error occurs accessing the {@code Blob}.
*/
public void truncate(long len) throws SQLException;
/**
* Frees any resources held by this blob. 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;
}