home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / sql / Blob.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  4.4 KB  |  114 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Blob.java    1.7 98/05/08
  3.  * 
  4.  * Copyright 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * JDBC 2.0
  19.  *
  20.  * <p>
  21.  * The representation (mapping) in
  22.  * the Java<sup><font size=-2>TM</font></sup> programming
  23.  * language of an SQL 
  24.  * <code>BLOB</code>.  An SQL <code>BLOB</code> is a built-in type 
  25.  * that stores a Binary Large Object as a column value in a row of 
  26.  * a database table. The driver implements <code>Blob</code> using
  27.  * an SQL <code>locator(BLOB)</code>, which means that a
  28.  * <code>Blob</code> object contains a logical pointer to the
  29.  * SQL <code>BLOB</code> data rather than the data itself.
  30.  * A <code>Blob</code> object is valid for the duration of the
  31.  * transaction in which is was created.
  32.  * 
  33.  * <P>Methods in the interfaces {@link ResultSet}, 
  34.  * {@link CallableStatement}, and {@link PreparedStatement}, such as
  35.  * <code>getBlob</code> and <code>setBlob</code> allow a programmer to 
  36.  * access the SQL <code>BLOB</code>.
  37.  * The <code>Blob</code> interface provides methods for getting the
  38.  * length of an SQL <code>BLOB</code> (Binary Large Object) value,
  39.  * for materializing a <code>BLOB</code> value on the client, and for
  40.  * determining the position of a pattern of bytes within a 
  41.  * <code>BLOB</code> value. 
  42.  */
  43.  
  44. public interface Blob {
  45.  
  46.   /**
  47.    * Returns the number of bytes in the <code>BLOB</code> value
  48.    * designated by this <code>Blob</code> object.
  49.    * @return length of the <code>BLOB</code> in bytes
  50.    * @exception SQLException if there is an error accessing the
  51.    * length of the <code>BLOB</code>
  52.    */
  53.   long length() throws SQLException;
  54.  
  55.   /**
  56.    * Returns as an array of bytes part or all of the <code>BLOB</code>
  57.    * value that this <code>Blob</code> object designates.  The byte
  58.    * array contains up to <code>length</code> consecutive bytes
  59.    * starting at position <code>pos</code>.
  60.    * @param pos the ordinal position of the first byte in the 
  61.    * <code>BLOB</code> value to be extracted; the first byte is at
  62.    * position 1
  63.    * @param length is the number of consecutive bytes to be copied
  64.    * @return a byte array containing up to <code>length</code> 
  65.    * consecutive bytes from the <code>BLOB</code> value designated
  66.    * by this <code>Blob</code> object, starting with the
  67.    * byte at position <code>pos</code>.
  68.    * @exception SQLException if there is an error accessing the
  69.    * <code>BLOB</code>
  70.    */
  71.   byte[] getBytes(long pos, int length) throws SQLException; 
  72.  
  73.   /**
  74.    * Retrieves the <code>BLOB</code> designated by this
  75.    * <code>Blob</code> instance as a stream.
  76.    * @return a stream containing the <code>BLOB</code> data
  77.    * @exception SQLException if there is an error accessing the
  78.    * <code>BLOB</code>
  79.    */
  80.   java.io.InputStream getBinaryStream () throws SQLException;
  81.  
  82.   /** 
  83.    * Determines the byte position at which the specified byte 
  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.    * @param pattern the byte array for which to search
  89.    * @param start the position at which to begin searching; the
  90.    *        first position is 1
  91.    * @return the position at which the pattern appears, else -1.
  92.    * @exception SQLException if there is an error accessing the 
  93.    * <code>BLOB</code>
  94.    */
  95.   long position(byte pattern[], long start) throws SQLException;
  96.  
  97.   /** 
  98.    * Determines the byte position in the <code>BLOB</code> value
  99.    * designated by this <code>Blob</code> object at which 
  100.    * <code>pattern</code> begins.  The search begins at position
  101.    * <code>start</code>.
  102.    * @param pattern the <code>Blob</code> object designating
  103.    * the <code>BLOB</code> value for which to search
  104.    * @param start the position in the <code>BLOB</code> value
  105.    *        at which to begin searching; the first position is 1
  106.    * @return the position at which the pattern begins, else -1
  107.    * @exception SQLException if there is an error accessing the
  108.    * <code>BLOB</code>
  109.    */
  110.   long position(Blob pattern, long start) throws SQLException;
  111. }
  112.  
  113.  
  114.