Blob (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.sql
Interface Blob

public interface Blob

The representation (mapping) in the JavaTM programming language of an SQL `BLOB` value. An SQL `BLOB` 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 `Blob` using an SQL `locator(BLOB)`, which means that a `Blob` object contains a logical pointer to the SQL `BLOB` data rather than the data itself. A `Blob` object is valid for the duration of the transaction in which is was created.

Methods in the interfaces `ResultSet`, `CallableStatement`, and `PreparedStatement`, such as `getBlob` and `setBlob` allow a programmer to access an SQL `BLOB` value. The `Blob` interface provides methods for getting the length of an SQL `BLOB` (Binary Large Object) value, for materializing a `BLOB` value on the client, and for determining the position of a pattern of bytes within a `BLOB` value. In addition, this interface has methods for updating a `BLOB` value.

Since:
  1.2

Method Summary
`InputStream` | `getBinaryStream()` Retrieves the `BLOB` value designated by this `Blob` instance as a stream.
`byte[]` | `getBytes(long pos, int length)` Retrieves all or part of the `BLOB` value that this `Blob` object represents, as an array of bytes.
`long` | `length()` Returns the number of bytes in the `BLOB` value designated by this `Blob` object.
`long` | `position(Blob pattern, long start)` Retrieves the byte position in the `BLOB` value designated by this `Blob` object at which `pattern` begins.
`long` | `position(byte[] pattern, long start)` Retrieves the byte position at which the specified byte array `pattern` begins within the `BLOB` value that this `Blob` object represents.
`OutputStream` | `setBinaryStream(long pos)` Retrieves a stream that can be used to write to the `BLOB` value that this `Blob` object represents.
`int` | `setBytes(long pos, byte[] bytes)` Writes the given array of bytes to the `BLOB` value that this `Blob` object represents, starting at position `pos`, and returns the number of bytes written.
`int` | `setBytes(long pos, byte[] bytes, int offset, int len)` Writes all or part of the given `byte` array to the `BLOB` value that this `Blob` object represents and returns the number of bytes written.
`void` | `truncate(long len)` Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length.

Method Detail

### length

    public long length()
                throws SQLException

  Returns the number of bytes in the `BLOB` value designated by this `Blob` object.

  Returns:
    length of the `BLOB` in bytes
  Throws:
    `SQLException` - if there is an error accessing the length of the `BLOB`
  Since:
    1.2

### getBytes

    public byte[] getBytes(long pos,
                           int length)
                    throws SQLException

  Retrieves all or part of the `BLOB` value that this `Blob` object represents, as an array of bytes. This `byte` array contains up to `length` consecutive bytes starting at position `pos`.

  Parameters:
    `pos` - the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1
    `length` - the number of consecutive bytes to be copied
  Returns:
    a byte array containing up to `length` consecutive bytes from the `BLOB` value designated by this `Blob` object, starting with the byte at position `pos`
  Throws:
    `SQLException` - if there is an error accessing the `BLOB` value
  Since:
    1.2
  See Also:
    `setBytes(long, byte[])`

### getBinaryStream

    public InputStream getBinaryStream()
                                throws SQLException

  Retrieves the `BLOB` value designated by this `Blob` instance as a stream.

  Returns:
    a stream containing the `BLOB` data
  Throws:
    `SQLException` - if there is an error accessing the `BLOB` value
  Since:
    1.2
  See Also:
    `setBinaryStream(long)`

### position

    public long position(byte[] pattern,
                         long start)
                  throws SQLException

  Retrieves the byte position at which the specified byte array `pattern` begins within the `BLOB` value that this `Blob` object represents. The search for `pattern` begins at position `start`.

  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 the `BLOB`
  Since:
    1.2

### position

    public long position(Blob pattern,
                         long start)
                  throws SQLException

  Retrieves the byte position in the `BLOB` value designated by this `Blob` object at which `pattern` begins. The search begins at position `start`.

  Parameters:
    `pattern` - the `Blob` object designating the `BLOB` value for which to search
    `start` - the position in the `BLOB` 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 the `BLOB` value
  Since:
    1.2

### setBytes

    public int setBytes(long pos,
                        byte[] bytes)
                 throws SQLException

  Writes the given array of bytes to the `BLOB` value that this `Blob` object represents, starting at position `pos`, and returns the number of bytes written.

  Parameters:
    `pos` - the position in the `BLOB` object at which to start writing
    `bytes` - the array of bytes to be written to the `BLOB` value that this `Blob` object represents
  Returns:
    the number of bytes written
  Throws:
    `SQLException` - if there is an error accessing the `BLOB` value
  Since:
    1.4
  See Also:
    `getBytes(long, int)`

### setBytes

    public int setBytes(long pos,
                        byte[] bytes,
                        int offset,
                        int len)
                 throws SQLException

  Writes all or part of the given `byte` array to the `BLOB` value that this `Blob` object represents and returns the number of bytes written. Writing starts at position `pos` in the `BLOB` value; `len` bytes from the given byte array are written.

  Parameters:
    `pos` - the position in the `BLOB` object at which to start writing
    `bytes` - the array of bytes to be written to this `BLOB` object
    `offset` - the offset into the array `bytes` at which to start reading the bytes to be set
    `len` - the number of bytes to be written to the `BLOB` value from the array of bytes `bytes`
  Returns:
    the number of bytes written
  Throws:
    `SQLException` - if there is an error accessing the `BLOB` value
  Since:
    1.4
  See Also:
    `getBytes(long, int)`

### setBinaryStream

    public OutputStream setBinaryStream(long pos)
                                 throws SQLException

  Retrieves a stream that can be used to write to the `BLOB` value that this `Blob` object represents. The stream begins at position `pos`.

  Parameters:
    `pos` - the position in the `BLOB` value at which to start writing
  Returns:
    a `java.io.OutputStream` object to which data can be written
  Throws:
    `SQLException` - if there is an error accessing the `BLOB` value
  Since:
    1.4
  See Also:
    `getBinaryStream()`

### truncate

    public void truncate(long len)
                  throws SQLException

  Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length.

  Parameters:
    `len` - the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated
  Throws:
    `SQLException` - if there is an error accessing the `BLOB` value
  Since:
    1.4

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.