Module java.sql
Package java.sql

Interface Blob

All Known Implementing Classes:
SerialBlob
public interfaceBlob
The representation (mapping) in the Java programming language of an SQLBLOB value. An SQLBLOB 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 implementBlob using an SQLlocator(BLOB), which means that aBlob object contains a logical pointer to the SQLBLOB data rather than the data itself. ABlob object is valid for the duration of the transaction in which is was created.

Methods in the interfacesResultSet,CallableStatement, andPreparedStatement, such asgetBlob andsetBlob allow a programmer to access an SQLBLOB value. TheBlob interface provides methods for getting the length of an SQLBLOB (Binary Large Object) value, for materializing aBLOB value on the client, and for determining the position of a pattern of bytes within aBLOB value. In addition, this interface has methods for updating aBLOB value.

All methods on theBlob interface must be fully implemented if the JDBC driver supports the data type.

Since:
1.2

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    This method frees theBlob object and releases the resources that it holds.
    Retrieves theBLOB value designated by thisBlob instance as a stream.
    getBinaryStream(long pos, long length)
    Returns anInputStream object that contains a partialBlob value, starting with the byte specified by pos, which is length bytes in length.
    byte[]
    getBytes(long pos, int length)
    Retrieves all or part of theBLOB value that thisBlob object represents, as an array of bytes.
    long
    Returns the number of bytes in theBLOB value designated by thisBlob object.
    long
    position(byte[] pattern, long start)
    Retrieves the byte position at which the specified byte arraypattern begins within theBLOB value that thisBlob object represents.
    long
    position(Blob pattern, long start)
    Retrieves the byte position in theBLOB value designated by thisBlob object at whichpattern begins.
    setBinaryStream(long pos)
    Retrieves a stream that can be used to write to theBLOB value that thisBlob object represents.
    int
    setBytes(long pos, byte[] bytes)
    Writes the given array of bytes to theBLOB value that thisBlob object represents, starting at positionpos, and returns the number of bytes written.
    int
    setBytes(long pos, byte[] bytes, int offset, int len)
    Writes all or part of the givenbyte array to theBLOB value that thisBlob object represents and returns the number of bytes written.
    void
    truncate(long len)
    Truncates theBLOB value that thisBlob object represents to belen bytes in length.

  • Method Details

    • length

      long length() throwsSQLException
      Returns the number of bytes in theBLOB value designated by thisBlob object.
      Returns:
      length of theBLOB in bytes
      Throws:
      SQLException - if there is an error accessing the length of theBLOB
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • getBytes

      byte[] getBytes(long pos, int length) throwsSQLException
      Retrieves all or part of theBLOB value that thisBlob object represents, as an array of bytes. Thisbyte array contains up tolength consecutive bytes starting at positionpos.
      Parameters:
      pos - the ordinal position of the first byte in theBLOB value to be extracted; the first byte is at position 1
      length - the number of consecutive bytes to be copied; the value for length must be 0 or greater
      Returns:
      a byte array containing up tolength consecutive bytes from theBLOB value designated by thisBlob object, starting with the byte at positionpos
      Throws:
      SQLException - if there is an error accessing theBLOB value; if pos is less than 1 or length is less than 0
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2
      See Also:

    • getBinaryStream

      InputStream getBinaryStream() throwsSQLException
      Retrieves theBLOB value designated by thisBlob instance as a stream.
      Returns:
      a stream containing theBLOB data
      Throws:
      SQLException - if there is an error accessing theBLOB value
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2
      See Also:

    • position

      long position(byte[] pattern, long start) throwsSQLException
      Retrieves the byte position at which the specified byte arraypattern begins within theBLOB value that thisBlob object represents. The search forpattern begins at positionstart.
      Parameters:
      pattern - the byte array for which to search
      start - the position at which to begin searching; the first position is 1
      Returns:
      the position at which the pattern appears, else -1
      Throws:
      SQLException - if there is an error accessing theBLOB or if start is less than 1
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • position

      long position(Blob pattern, long start) throwsSQLException
      Retrieves the byte position in theBLOB value designated by thisBlob object at whichpattern begins. The search begins at positionstart.
      Parameters:
      pattern - theBlob object designating theBLOB value for which to search
      start - the position in theBLOB value at which to begin searching; the first position is 1
      Returns:
      the position at which the pattern begins, else -1
      Throws:
      SQLException - if there is an error accessing theBLOB value or if start is less than 1
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • setBytes

      int setBytes(long pos, byte[] bytes) throwsSQLException
      Writes the given array of bytes to theBLOB value that thisBlob object represents, starting at positionpos, and returns the number of bytes written. The array of bytes will overwrite the existing bytes in theBlob object starting at the positionpos. If the end of theBlob value is reached while writing the array of bytes, then the length of theBlob value will be increased to accommodate the extra bytes.

      Note: If the value specified forpos is greater than the length+1 of theBLOB value then the behavior is undefined. Some JDBC drivers may throw anSQLException while other drivers may support this operation.

      Parameters:
      pos - the position in theBLOB object at which to start writing; the first position is 1
      bytes - the array of bytes to be written to theBLOB value that thisBlob object represents
      Returns:
      the number of bytes written
      Throws:
      SQLException - if there is an error accessing theBLOB value or if pos is less than 1
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.4
      See Also:

    • setBytes

      int setBytes(long pos, byte[] bytes, int offset, int len) throwsSQLException
      Writes all or part of the givenbyte array to theBLOB value that thisBlob object represents and returns the number of bytes written. Writing starts at positionpos in theBLOB value;len bytes from the given byte array are written. The array of bytes will overwrite the existing bytes in theBlob object starting at the positionpos. If the end of theBlob value is reached while writing the array of bytes, then the length of theBlob value will be increased to accommodate the extra bytes.

      Note: If the value specified forpos is greater than the length+1 of theBLOB value then the behavior is undefined. Some JDBC drivers may throw anSQLException while other drivers may support this operation.

      Parameters:
      pos - the position in theBLOB object at which to start writing; the first position is 1
      bytes - the array of bytes to be written to thisBLOB object
      offset - the offset into the arraybytes at which to start reading the bytes to be set
      len - the number of bytes to be written to theBLOB value from the array of bytesbytes
      Returns:
      the number of bytes written
      Throws:
      SQLException - if there is an error accessing theBLOB value or if pos is less than 1
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.4
      See Also:

    • setBinaryStream

      OutputStream setBinaryStream(long pos) throwsSQLException
      Retrieves a stream that can be used to write to theBLOB value that thisBlob object represents. The stream begins at positionpos. The bytes written to the stream will overwrite the existing bytes in theBlob object starting at the positionpos. If the end of theBlob value is reached while writing to the stream, then the length of theBlob value will be increased to accommodate the extra bytes.

      Note: If the value specified forpos is greater than the length+1 of theBLOB value then the behavior is undefined. Some JDBC drivers may throw anSQLException while other drivers may support this operation.

      Parameters:
      pos - the position in theBLOB value at which to start writing; the first position is 1
      Returns:
      ajava.io.OutputStream object to which data can be written
      Throws:
      SQLException - if there is an error accessing theBLOB value or if pos is less than 1
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.4
      See Also:

    • truncate

      void truncate(long len) throwsSQLException
      Truncates theBLOB value that thisBlob object represents to belen bytes in length.

      Note: If the value specified forpos is greater than the length+1 of theBLOB value then the behavior is undefined. Some JDBC drivers may throw anSQLException while other drivers may support this operation.

      Parameters:
      len - the length, in bytes, to which theBLOB value that thisBlob object represents should be truncated
      Throws:
      SQLException - if there is an error accessing theBLOB value or if len is less than 0
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.4

    • free

      void free() throwsSQLException
      This method frees theBlob object and releases the resources that it holds. The object is invalid once thefree method is called.

      Afterfree has been called, any attempt to invoke a method other thanfree will result in anSQLException being thrown. Iffree is called multiple times, the subsequent calls tofree are treated as a no-op.

      Throws:
      SQLException - if an error occurs releasing the Blob's resources
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.6

    • getBinaryStream

      InputStream getBinaryStream(long pos, long length) throwsSQLException
      Returns anInputStream object that contains a partialBlob value, starting with the byte specified by pos, which is length bytes in length.
      Parameters:
      pos - the offset to the first byte of the partial value to be retrieved. The first byte in theBlob is at position 1.
      length - the length in bytes of the partial value to be retrieved
      Returns:
      InputStream through which the partialBlob value can be read.
      Throws:
      SQLException - if pos is less than 1 or if pos is greater than the number of bytes in theBlob or if pos + length is greater than the number of bytes in theBlob
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.6