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 18 package java.sql; 19 20 import java.io.InputStream; 21 import 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 */ 33 public 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
