00001 /** 00002 * C-JDBC: Clustered JDBC. 00003 * Copyright (C) 2002-2004 French National Institute For Research In Computer 00004 * Science And Control (INRIA). 00005 * Contact: c-jdbc@objectweb.org 00006 * 00007 * This library is free software; you can redistribute it and/or modify it 00008 * under the terms of the GNU Lesser General Public License as published by the 00009 * Free Software Foundation; either version 2.1 of the License, or any later 00010 * version. 00011 * 00012 * This library is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00014 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 00015 * for more details. 00016 * 00017 * You should have received a copy of the GNU Lesser General Public License 00018 * along with this library; if not, write to the Free Software Foundation, 00019 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 00020 * 00021 * Initial developer(s): Emmanuel Cecchet. 00022 * Contributor(s): Nicolas Modrzyk. 00023 */ 00024 00025 package org.objectweb.cjdbc.driver; 00026 00027 import java.io.ByteArrayInputStream; 00028 import java.io.Serializable; 00029 import java.sql.SQLException; 00030 00031 import org.objectweb.cjdbc.common.sql.NotImplementedException; 00032 00033 /** 00034 * The representation (mapping) in the Java <sup><small>TM </small> </sup> 00035 * programming language of an SQL <code>BLOB</code> value. An SQL 00036 * <code>BLOB</code> is a built-in type that stores a Binary Large Object as a 00037 * column value in a row of a database table. By default drivers implement 00038 * <code>Blob</code> using an SQL <code>locator(BLOB)</code>, which means 00039 * that a <code>Blob</code> object contains a logical pointer to the SQL 00040 * <code>BLOB</code> data rather than the data itself. A <code>Blob</code> 00041 * object is valid for the duration of the transaction in which is was created. 00042 * <p> 00043 * Methods in the interfaces {@link DriverResultSet},{@link CallableStatement}, 00044 * and {@link PreparedStatement}, such as <code>getBlob</code> and 00045 * <code>setBlob</code> allow a programmer to access an SQL <code>BLOB</code> 00046 * value. The <code>Blob</code> interface provides methods for getting the 00047 * length of an SQL <code>BLOB</code> (Binary Large Object) value, for 00048 * materializing a <code>BLOB</code> value on the client, and for determining 00049 * the position of a pattern of bytes within a <code>BLOB</code> value. In 00050 * addition, this interface has methods for updating a <code>BLOB</code> 00051 * value. 00052 * 00053 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a> 00054 * @author <a href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a> 00055 * @since JDK 1.2 00056 */ 00057 public class Blob implements java.sql.Blob, Serializable 00058 { 00059 /** The binary data that makes up this <code>BLOB</code>. */ 00060 byte[] binaryData = null; 00061 00062 /** 00063 * Creates a new <code>Blob</code> instance. 00064 * 00065 * @param data an <code>byte</code> array 00066 */ 00067 public Blob(byte[] data) 00068 { 00069 binaryData = data; 00070 } 00071 00072 /** 00073 * Returns the number of bytes in the <code>BLOB</code> value designated by 00074 * this <code>Blob</code> object. 00075 * 00076 * @return length of the <code>BLOB</code> in bytes 00077 * @exception SQLException if there is an error accessing the length of the 00078 * <code>BLOB</code> 00079 * @since JDK 1.2 00080 */ 00081 public long length() throws SQLException 00082 { 00083 return binaryData.length; 00084 } 00085 00086 /** 00087 * Retrieves all or part of the <code>BLOB</code> value that this 00088 * <code>Blob</code> object represents, as an array of bytes. This 00089 * <code>byte</code> array contains up to <code>length</code> consecutive 00090 * bytes starting at position <code>pos</code>. 00091 * 00092 * @param pos the ordinal position of the first byte in the <code>BLOB</code> 00093 * value to be extracted; the first byte is at position 1 00094 * @param length the number of consecutive bytes to be copied 00095 * @return a byte array containing up to <code>length</code> consecutive 00096 * bytes from the <code>BLOB</code> value designated by this 00097 * <code>Blob</code> object, starting with the byte at position 00098 * <code>pos</code> 00099 * @exception SQLException if there is an error accessing the 00100 * <code>BLOB</code> value 00101 * @see #setBytes(long, byte[]) 00102 * @since JDK 1.2 00103 */ 00104 public byte[] getBytes(long pos, int length) throws SQLException 00105 { 00106 byte[] newData = new byte[length]; 00107 00108 System.arraycopy(binaryData, (int) (pos - 1), newData, 0, length); 00109 00110 return newData; 00111 } 00112 00113 /** 00114 * Retrieves the <code>BLOB</code> value designated by this 00115 * <code>Blob</code> instance as a stream. 00116 * 00117 * @return a stream containing the <code>BLOB</code> data 00118 * @exception SQLException if there is an error accessing the 00119 * <code>BLOB</code> value 00120 * @see #setBinaryStream 00121 * @since JDK 1.2 00122 */ 00123 public java.io.InputStream getBinaryStream() throws SQLException 00124 { 00125 return new ByteArrayInputStream(binaryData); 00126 } 00127 00128 /** 00129 * Retrieves the byte position at which the specified byte array 00130 * <code>pattern</code> begins within the <code>BLOB</code> value that 00131 * this <code>Blob</code> object represents. The search for 00132 * <code>pattern</code> begins at position <code>start</code>. 00133 * 00134 * @param pattern the byte array for which to search 00135 * @param start the position at which to begin searching; the first position 00136 * is 1 00137 * @return the position at which the pattern appears, else -1 00138 * @exception SQLException if there is an error accessing the 00139 * <code>BLOB</code> 00140 * @since JDK 1.2 00141 */ 00142 public long position(byte pattern[], long start) throws SQLException 00143 { 00144 return (new String(binaryData)).indexOf(new String(pattern), (int) start); 00145 } 00146 00147 /** 00148 * Retrieves the byte position in the <code>BLOB</code> value designated by 00149 * this <code>Blob</code> object at which <code>pattern</code> begins. The 00150 * search begins at position <code>start</code>. 00151 * 00152 * @param pattern the <code>Blob</code> object designating the 00153 * <code>BLOB</code> value for which to search 00154 * @param start the position in the <code>BLOB</code> value at which to 00155 * begin searching; the first position is 1 00156 * @return the position at which the pattern begins, else -1 00157 * @exception SQLException if there is an error accessing the 00158 * <code>BLOB</code> value 00159 * @since JDK 1.2 00160 */ 00161 public long position(java.sql.Blob pattern, long start) throws SQLException 00162 { 00163 return position(pattern.getBytes(0, (int) pattern.length()), start); 00164 } 00165 00166 // -------------------------- JDBC 3.0 ----------------------------------- 00167 00168 /** 00169 * Writes the given array of bytes to the <code>BLOB</code> value that this 00170 * <code>Blob</code> object represents, starting at position 00171 * <code>pos</code>, and returns the number of bytes written. 00172 * 00173 * @param pos the position in the <code>BLOB</code> object at which to start 00174 * writing 00175 * @param bytes the array of bytes to be written to the <code>BLOB</code> 00176 * value that this <code>Blob</code> object represents 00177 * @return the number of bytes written 00178 * @exception SQLException if there is an error accessing the 00179 * <code>BLOB</code> value 00180 * @see #getBytes 00181 * @since JDK 1.4 00182 */ 00183 public int setBytes(long pos, byte[] bytes) throws SQLException 00184 { 00185 throw new NotImplementedException("setBytes"); 00186 } 00187 00188 /** 00189 * Writes all or part of the given <code>byte</code> array to the 00190 * <code>BLOB</code> value that this <code>Blob</code> object represents 00191 * and returns the number of bytes written. Writing starts at position 00192 * <code>pos</code> in the <code>BLOB</code> value; <code>len</code> 00193 * bytes from the given byte array are written. 00194 * 00195 * @param pos the position in the <code>BLOB</code> object at which to start 00196 * writing 00197 * @param bytes the array of bytes to be written to this <code>BLOB</code> 00198 * object 00199 * @param offset the offset into the array <code>bytes</code> at which to 00200 * start reading the bytes to be set 00201 * @param len the number of bytes to be written to the <code>BLOB</code> 00202 * value from the array of bytes <code>bytes</code> 00203 * @return the number of bytes written 00204 * @exception SQLException if there is an error accessing the 00205 * <code>BLOB</code> value 00206 * @see #getBytes 00207 * @since JDK 1.4 00208 */ 00209 public int setBytes(long pos, byte[] bytes, int offset, int len) 00210 throws SQLException 00211 { 00212 throw new NotImplementedException("setBytes"); 00213 } 00214 00215 /** 00216 * Retrieves a stream that can be used to write to the <code>BLOB</code> 00217 * value that this <code>Blob</code> object represents. The stream begins at 00218 * position <code>pos</code>. 00219 * 00220 * @param pos the position in the <code>BLOB</code> value at which to start 00221 * writing 00222 * @return a <code>java.io.OutputStream</code> object to which data can be 00223 * written 00224 * @exception SQLException if there is an error accessing the 00225 * <code>BLOB</code> value 00226 * @see #getBinaryStream 00227 * @since JDK 1.4 00228 */ 00229 public java.io.OutputStream setBinaryStream(long pos) throws SQLException 00230 { 00231 throw new NotImplementedException("setBinaryStream"); 00232 } 00233 00234 /** 00235 * Truncates the <code>BLOB</code> value that this <code>Blob</code> 00236 * object represents to be <code>len</code> bytes in length. 00237 * 00238 * @param len the length, in bytes, to which the <code>BLOB</code> value 00239 * that this <code>Blob</code> object represents should be 00240 * truncated 00241 * @exception SQLException if there is an error accessing the 00242 * <code>BLOB</code> value 00243 * @since JDK 1.4 00244 */ 00245 public void truncate(long len) throws SQLException 00246 { 00247 throw new NotImplementedException("truncate"); 00248 } 00249 00250 // -------------------------- BLOB Specific 00251 // computation----------------------------------- 00252 00253 }