Blob.java

/**
 * C-JDBC: Clustered JDBC.
 * Copyright (C) 2002-2004 French National Institute For Research In Computer
 * Science And Control (INRIA).
 * Contact: c-jdbc@objectweb.org
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by the
 * Free Software Foundation; either version 2.1 of the License, or any later
 * version.
 * 
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 *
 * Initial developer(s): Emmanuel Cecchet.
 * Contributor(s): Nicolas Modrzyk.
 */

package org.objectweb.cjdbc.driver;

import java.io.ByteArrayInputStream;
import java.io.Serializable;
import java.sql.SQLException;

import org.objectweb.cjdbc.common.sql.NotImplementedException;

/**
 * The representation (mapping) in the Java <sup><small>TM </small> </sup>
 * programming language of an SQL <code>BLOB</code> value. An SQL
 * <code>BLOB</code> is a built-in type that stores a Binary Large Object as a
 * column value in a row of a database table. By default drivers implement
 * <code>Blob</code> using an SQL <code>locator(BLOB)</code>, which means
 * that a <code>Blob</code> object contains a logical pointer to the SQL
 * <code>BLOB</code> data rather than the data itself. A <code>Blob</code>
 * object is valid for the duration of the transaction in which is was created.
 * <p>
 * Methods in the interfaces {@link DriverResultSet},{@link CallableStatement},
 * and {@link PreparedStatement}, such as <code>getBlob</code> and
 * <code>setBlob</code> allow a programmer to access an SQL <code>BLOB</code>
 * value. The <code>Blob</code> interface provides methods for getting the
 * length of an SQL <code>BLOB</code> (Binary Large Object) value, for
 * materializing a <code>BLOB</code> value on the client, and for determining
 * the position of a pattern of bytes within a <code>BLOB</code> value. In
 * addition, this interface has methods for updating a <code>BLOB</code>
 * value.
 * 
 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
 * @author <a href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
 * @since JDK 1.2
 */
public class Blob implements java.sql.Blob, Serializable
{
  /** The binary data that makes up this <code>BLOB</code>. */
  byte[] binaryData = null;

  /**
   * Creates a new <code>Blob</code> instance.
   * 
   * @param data an <code>byte</code> array
   */
  public Blob(byte[] data)
  {
    binaryData = data;
  }

  /**
   * Returns the number of bytes in the <code>BLOB</code> value designated by
   * this <code>Blob</code> object.
   * 
   * @return length of the <code>BLOB</code> in bytes
   * @exception SQLException if there is an error accessing the length of the
   *              <code>BLOB</code>
   * @since JDK 1.2
   */
  public long length() throws SQLException
  {
    return binaryData.length;
  }

  /**
   * Retrieves all or part of the <code>BLOB</code> value that this
   * <code>Blob</code> object represents, as an array of bytes. This
   * <code>byte</code> array contains up to <code>length</code> consecutive
   * bytes starting at position <code>pos</code>.
   * 
   * @param pos the ordinal position of the first byte in the <code>BLOB</code>
   *          value to be extracted; the first byte is at position 1
   * @param length the number of consecutive bytes to be copied
   * @return a byte array containing up to <code>length</code> consecutive
   *         bytes from the <code>BLOB</code> value designated by this
   *         <code>Blob</code> object, starting with the byte at position
   *         <code>pos</code>
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @see #setBytes(long, byte[])
   * @since JDK 1.2
   */
  public byte[] getBytes(long pos, int length) throws SQLException
  {
    byte[] newData = new byte[length];

    System.arraycopy(binaryData, (int) (pos - 1), newData, 0, length);

    return newData;
  }

  /**
   * Retrieves the <code>BLOB</code> value designated by this
   * <code>Blob</code> instance as a stream.
   * 
   * @return a stream containing the <code>BLOB</code> data
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @see #setBinaryStream
   * @since JDK 1.2
   */
  public java.io.InputStream getBinaryStream() throws SQLException
  {
    return new ByteArrayInputStream(binaryData);
  }

  /**
   * Retrieves the byte position at which the specified byte array
   * <code>pattern</code> begins within the <code>BLOB</code> value that
   * this <code>Blob</code> object represents. The search for
   * <code>pattern</code> begins at position <code>start</code>.
   * 
   * @param pattern the byte array for which to search
   * @param start the position at which to begin searching; the first position
   *          is 1
   * @return the position at which the pattern appears, else -1
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code>
   * @since JDK 1.2
   */
  public long position(byte pattern[], long start) throws SQLException
  {
    return (new String(binaryData)).indexOf(new String(pattern), (int) start);
  }

  /**
   * Retrieves the byte position in the <code>BLOB</code> value designated by
   * this <code>Blob</code> object at which <code>pattern</code> begins. The
   * search begins at position <code>start</code>.
   * 
   * @param pattern the <code>Blob</code> object designating the
   *          <code>BLOB</code> value for which to search
   * @param start the position in the <code>BLOB</code> value at which to
   *          begin searching; the first position is 1
   * @return the position at which the pattern begins, else -1
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @since JDK 1.2
   */
  public long position(java.sql.Blob pattern, long start) throws SQLException
  {
    return position(pattern.getBytes(0, (int) pattern.length()), start);
  }

  // -------------------------- JDBC 3.0 -----------------------------------

  /**
   * Writes the given array of bytes to the <code>BLOB</code> value that this
   * <code>Blob</code> object represents, starting at position
   * <code>pos</code>, and returns the number of bytes written.
   * 
   * @param pos the position in the <code>BLOB</code> object at which to start
   *          writing
   * @param bytes the array of bytes to be written to the <code>BLOB</code>
   *          value that this <code>Blob</code> object represents
   * @return the number of bytes written
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @see #getBytes
   * @since JDK 1.4
   */
  public int setBytes(long pos, byte[] bytes) throws SQLException
  {
    throw new NotImplementedException("setBytes");
  }

  /**
   * Writes all or part of the given <code>byte</code> array to the
   * <code>BLOB</code> value that this <code>Blob</code> object represents
   * and returns the number of bytes written. Writing starts at position
   * <code>pos</code> in the <code>BLOB</code> value; <code>len</code>
   * bytes from the given byte array are written.
   * 
   * @param pos the position in the <code>BLOB</code> object at which to start
   *          writing
   * @param bytes the array of bytes to be written to this <code>BLOB</code>
   *          object
   * @param offset the offset into the array <code>bytes</code> at which to
   *          start reading the bytes to be set
   * @param len the number of bytes to be written to the <code>BLOB</code>
   *          value from the array of bytes <code>bytes</code>
   * @return the number of bytes written
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @see #getBytes
   * @since JDK 1.4
   */
  public int setBytes(long pos, byte[] bytes, int offset, int len)
      throws SQLException
  {
    throw new NotImplementedException("setBytes");
  }

  /**
   * Retrieves a stream that can be used to write to the <code>BLOB</code>
   * value that this <code>Blob</code> object represents. The stream begins at
   * position <code>pos</code>.
   * 
   * @param pos the position in the <code>BLOB</code> value at which to start
   *          writing
   * @return a <code>java.io.OutputStream</code> object to which data can be
   *         written
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @see #getBinaryStream
   * @since JDK 1.4
   */
  public java.io.OutputStream setBinaryStream(long pos) throws SQLException
  {
    throw new NotImplementedException("setBinaryStream");
  }

  /**
   * Truncates the <code>BLOB</code> value that this <code>Blob</code>
   * object represents to be <code>len</code> bytes in length.
   * 
   * @param len the length, in bytes, to which the <code>BLOB</code> value
   *          that this <code>Blob</code> object represents should be
   *          truncated
   * @exception SQLException if there is an error accessing the
   *              <code>BLOB</code> value
   * @since JDK 1.4
   */
  public void truncate(long len) throws SQLException
  {
    throw new NotImplementedException("truncate");
  }

  // -------------------------- BLOB Specific
  // computation-----------------------------------

}

---