001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: import java.io.OutputStream;
021: import java.io.InputStream;
022:
023: /**
024: * A Java interface mapping for the SQL BLOB type.
025: * <p>
026: * An SQL CLOB type stores a large array of bytes (binary data) as the value in
027: * a column of a database.
028: * <p>
029: * The java.sql.Blob interface provides methods for setting and retrieving data
030: * in the Blob, for querying Clob data length, for searching for data within the
031: * Blob.
032: */
033: public interface Blob {
034:
035: /**
036: * Retrieves this Blob object as a binary stream.
037: *
038: * @return a binary InputStream giving access to the Blob data
039: * @throws SQLException
040: * if an error occurs accessing the Blob
041: */
042: public InputStream getBinaryStream() throws SQLException;
043:
044: /**
045: * Gets a portion of the value of this Blob as an array of bytes.
046: *
047: * @param pos
048: * the position of the first byte in the Blob to get, where the
049: * first byte in the Blob has position = 1
050: * @param length
051: * the number of bytes to get
052: * @return a byte array containing the data from the Blob, starting at pos
053: * and of length up to <code>length</code> bytes long
054: * @throws SQLException
055: * if an error occurs accessing the Blob
056: */
057: public byte[] getBytes(long pos, int length) throws SQLException;
058:
059: /**
060: * Gets the number of bytes in this Blob object.
061: *
062: * @return an long value with the length of the Blob in bytes
063: * @throws SQLException
064: * if an error occurs accessing the Blob
065: */
066: public long length() throws SQLException;
067:
068: /**
069: * Search for the position in this Blob at which a specified pattern begins,
070: * starting at a specified position within the Blob.
071: *
072: * @param pattern
073: * a Blob containing the pattern of data to search for in this
074: * Blob
075: * @param start
076: * the position within this Blob to start the search, where the
077: * first position in the Blob is 1
078: * @return a long value with the position at which the pattern begins. -1 if
079: * the pattern is not found in this Blob.
080: * @throws SQLException
081: * if an error occurs accessing the Blob
082: */
083: public long position(Blob pattern, long start) throws SQLException;
084:
085: /**
086: * Search for the position in this Blob at which the specified pattern
087: * begins, starting at a specified position within the Blob.
088: *
089: * @param pattern
090: * a byte array containing the pattern of data to search for in
091: * this Blob
092: * @param start
093: * the position within this Blob to start the search, where the
094: * first position in the Blob is 1
095: * @return a long value with the position at which the pattern begins. -1 if
096: * the pattern is not found in this Blob.
097: * @throws SQLException
098: * if an error occurs accessing the Blob
099: */
100: public long position(byte[] pattern, long start)
101: throws SQLException;
102:
103: /**
104: * Gets a stream that can be used to write binary data to this Blob.
105: *
106: * @param pos
107: * the position within this Blob at which to start writing, where
108: * the first position in the Blob is 1
109: * @return a binary InputStream which can be used to write data into the
110: * Blob starting at the specified position.
111: * @throws SQLException
112: * if an error occurs accessing the Blob
113: */
114: public OutputStream setBinaryStream(long pos) throws SQLException;
115:
116: /**
117: * Writes a specified array of bytes to this Blob. object, starting at a
118: * specified position. Returns the number of bytes written.
119: *
120: * @param pos
121: * the position within this Blob at which to start writing, where
122: * the first position in the Blob is 1
123: * @param theBytes
124: * an array of bytes to write into the Blob
125: * @return an integer containing the number of bytes written to the Blob
126: * @throws SQLException
127: * if an error occurs accessing the Blob
128: */
129: public int setBytes(long pos, byte[] theBytes) throws SQLException;
130:
131: /**
132: * Writes a portion of a specified byte array to this Blob. Returns the
133: * number of bytes written.
134: *
135: * @param pos
136: * the position within this Blob at which to start writing, where
137: * the first position in the Blob is 1
138: * @param theBytes
139: * an array of bytes to write into the Blob
140: * @param offset
141: * the offset into the byte array from which to start writing
142: * data - the first byte in the array has offset 0.
143: * @param len
144: * the length of data to write, as the number of bytes
145: * @return an integer containing the number of bytes written to the Blob
146: * @throws SQLException
147: * if an error occurs accessing the Blob
148: */
149: public int setBytes(long pos, byte[] theBytes, int offset, int len)
150: throws SQLException;
151:
152: /**
153: * Truncate the value of this Blob object to a specified length in bytes.
154: *
155: * @param len
156: * the length of data in bytes to truncate the value of this Blob
157: * @throws SQLException
158: * if an error occurs accessing the Blob
159: */
160: public void truncate(long len) throws SQLException;
161: }
|