1f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes/* 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Licensed to the Apache Software Foundation (ASF) under one or more 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contributor license agreements. See the NOTICE file distributed with 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this work for additional information regarding copyright ownership. 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The ASF licenses this file to You under the Apache License, Version 2.0 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (the "License"); you may not use this file except in compliance with 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the License. You may obtain a copy of the License at 8f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 10f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Unless required by applicable law or agreed to in writing, software 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See the License for the specific language governing permissions and 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitations under the License. 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.sql; 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.InputStream; 217365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport java.io.OutputStream; 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 23adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 24adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * A Java interface representing the SQL {@code BLOB} type. 25adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p> 26adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An SQL {@code BLOB} type stores a large array of binary data (bytes) as the 27adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * value in a column of a database. 28142d526f8bf90fb9bb63c637beb5299f39791f55Jesse Wilson * <p> 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The {@code java.sql.Blob} interface provides methods for setting and 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * retrieving data in the {@code Blob}, for querying {@code Blob} data length, 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and for searching for data within the {@code Blob}. 32adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 33adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface Blob { 34adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 35adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Retrieves this {@code Blob} object as a binary stream. 37f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a binary {@code InputStream} giving access to the {@code Blob} 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * data. 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public InputStream getBinaryStream() throws SQLException; 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 45adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 46f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * Retrieves {@code length} bytes from this {@code Blob}, starting at 1-based 47f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * offset {@code pos}, and returns them as a binary stream. 48f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * 49f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * @return a binary {@code InputStream} giving access to the {@code Blob} 50f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * data. 51f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * @throws SQLException 52f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * if an error occurs accessing the {@code Blob}. 53f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes */ 54f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes public InputStream getBinaryStream(long pos, long length) throws SQLException; 55f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes 56f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes /** 57adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a portion of the value of this {@code Blob} as an array of bytes. 58f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 59adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 60adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position of the first byte in the {@code Blob} to get, 61adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * where the first byte in the {@code Blob} has position 1. 62adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param length 63adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the number of bytes to get. 64adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a byte array containing the data from the {@code Blob}, starting 65adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * at {@code pos} and is up to {@code length} bytes long. 66adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 67adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 68adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public byte[] getBytes(long pos, int length) throws SQLException; 70adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 71adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 72adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the number of bytes in this {@code Blob} object. 73f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 74adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a {@code long} value with the length of the {@code Blob} in 75adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * bytes. 76adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 78adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public long length() throws SQLException; 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Search for the position in this {@code Blob} at which a specified pattern 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * begins, starting at a specified position within the {@code Blob}. 84f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pattern 86adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a {@code Blob} containing the pattern of data to search for in 87adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this {@code Blob}. 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param start 89adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} to start the search, 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * where the first position in the {@code Blob} is {@code 1}. 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a {@code long} value with the position at which the pattern 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * begins. Returns {@code -1} if the pattern is not found in this 93adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code Blob}. 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public long position(Blob pattern, long start) throws SQLException; 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 100adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Search for the position in this {@code Blob} at which the specified 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * pattern begins, starting at a specified position within the {@code Blob}. 102f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pattern 104adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a byte array containing the pattern of data to search for in 105adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this {@code Blob}. 106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param start 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} to start the search, 108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * where the first position in the {@code Blob} is {@code 1}. 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a {@code long} value with the position at which the pattern 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * begins. Returns {@code -1} if the pattern is not found in this 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code Blob}. 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 114adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 115adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public long position(byte[] pattern, long start) throws SQLException; 116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a stream that can be used to write binary data to this {@code Blob}. 119f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 120adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 121adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} at which to start 122adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * writing, where the first position in the {@code Blob} is 123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code 1}. 124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a binary {@code InputStream} which can be used to write data into 125adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the {@code Blob} starting at the specified position. 126adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 127adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 128adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 129adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public OutputStream setBinaryStream(long pos) throws SQLException; 130adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 131adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 132adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Writes a specified array of bytes to this {@code Blob} object, starting 133adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * at a specified position. Returns the number of bytes written. 134f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 135adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 136adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} at which to start 137adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * writing, where the first position in the {@code Blob} is 138adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code 1}. 139adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param theBytes 140adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an array of bytes to write into the {@code Blob}. 141adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return an integer containing the number of bytes written to the {@code 142adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Blob}. 143adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 144adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 145adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 146adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public int setBytes(long pos, byte[] theBytes) throws SQLException; 147adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 148adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 149adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Writes a portion of a specified byte array to this {@code Blob}. Returns 150adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the number of bytes written. 151f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 152adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 153adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} at which to start 154adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * writing, where the first position in the {@code Blob} is 155adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code 1}. 156adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param theBytes 157adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an array of bytes to write into the {@code Blob}. 158adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param offset 159adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the offset into the byte array from which to start writing 160adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * data - the first byte in the array has offset {@code 0}. 161adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param len 162adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the length of data to write in number of bytes. 163adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return an integer containing the number of bytes written to the {@code 164adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Blob}. 165adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 166adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 167adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 168adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public int setBytes(long pos, byte[] theBytes, int offset, int len) 169adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws SQLException; 170adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 171adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 172adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Truncate the value of this {@code Blob} object to a specified length in 173adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * bytes. 174f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 175adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param len 176adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the length of data in bytes after which this {@code Blob} 177adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is to be truncated. 178adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 179adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 180adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 181adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public void truncate(long len) throws SQLException; 18236b3cdfbcd219d0308753d919638262c16fd34daJeremy Sharpe 18336b3cdfbcd219d0308753d919638262c16fd34daJeremy Sharpe /** 184f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * Frees any resources held by this blob. After {@code free} is called, calling 185f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * method other than {@code free} will throw {@code SQLException} (calling {@code free} 186f3cc41ede7af1dd683e1a55eabc8f36963aec8abElliott Hughes * repeatedly will do nothing). 18736b3cdfbcd219d0308753d919638262c16fd34daJeremy Sharpe * 18836b3cdfbcd219d0308753d919638262c16fd34daJeremy Sharpe * @throws SQLException 18936b3cdfbcd219d0308753d919638262c16fd34daJeremy Sharpe */ 19036b3cdfbcd219d0308753d919638262c16fd34daJeremy Sharpe public void free() throws SQLException; 191adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 192