Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.sql.rowset.serial
Class SerialBlob

    java.lang.Object
      javax.sql.rowset.serial.SerialBlob

All Implemented Interfaces:
  Serializable, Cloneable, Blob

    public class SerialBlob

extends Object
implements Blob, Serializable, Cloneable

A serialized mapping in the Java programming language of an SQL `BLOB` value.

The `SerialBlob` class provides a constructor for creating an instance from a `Blob` object. Note that the `Blob` object should have brought the SQL `BLOB` value's data over to the client before a `SerialBlob` object is constructed from it. The data of an SQL `BLOB` value can be materialized on the client as an array of bytes (using the method `Blob.getBytes`) or as a stream of uninterpreted bytes (using the method `Blob.getBinaryStream`).

`SerialBlob` methods make it possible to make a copy of a `SerialBlob` object as an array of bytes or as a stream. They also make it possible to locate a given pattern of bytes or a `Blob` object within a `SerialBlob` object and to update or truncate a `Blob` object.

See Also:
  Serialized Form

Constructor Summary
`SerialBlob(Blob blob)` Constructs a `SerialBlob` object that is a serialized version of the given `Blob` object.
`SerialBlob(byte[] b)` Constructs a `SerialBlob` object that is a serialized version of the given `byte` array.

Method Summary
`void` | `free()` This method frees the `Blob` object and releases the resources that it holds.
`InputStream` | `getBinaryStream()` Returns this `SerialBlob` object as an input stream.
`InputStream` | `getBinaryStream(long pos, long length)` Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.
`byte[]` | `getBytes(long pos, int length)` Copies the specified number of bytes, starting at the given position, from this `SerialBlob` object to another array of bytes.
`long` | `length()` Retrieves the number of bytes in this `SerialBlob` object's array of bytes.
`long` | `position(Blob pattern, long start)` Returns the position in this `SerialBlob` object where the given `Blob` object begins, starting the search at the specified position.
`long` | `position(byte[] pattern, long start)` Returns the position in this `SerialBlob` object where the given pattern of bytes begins, starting the search at the specified position.
`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 length)` 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 length)` Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### SerialBlob

    public SerialBlob(byte[] b)
               throws SerialException,
                      SQLException

  Constructs a `SerialBlob` object that is a serialized version of the given `byte` array.

  The new `SerialBlob` object is initialized with the data from the `byte` array, thus allowing disconnected `RowSet` objects to establish serialized `Blob` objects without touching the data source.

  Parameters:
    `b` - the `byte` array containing the data for the `Blob` object to be serialized
  Throws:
    `SerialException` - if an error occurs during serialization
    `SQLException` - if a SQL errors occurs

### SerialBlob

    public SerialBlob(Blob blob)
               throws SerialException,
                      SQLException

  Constructs a `SerialBlob` object that is a serialized version of the given `Blob` object.

  The new `SerialBlob` object is initialized with the data from the `Blob` object; therefore, the `Blob` object should have previously brought the SQL `BLOB` value's data over to the client from the database. Otherwise, the new `SerialBlob` object will contain no data.

  Parameters:
    `blob` - the `Blob` object from which this `SerialBlob` object is to be constructed; cannot be null.
  Throws:
    `SerialException` - if an error occurs during serialization
    `SQLException` - if the `Blob` passed to this to this constructor is a `null`.
  See Also:
    `Blob`

Method Detail

### getBytes

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

  Copies the specified number of bytes, starting at the given position, from this `SerialBlob` object to another array of bytes.

  Note that if the given number of bytes to be copied is larger than the length of this `SerialBlob` object's array of bytes, the given number will be shortened to the array's length.

  Specified by:
    `getBytes` in interface `Blob`
  Parameters:
    `pos` - the ordinal position of the first byte in this `SerialBlob` object to be copied; numbering starts at `1`; must not be less than `1` and must be less than or equal to the length of this `SerialBlob` object
    `length` - the number of bytes to be copied
  Returns:
    an array of bytes that is a copy of a region of this `SerialBlob` object, starting at the given position and containing the given number of consecutive bytes
  Throws:
    `SerialException` - if the given starting position is out of bounds
  See Also:
    `Blob.setBytes(long, byte[])`

### length

    public long length()
                throws SerialException

  Retrieves the number of bytes in this `SerialBlob` object's array of bytes.

  Specified by:
    `length` in interface `Blob`
  Returns:
    a `long` indicating the length in bytes of this `SerialBlob` object's array of bytes
  Throws:
    `SerialException` - if an error occurs

### getBinaryStream

    public InputStream getBinaryStream()
                                throws SerialException

  Returns this `SerialBlob` object as an input stream. Unlike the related method, `setBinaryStream`, a stream is produced regardless of whether the `SerialBlob` was created with a `Blob` object or a `byte` array.

  Specified by:
    `getBinaryStream` in interface `Blob`
  Returns:
    a `java.io.InputStream` object that contains this `SerialBlob` object's array of bytes
  Throws:
    `SerialException` - if an error occurs
  See Also:
    `setBinaryStream(long)`

### position

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

  Returns the position in this `SerialBlob` object where the given pattern of bytes begins, starting the search at the specified position.

  Specified by:
    `position` in interface `Blob`
  Parameters:
    `pattern` - the pattern of bytes for which to search
    `start` - the position of the byte in this `SerialBlob` object from which to begin the search; the first position is `1`; must not be less than `1` nor greater than the length of this `SerialBlob` object
  Returns:
    the position in this `SerialBlob` object where the given pattern begins, starting at the specified position; `-1` if the pattern is not found or the given starting position is out of bounds; position numbering for the return value starts at `1`
  Throws:
    `SerialException` - if an error occurs when serializing the blob
    `SQLException` - if there is an error accessing the `BLOB` value from the database

### position

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

  Returns the position in this `SerialBlob` object where the given `Blob` object begins, starting the search at the specified position.

  Specified by:
    `position` in interface `Blob`
  Parameters:
    `pattern` - the `Blob` object for which to search;
    `start` - the position of the byte in this `SerialBlob` object from which to begin the search; the first position is `1`; must not be less than `1` nor greater than the length of this `SerialBlob` object
  Returns:
    the position in this `SerialBlob` object where the given `Blob` object begins, starting at the specified position; `-1` if the pattern is not found or the given starting position is out of bounds; position numbering for the return value starts at `1`
  Throws:
    `SerialException` - if an error occurs when serializing the blob
    `SQLException` - if there is an error accessing the `BLOB` value from the database

### setBytes

    public int setBytes(long pos,
                        byte[] bytes)
                 throws SerialException,
                        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.

  Specified by:
    `setBytes` in interface `Blob`
  Parameters:
    `pos` - the position in the SQL `BLOB` value at which to start writing. The first position is `1`; must not be less than `1` nor greater than the length of this `SerialBlob` object.
    `bytes` - the array of bytes to be written to the `BLOB` value that this `Blob` object represents
  Returns:
    the number of bytes written
  Throws:
    `SerialException` - if there is an error accessing the `BLOB` value; or if an invalid position is set; if an invalid offset value is set
    `SQLException` - if there is an error accessing the `BLOB` value from the database
  See Also:
    `getBytes(long, int)`

### setBytes

    public int setBytes(long pos,
                        byte[] bytes,
                        int offset,
                        int length)
                 throws SerialException,
                        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.

  Specified by:
    `setBytes` in interface `Blob`
  Parameters:
    `pos` - the position in the `BLOB` object at which to start writing. The first position is `1`; must not be less than `1` nor greater than the length of this `SerialBlob` object.
    `bytes` - the array of bytes to be written to the `BLOB` value
    `offset` - the offset in the `byte` array at which to start reading the bytes. The first offset position is `0`; must not be less than `0` nor greater than the length of the `byte` array
    `length` - the number of bytes to be written to the `BLOB` value from the array of bytes bytes.
  Returns:
    the number of bytes written
  Throws:
    `SerialException` - if there is an error accessing the `BLOB` value; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than the `SerialBlob` length; or the combined values of the length and offset is greater than the Blob buffer
    `SQLException` - if there is an error accessing the `BLOB` value from the database.
  See Also:
    `getBytes(long, int)`

### setBinaryStream

    public OutputStream setBinaryStream(long pos)
                                 throws SerialException,
                                        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`. This method forwards the `setBinaryStream()` call to the underlying `Blob` in the event that this `SerialBlob` object is instantiated with a `Blob`. If this `SerialBlob` is instantiated with a `byte` array, a `SerialException` is thrown.

  Specified by:
    `setBinaryStream` in interface `Blob`
  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
    `SerialException` - if the SerialBlob in not instantiated with a `Blob` object that supports `setBinaryStream()`
  See Also:
    `getBinaryStream()`

### truncate

    public void truncate(long length)
                  throws SerialException

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

  Specified by:
    `truncate` in interface `Blob`
  Parameters:
    `length` - the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated
  Throws:
    `SerialException` - if there is an error accessing the Blob value; or the length to truncate is greater that the SerialBlob length

### getBinaryStream

    public InputStream getBinaryStream(long pos,
                                       long length)
                                throws SQLException

  Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.

  Specified by:
    `getBinaryStream` in interface `Blob`
  Parameters:
    `pos` - the offset to the first byte of the partial value to be retrieved. The first byte in the `Blob` is at position 1
    `length` - the length in bytes of the partial value to be retrieved
  Returns:
    `InputStream` through which the partial `Blob` value can be read.
  Throws:
    `SQLException` - if pos is less than 1 or if pos is greater than the number of bytes in the `Blob` or if pos + length is greater than the number of bytes in the `Blob`
  Since:
    1.6

### free

    public void free()
              throws SQLException

  This method frees the `Blob` object and releases the resources that it holds. `Blob` object. The object is invalid once the `free` method is called. If `free` is called multiple times, the subsequent calls to `free` are treated as a no-op.

  Specified by:
    `free` in interface `Blob`
  Throws:
    `SQLException` - if an error occurs releasing the Blob's resources
  Since:
    1.6

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
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 SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 1993, 2010, Oracle and/or its affiliates. All rights reserved.