/*
 * @(#)Blob.java	1.7 98/05/08
 * 
 * Copyright 1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package java.sql;
 
/**
 * JDBC 2.0
 *
 * <p>By default, a Blob is a transaction duration reference to a 
 * binary large object. By default, a Blob is implemented using a
 * LOCATOR(blob) internally.
 */

public interface Blob {

  /**
   * The length of the Binary Large OBject in bytes.
   *
   * @return length of the BLOB in bytes
   */
  long length() throws SQLException;

  /**
   * Return a copy of the contents of the BLOB at the requested 
   * position.
   *
   * @param pos is the first byte of the blob to be extracted.
   * @param length is the number of consecutive bytes to be copied.
   *
   * @return a byte array containing a portion of the BLOB
   */
  byte[] getBytes(long pos, int length) throws SQLException; 

  /**
   * Retrieve the entire BLOB as a stream.
   *
   * @return a stream containing the BLOB data
   */
  java.io.InputStream getBinaryStream () throws SQLException;

  /** 
   * Determine the byte position at which the given byte pattern 
   * @pattern starts in the BLOB.  Begin search at position @start.
   * Return -1 if the pattern does not appear in the BLOB.
   *
   * @param  pattern is the pattern to search for.
   * @param start is the position at which to begin searching.
   * @return the position at which the pattern appears, else -1.
   */
  long position(byte pattern[], long start) throws SQLException;

  /** 
   * Determine the byte position at which the given pattern 
   * @pattern starts in the BLOB.  Begin search at position @start.
   * Return -1 if the pattern does not appear in the BLOB.
   *
   * @param searchstr is the pattern to search for.
   * @param start is the position at which to begin searching.
   * @return the position at which the pattern appears, else -1.
   */
  long position(Blob pattern, long start) throws SQLException;
}


