Blob.java revision adc854b798c1cfe3bfd4c27d68d5cee38ca617da
1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* 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 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 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.OutputStream; 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.InputStream; 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. 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </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 Project * @since Android 1.0 34adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 35adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface Blob { 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Retrieves this {@code Blob} object as a binary stream. 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a binary {@code InputStream} giving access to the {@code Blob} 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * data. 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 45adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 46adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public InputStream getBinaryStream() throws SQLException; 47adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 48adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 49adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a portion of the value of this {@code Blob} as an array of bytes. 50adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 51adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 52adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position of the first byte in the {@code Blob} to get, 53adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * where the first byte in the {@code Blob} has position 1. 54adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param length 55adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the number of bytes to get. 56adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a byte array containing the data from the {@code Blob}, starting 57adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * at {@code pos} and is up to {@code length} bytes long. 58adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 59adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 60adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 61adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 62adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public byte[] getBytes(long pos, int length) throws SQLException; 63adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 64adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 65adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the number of bytes in this {@code Blob} object. 66adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 67adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a {@code long} value with the length of the {@code Blob} in 68adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * bytes. 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 70adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 71adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 72adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 73adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public long length() throws SQLException; 74adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 75adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 76adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Search for the position in this {@code Blob} at which a specified pattern 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * begins, starting at a specified position within the {@code Blob}. 78adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pattern 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a {@code Blob} containing the pattern of data to search for in 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this {@code Blob}. 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param start 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} to start the search, 84adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * where the first position in the {@code Blob} is {@code 1}. 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a {@code long} value with the position at which the pattern 86adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * begins. Returns {@code -1} if the pattern is not found in this 87adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code Blob}. 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 89adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public long position(Blob pattern, long start) throws SQLException; 93adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Search for the position in this {@code Blob} at which the specified 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * pattern begins, starting at a specified position within the {@code Blob}. 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pattern 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a byte array containing the pattern of data to search for in 100adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this {@code Blob}. 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param start 102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} to start the search, 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * where the first position in the {@code Blob} is {@code 1}. 104adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a {@code long} value with the position at which the pattern 105adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * begins. Returns {@code -1} if the pattern is not found in this 106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code Blob}. 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public long position(byte[] pattern, long start) throws SQLException; 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 114adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a stream that can be used to write binary data to this {@code Blob}. 115adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} at which to start 118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * writing, where the first position in the {@code Blob} is 119adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code 1}. 120adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a binary {@code InputStream} which can be used to write data into 121adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the {@code Blob} starting at the specified position. 122adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 125adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 126adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public OutputStream setBinaryStream(long pos) throws SQLException; 127adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 128adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 129adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Writes a specified array of bytes to this {@code Blob} object, starting 130adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * at a specified position. Returns the number of bytes written. 131adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 132adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 133adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} at which to start 134adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * writing, where the first position in the {@code Blob} is 135adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code 1}. 136adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param theBytes 137adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an array of bytes to write into the {@code Blob}. 138adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return an integer containing the number of bytes written to the {@code 139adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Blob}. 140adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 141adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 142adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 143adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 144adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public int setBytes(long pos, byte[] theBytes) throws SQLException; 145adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 146adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 147adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Writes a portion of a specified byte array to this {@code Blob}. Returns 148adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the number of bytes written. 149adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 150adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param pos 151adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position within this {@code Blob} at which to start 152adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * writing, where the first position in the {@code Blob} is 153adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@code 1}. 154adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param theBytes 155adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an array of bytes to write into the {@code Blob}. 156adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param offset 157adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the offset into the byte array from which to start writing 158adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * data - the first byte in the array has offset {@code 0}. 159adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param len 160adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the length of data to write in number of bytes. 161adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return an integer containing the number of bytes written to the {@code 162adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Blob}. 163adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 164adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 165adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 166adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 167adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public int setBytes(long pos, byte[] theBytes, int offset, int len) 168adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws SQLException; 169adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 170adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 171adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Truncate the value of this {@code Blob} object to a specified length in 172adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * bytes. 173adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 174adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param len 175adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the length of data in bytes after which this {@code Blob} 176adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is to be truncated. 177adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws SQLException 178adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if an error occurs accessing the {@code Blob}. 179adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since Android 1.0 180adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 181adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public void truncate(long len) throws SQLException; 182adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 183