1. /*

  2.  * @(#)Blob.java	1.27 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.sql;

  9.  

  10. /**

  11.  * The representation (mapping) in

  12.  * the Java<sup><font size=-2>TM</font></sup> programming

  13.  * language of an SQL 

  14.  * <code>BLOB</code> value.  An SQL <code>BLOB</code> is a built-in type 

  15.  * that stores a Binary Large Object as a column value in a row of 

  16.  * a database table. By default drivers implement <code>Blob</code> using

  17.  * an SQL <code>locator(BLOB)</code>, which means that a

  18.  * <code>Blob</code> object contains a logical pointer to the

  19.  * SQL <code>BLOB</code> data rather than the data itself.

  20.  * A <code>Blob</code> object is valid for the duration of the

  21.  * transaction in which is was created.

  22.  * 

  23.  * <P>Methods in the interfaces {@link ResultSet}, 

  24.  * {@link CallableStatement}, and {@link PreparedStatement}, such as

  25.  * <code>getBlob</code> and <code>setBlob</code> allow a programmer to 

  26.  * access an SQL <code>BLOB</code> value.

  27.  * The <code>Blob</code> interface provides methods for getting the

  28.  * length of an SQL <code>BLOB</code> (Binary Large Object) value,

  29.  * for materializing a <code>BLOB</code> value on the client, and for

  30.  * determining the position of a pattern of bytes within a 

  31.  * <code>BLOB</code> value. In addition, this interface has methods for updating

  32.  * a <code>BLOB</code> value.

  33.  *

  34.  * @since 1.2

  35.  */

  36. 

  37. public interface Blob {

  38. 

  39.   /**

  40.    * Returns the number of bytes in the <code>BLOB</code> value

  41.    * designated by this <code>Blob</code> object.

  42.    * @return length of the <code>BLOB</code> in bytes

  43.    * @exception SQLException if there is an error accessing the

  44.    * length of the <code>BLOB</code>

  45.    * @since 1.2

  46.    */

  47.   long length() throws SQLException;

  48. 

  49.   /**

  50.    * Retrieves all or part of the <code>BLOB</code>

  51.    * value that this <code>Blob</code> object represents, as an array of

  52.    * bytes.  This <code>byte</code> array contains up to <code>length</code> 

  53.    * consecutive bytes starting at position <code>pos</code>.

  54.    *

  55.    * @param pos the ordinal position of the first byte in the 

  56.    *        <code>BLOB</code> value to be extracted; the first byte is at

  57.    *        position 1

  58.    * @param length the number of consecutive bytes to be copied

  59.    * @return a byte array containing up to <code>length</code> 

  60.    *         consecutive bytes from the <code>BLOB</code> value designated

  61.    *         by this <code>Blob</code> object, starting with the

  62.    *         byte at position <code>pos</code>

  63.    * @exception SQLException if there is an error accessing the

  64.    *            <code>BLOB</code> value

  65.    * @see #setBytes

  66.    * @since 1.2

  67.    */

  68.   byte[] getBytes(long pos, int length) throws SQLException; 

  69. 

  70.   /**

  71.    * Retrieves the <code>BLOB</code> value designated by this

  72.    * <code>Blob</code> instance as a stream.

  73.    *

  74.    * @return a stream containing the <code>BLOB</code> data

  75.    * @exception SQLException if there is an error accessing the

  76.    *            <code>BLOB</code> value

  77.    * @see #setBinaryStream

  78.    * @since 1.2

  79.    */

  80.   java.io.InputStream getBinaryStream () throws SQLException;

  81. 

  82.   /** 

  83.    * Retrieves the byte position at which the specified byte array

  84.    * <code>pattern</code> begins within the <code>BLOB</code>

  85.    * value that this <code>Blob</code> object represents.  The

  86.    * search for <code>pattern</code> begins at position

  87.    * <code>start</code>.  

  88.    *

  89.    * @param pattern the byte array for which to search

  90.    * @param start the position at which to begin searching; the

  91.    *        first position is 1

  92.    * @return the position at which the pattern appears, else -1

  93.    * @exception SQLException if there is an error accessing the 

  94.    * <code>BLOB</code>

  95.    * @since 1.2

  96.    */

  97.   long position(byte pattern[], long start) throws SQLException;

  98. 

  99.   /** 

  100.    * Retrieves the byte position in the <code>BLOB</code> value

  101.    * designated by this <code>Blob</code> object at which 

  102.    * <code>pattern</code> begins.  The search begins at position

  103.    * <code>start</code>.

  104.    *

  105.    * @param pattern the <code>Blob</code> object designating

  106.    * the <code>BLOB</code> value for which to search

  107.    * @param start the position in the <code>BLOB</code> value

  108.    *        at which to begin searching; the first position is 1

  109.    * @return the position at which the pattern begins, else -1

  110.    * @exception SQLException if there is an error accessing the

  111.    *            <code>BLOB</code> value

  112.    * @since 1.2

  113.    */

  114.   long position(Blob pattern, long start) throws SQLException;

  115. 

  116.     // -------------------------- JDBC 3.0 -----------------------------------

  117. 

  118.     /**

  119.      * Writes the given array of bytes to the <code>BLOB</code> value that

  120.      * this <code>Blob</code> object represents, starting at position 

  121.      * <code>pos</code>, and returns the number of bytes written.

  122.      *

  123.      * @param pos the position in the <code>BLOB</code> object at which

  124.      *        to start writing

  125.      * @param bytes the array of bytes to be written to the <code>BLOB</code>

  126.      *        value that this <code>Blob</code> object represents

  127.      * @return the number of bytes written

  128.      * @exception SQLException if there is an error accessing the

  129.      *            <code>BLOB</code> value

  130.      * @see #getBytes

  131.      * @since 1.4

  132.      */

  133.     int setBytes(long pos, byte[] bytes) throws SQLException;

  134. 

  135.     /**

  136.      * Writes all or part of the given <code>byte</code> array to the

  137.      * <code>BLOB</code> value that this <code>Blob</code> object represents

  138.      * and returns the number of bytes written.

  139.      * Writing starts at position <code>pos</code> in the <code>BLOB</code>

  140.      * value; <code>len</code> bytes from the given byte array are written.

  141.      *

  142.      * @param pos the position in the <code>BLOB</code> object at which

  143.      *        to start writing

  144.      * @param bytes the array of bytes to be written to this <code>BLOB</code>

  145.      *        object

  146.      * @param offset the offset into the array <code>bytes</code> at which

  147.      *        to start reading the bytes to be set

  148.      * @param len the number of bytes to be written to the <code>BLOB</code>

  149.      *        value from the array of bytes <code>bytes</code>

  150.      * @return the number of bytes written

  151.      * @exception SQLException if there is an error accessing the

  152.      *            <code>BLOB</code> value

  153.      * @see #getBytes

  154.      * @since 1.4

  155.      */

  156.     int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException;

  157. 

  158.     /**

  159.      * Retrieves a stream that can be used to write to the <code>BLOB</code> 

  160.      * value that this <code>Blob</code> object represents.  The stream begins

  161.      * at position <code>pos</code>.

  162.      *

  163.      * @param pos the position in the <code>BLOB</code> value at which

  164.      *        to start writing

  165.      * @return a <code>java.io.OutputStream</code> object to which data can 

  166.      *         be written

  167.      * @exception SQLException if there is an error accessing the

  168.      *            <code>BLOB</code> value

  169.      * @see #getBinaryStream

  170.      * @since 1.4

  171.      */

  172.     java.io.OutputStream setBinaryStream(long pos) throws SQLException;

  173. 

  174.     /**

  175.      * Truncates the <code>BLOB</code> value that this <code>Blob</code>

  176.      * object represents to be <code>len</code> bytes in length.

  177.      *

  178.      * @param len the length, in bytes, to which the <code>BLOB</code> value

  179.      *        that this <code>Blob</code> object represents should be truncated

  180.      * @exception SQLException if there is an error accessing the

  181.      *            <code>BLOB</code> value

  182.      * @since 1.4

  183.      */

  184.     void truncate(long len) throws SQLException;

  185. 

  186. }

  187. 

  188.