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
18package java.sql;
19
20import java.io.InputStream;
21import java.io.OutputStream;
22
23/**
24 * A Java interface representing the SQL {@code BLOB} type.
25 * <p>
26 * An SQL {@code BLOB} type stores a large array of binary data (bytes) as the
27 * value in a column of a database.
28 * <p>
29 * The {@code java.sql.Blob} interface provides methods for setting and
30 * retrieving data in the {@code Blob}, for querying {@code Blob} data length,
31 * and for searching for data within the {@code Blob}.
32 */
33public interface Blob {
34
35    /**
36     * Retrieves this {@code Blob} object as a binary stream.
37     *
38     * @return a binary {@code InputStream} giving access to the {@code Blob}
39     *         data.
40     * @throws SQLException
41     *             if an error occurs accessing the {@code Blob}.
42     */
43    public InputStream getBinaryStream() throws SQLException;
44
45    /**
46     * Retrieves {@code length} bytes from this {@code Blob}, starting at 1-based
47     * offset {@code pos}, and returns them as a binary stream.
48     *
49     * @return a binary {@code InputStream} giving access to the {@code Blob}
50     *         data.
51     * @throws SQLException
52     *             if an error occurs accessing the {@code Blob}.
53     */
54    public InputStream getBinaryStream(long pos, long length) throws SQLException;
55
56    /**
57     * Gets a portion of the value of this {@code Blob} as an array of bytes.
58     *
59     * @param pos
60     *            the position of the first byte in the {@code Blob} to get,
61     *            where the first byte in the {@code Blob} has position 1.
62     * @param length
63     *            the number of bytes to get.
64     * @return a byte array containing the data from the {@code Blob}, starting
65     *         at {@code pos} and is up to {@code length} bytes long.
66     * @throws SQLException
67     *             if an error occurs accessing the {@code Blob}.
68     */
69    public byte[] getBytes(long pos, int length) throws SQLException;
70
71    /**
72     * Gets the number of bytes in this {@code Blob} object.
73     *
74     * @return a {@code long} value with the length of the {@code Blob} in
75     *         bytes.
76     * @throws SQLException
77     *             if an error occurs accessing the {@code Blob}.
78     */
79    public long length() throws SQLException;
80
81    /**
82     * Search for the position in this {@code Blob} at which a specified pattern
83     * begins, starting at a specified position within the {@code Blob}.
84     *
85     * @param pattern
86     *            a {@code Blob} containing the pattern of data to search for in
87     *            this {@code Blob}.
88     * @param start
89     *            the position within this {@code Blob} to start the search,
90     *            where the first position in the {@code Blob} is {@code 1}.
91     * @return a {@code long} value with the position at which the pattern
92     *         begins. Returns {@code -1} if the pattern is not found in this
93     *         {@code Blob}.
94     * @throws SQLException
95     *             if an error occurs accessing the {@code Blob}.
96     */
97    public long position(Blob pattern, long start) throws SQLException;
98
99    /**
100     * Search for the position in this {@code Blob} at which the specified
101     * pattern begins, starting at a specified position within the {@code Blob}.
102     *
103     * @param pattern
104     *            a byte array containing the pattern of data to search for in
105     *            this {@code Blob}.
106     * @param start
107     *            the position within this {@code Blob} to start the search,
108     *            where the first position in the {@code Blob} is {@code 1}.
109     * @return a {@code long} value with the position at which the pattern
110     *         begins. Returns {@code -1} if the pattern is not found in this
111     *         {@code Blob}.
112     * @throws SQLException
113     *             if an error occurs accessing the {@code Blob}.
114     */
115    public long position(byte[] pattern, long start) throws SQLException;
116
117    /**
118     * Gets a stream that can be used to write binary data to this {@code Blob}.
119     *
120     * @param pos
121     *            the position within this {@code Blob} at which to start
122     *            writing, where the first position in the {@code Blob} is
123     *            {@code 1}.
124     * @return a binary {@code InputStream} which can be used to write data into
125     *         the {@code Blob} starting at the specified position.
126     * @throws SQLException
127     *             if an error occurs accessing the {@code Blob}.
128     */
129    public OutputStream setBinaryStream(long pos) throws SQLException;
130
131    /**
132     * Writes a specified array of bytes to this {@code Blob} object, starting
133     * at a specified position. Returns the number of bytes written.
134     *
135     * @param pos
136     *            the position within this {@code Blob} at which to start
137     *            writing, where the first position in the {@code Blob} is
138     *            {@code 1}.
139     * @param theBytes
140     *            an array of bytes to write into the {@code Blob}.
141     * @return an integer containing the number of bytes written to the {@code
142     *         Blob}.
143     * @throws SQLException
144     *             if an error occurs accessing the {@code Blob}.
145     */
146    public int setBytes(long pos, byte[] theBytes) throws SQLException;
147
148    /**
149     * Writes a portion of a specified byte array to this {@code Blob}. Returns
150     * the number of bytes written.
151     *
152     * @param pos
153     *            the position within this {@code Blob} at which to start
154     *            writing, where the first position in the {@code Blob} is
155     *            {@code 1}.
156     * @param theBytes
157     *            an array of bytes to write into the {@code Blob}.
158     * @param offset
159     *            the offset into the byte array from which to start writing
160     *            data - the first byte in the array has offset {@code 0}.
161     * @param len
162     *            the length of data to write in number of bytes.
163     * @return an integer containing the number of bytes written to the {@code
164     *         Blob}.
165     * @throws SQLException
166     *             if an error occurs accessing the {@code Blob}.
167     */
168    public int setBytes(long pos, byte[] theBytes, int offset, int len)
169            throws SQLException;
170
171    /**
172     * Truncate the value of this {@code Blob} object to a specified length in
173     * bytes.
174     *
175     * @param len
176     *            the length of data in bytes after which this {@code Blob}
177     *            is to be truncated.
178     * @throws SQLException
179     *             if an error occurs accessing the {@code Blob}.
180     */
181    public void truncate(long len) throws SQLException;
182
183    /**
184     * Frees any resources held by this blob. After {@code free} is called, calling
185     * method other than {@code free} will throw {@code SQLException} (calling {@code free}
186     * repeatedly will do nothing).
187     *
188     * @throws SQLException
189     */
190    public void free() throws SQLException;
191}
192