History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/Blob.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/Blob.java+304−0
@@ -0,0 +1,304 @@
1+/*
2+ * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.sql;
27+
28+import java.io.InputStream;
29+
30+/**
31+ * The representation (mapping) in
32+ * the Java<sup><font size=-2>TM</font></sup> programming
33+ * language of an SQL
34+ * <code>BLOB</code> value. An SQL <code>BLOB</code> is a built-in type
35+ * that stores a Binary Large Object as a column value in a row of
36+ * a database table. By default drivers implement <code>Blob</code> using
37+ * an SQL <code>locator(BLOB)</code>, which means that a
38+ * <code>Blob</code> object contains a logical pointer to the
39+ * SQL <code>BLOB</code> data rather than the data itself.
40+ * A <code>Blob</code> object is valid for the duration of the
41+ * transaction in which is was created.
42+ *
43+ * <P>Methods in the interfaces {@link ResultSet},
44+ * {@link CallableStatement}, and {@link PreparedStatement}, such as
45+ * <code>getBlob</code> and <code>setBlob</code> allow a programmer to
46+ * access an SQL <code>BLOB</code> value.
47+ * The <code>Blob</code> interface provides methods for getting the
48+ * length of an SQL <code>BLOB</code> (Binary Large Object) value,
49+ * for materializing a <code>BLOB</code> value on the client, and for
50+ * determining the position of a pattern of bytes within a
51+ * <code>BLOB</code> value. In addition, this interface has methods for updating
52+ * a <code>BLOB</code> value.
53+ * <p>
54+ * All methods on the <code>Blob</code> interface must be fully implemented if the
55+ * JDBC driver supports the data type.
56+ *
57+ * @since 1.2
58+ */
59+
60+public interface Blob {
61+
62+ /**
63+ * Returns the number of bytes in the <code>BLOB</code> value
64+ * designated by this <code>Blob</code> object.
65+ * @return length of the <code>BLOB</code> in bytes
66+ * @exception SQLException if there is an error accessing the
67+ * length of the <code>BLOB</code>
68+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
69+ * this method
70+ * @since 1.2
71+ */
72+ long length() throws SQLException;
73+
74+ /**
75+ * Retrieves all or part of the <code>BLOB</code>
76+ * value that this <code>Blob</code> object represents, as an array of
77+ * bytes. This <code>byte</code> array contains up to <code>length</code>
78+ * consecutive bytes starting at position <code>pos</code>.
79+ *
80+ * @param pos the ordinal position of the first byte in the
81+ * <code>BLOB</code> value to be extracted; the first byte is at
82+ * position 1
83+ * @param length the number of consecutive bytes to be copied; the value
84+ * for length must be 0 or greater
85+ * @return a byte array containing up to <code>length</code>
86+ * consecutive bytes from the <code>BLOB</code> value designated
87+ * by this <code>Blob</code> object, starting with the
88+ * byte at position <code>pos</code>
89+ * @exception SQLException if there is an error accessing the
90+ * <code>BLOB</code> value; if pos is less than 1 or length is
91+ * less than 0
92+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
93+ * this method
94+ * @see #setBytes
95+ * @since 1.2
96+ */
97+ byte[] getBytes(long pos, int length) throws SQLException;
98+
99+ /**
100+ * Retrieves the <code>BLOB</code> value designated by this
101+ * <code>Blob</code> instance as a stream.
102+ *
103+ * @return a stream containing the <code>BLOB</code> data
104+ * @exception SQLException if there is an error accessing the
105+ * <code>BLOB</code> value
106+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
107+ * this method
108+ * @see #setBinaryStream
109+ * @since 1.2
110+ */
111+ java.io.InputStream getBinaryStream () throws SQLException;
112+
113+ /**
114+ * Retrieves the byte position at which the specified byte array
115+ * <code>pattern</code> begins within the <code>BLOB</code>
116+ * value that this <code>Blob</code> object represents. The
117+ * search for <code>pattern</code> begins at position
118+ * <code>start</code>.
119+ *
120+ * @param pattern the byte array for which to search
121+ * @param start the position at which to begin searching; the
122+ * first position is 1
123+ * @return the position at which the pattern appears, else -1
124+ * @exception SQLException if there is an error accessing the
125+ * <code>BLOB</code> or if start is less than 1
126+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
127+ * this method
128+ * @since 1.2
129+ */
130+ long position(byte pattern[], long start) throws SQLException;
131+
132+ /**
133+ * Retrieves the byte position in the <code>BLOB</code> value
134+ * designated by this <code>Blob</code> object at which
135+ * <code>pattern</code> begins. The search begins at position
136+ * <code>start</code>.
137+ *
138+ * @param pattern the <code>Blob</code> object designating
139+ * the <code>BLOB</code> value for which to search
140+ * @param start the position in the <code>BLOB</code> value
141+ * at which to begin searching; the first position is 1
142+ * @return the position at which the pattern begins, else -1
143+ * @exception SQLException if there is an error accessing the
144+ * <code>BLOB</code> value or if start is less than 1
145+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
146+ * this method
147+ * @since 1.2
148+ */
149+ long position(Blob pattern, long start) throws SQLException;
150+
151+ // -------------------------- JDBC 3.0 -----------------------------------
152+
153+ /**
154+ * Writes the given array of bytes to the <code>BLOB</code> value that
155+ * this <code>Blob</code> object represents, starting at position
156+ * <code>pos</code>, and returns the number of bytes written.
157+ * The array of bytes will overwrite the existing bytes
158+ * in the <code>Blob</code> object starting at the position
159+ * <code>pos</code>. If the end of the <code>Blob</code> value is reached
160+ * while writing the array of bytes, then the length of the <code>Blob</code>
161+ * value will be increased to accomodate the extra bytes.
162+ * <p>
163+ * <b>Note:</b> If the value specified for <code>pos</code>
164+ * is greater then the length+1 of the <code>BLOB</code> value then the
165+ * behavior is undefined. Some JDBC drivers may throw a
166+ * <code>SQLException</code> while other drivers may support this
167+ * operation.
168+ *
169+ * @param pos the position in the <code>BLOB</code> object at which
170+ * to start writing; the first position is 1
171+ * @param bytes the array of bytes to be written to the <code>BLOB</code>
172+ * value that this <code>Blob</code> object represents
173+ * @return the number of bytes written
174+ * @exception SQLException if there is an error accessing the
175+ * <code>BLOB</code> value or if pos is less than 1
176+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
177+ * this method
178+ * @see #getBytes
179+ * @since 1.4
180+ */
181+ int setBytes(long pos, byte[] bytes) throws SQLException;
182+
183+ /**
184+ * Writes all or part of the given <code>byte</code> array to the
185+ * <code>BLOB</code> value that this <code>Blob</code> object represents
186+ * and returns the number of bytes written.
187+ * Writing starts at position <code>pos</code> in the <code>BLOB</code>
188+ * value; <code>len</code> bytes from the given byte array are written.
189+ * The array of bytes will overwrite the existing bytes
190+ * in the <code>Blob</code> object starting at the position
191+ * <code>pos</code>. If the end of the <code>Blob</code> value is reached
192+ * while writing the array of bytes, then the length of the <code>Blob</code>
193+ * value will be increased to accomodate the extra bytes.
194+ * <p>
195+ * <b>Note:</b> If the value specified for <code>pos</code>
196+ * is greater then the length+1 of the <code>BLOB</code> value then the
197+ * behavior is undefined. Some JDBC drivers may throw a
198+ * <code>SQLException</code> while other drivers may support this
199+ * operation.
200+ *
201+ * @param pos the position in the <code>BLOB</code> object at which
202+ * to start writing; the first position is 1
203+ * @param bytes the array of bytes to be written to this <code>BLOB</code>
204+ * object
205+ * @param offset the offset into the array <code>bytes</code> at which
206+ * to start reading the bytes to be set
207+ * @param len the number of bytes to be written to the <code>BLOB</code>
208+ * value from the array of bytes <code>bytes</code>
209+ * @return the number of bytes written
210+ * @exception SQLException if there is an error accessing the
211+ * <code>BLOB</code> value or if pos is less than 1
212+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
213+ * this method
214+ * @see #getBytes
215+ * @since 1.4
216+ */
217+ int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException;
218+
219+ /**
220+ * Retrieves a stream that can be used to write to the <code>BLOB</code>
221+ * value that this <code>Blob</code> object represents. The stream begins
222+ * at position <code>pos</code>.
223+ * The bytes written to the stream will overwrite the existing bytes
224+ * in the <code>Blob</code> object starting at the position
225+ * <code>pos</code>. If the end of the <code>Blob</code> value is reached
226+ * while writing to the stream, then the length of the <code>Blob</code>
227+ * value will be increased to accomodate the extra bytes.
228+ * <p>
229+ * <b>Note:</b> If the value specified for <code>pos</code>
230+ * is greater then the length+1 of the <code>BLOB</code> value then the
231+ * behavior is undefined. Some JDBC drivers may throw a
232+ * <code>SQLException</code> while other drivers may support this
233+ * operation.
234+ *
235+ * @param pos the position in the <code>BLOB</code> value at which
236+ * to start writing; the first position is 1
237+ * @return a <code>java.io.OutputStream</code> object to which data can
238+ * be written
239+ * @exception SQLException if there is an error accessing the
240+ * <code>BLOB</code> value or if pos is less than 1
241+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
242+ * this method
243+ * @see #getBinaryStream
244+ * @since 1.4
245+ */
246+ java.io.OutputStream setBinaryStream(long pos) throws SQLException;
247+
248+ /**
249+ * Truncates the <code>BLOB</code> value that this <code>Blob</code>
250+ * object represents to be <code>len</code> bytes in length.
251+ * <p>
252+ * <b>Note:</b> If the value specified for <code>pos</code>
253+ * is greater then the length+1 of the <code>BLOB</code> value then the
254+ * behavior is undefined. Some JDBC drivers may throw a
255+ * <code>SQLException</code> while other drivers may support this
256+ * operation.
257+ *
258+ * @param len the length, in bytes, to which the <code>BLOB</code> value
259+ * that this <code>Blob</code> object represents should be truncated
260+ * @exception SQLException if there is an error accessing the
261+ * <code>BLOB</code> value or if len is less than 0
262+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
263+ * this method
264+ * @since 1.4
265+ */
266+ void truncate(long len) throws SQLException;
267+
268+ /**
269+ * This method frees the <code>Blob</code> object and releases the resources that
270+ * it holds. The object is invalid once the <code>free</code>
271+ * method is called.
272+ *<p>
273+ * After <code>free</code> has been called, any attempt to invoke a
274+ * method other than <code>free</code> will result in a <code>SQLException</code>
275+ * being thrown. If <code>free</code> is called multiple times, the subsequent
276+ * calls to <code>free</code> are treated as a no-op.
277+ *<p>
278+ *
279+ * @throws SQLException if an error occurs releasing
280+ * the Blob's resources
281+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
282+ * this method
283+ * @since 1.6
284+ */
285+ void free() throws SQLException;
286+
287+ /**
288+ * Returns an <code>InputStream</code> object that contains a partial <code>Blob</code> value,
289+ * starting with the byte specified by pos, which is length bytes in length.
290+ *
291+ * @param pos the offset to the first byte of the partial value to be retrieved.
292+ * The first byte in the <code>Blob</code> is at position 1
293+ * @param length the length in bytes of the partial value to be retrieved
294+ * @return <code>InputStream</code> through which the partial <code>Blob</code> value can be read.
295+ * @throws SQLException if pos is less than 1 or if pos is greater than the number of bytes
296+ * in the <code>Blob</code> or if pos + length is greater than the number of bytes
297+ * in the <code>Blob</code>
298+ *
299+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
300+ * this method
301+ * @since 1.6
302+ */
303+ InputStream getBinaryStream(long pos, long length) throws SQLException;
304+}