DatabaseStream (Oracle - Berkeley DB Java API)
Date: 2017-04-13

com.sleepycat.db

## Class DatabaseStream

- java.lang.Object
- - com.sleepycat.db.DatabaseStream

-     public class DatabaseStream
      extends java.lang.Object

  A database stream. The database stream is used to access external files.

  Once the database stream close method has been called, the handle may not be accessed again.

  To obtain a database stream with default attributes:

  >         DatabaseStream dbs = myCursor.openDatabaseStream(null);

  To customize the attributes of a database stream, use a DatabaseStreamConfig object.

  >         DatabaseStreamConfig config = new DatabaseStreamConfig();
  >         config.setReadOnly(true);
  >         DatabaseStream dbs = myCursor.openDatabaseStream(config);

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DatabaseStream(Cursor cursor, DatabaseStreamConfig config)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Discard the database stream.
    `DatabaseStreamConfig` | `getConfig()` Return this database stream configuration.
    `Cursor` | `getCursor()` Return the `Cursor` handle associated with this database stream.
    `OperationStatus` | `read(DatabaseEntry data, long offset, int size)` Read from the external file accessed by this database stream.
    `long` | `size()` Return the size in bytes of the external file accessed by the database stream.
    `OperationStatus` | `write(DatabaseEntry data, long offset)` Write to the external file accessed by the database stream.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DatabaseStream

          protected DatabaseStream(Cursor cursor,
                                   DatabaseStreamConfig config)

  - ### Method Detail

    - #### close

          public void close()
                     throws DatabaseException

      Discard the database stream.

      After the close method has been called, you cannot use the database stream handle again.

      It is recommended to always close all database stream handles immediately after their use to release resources.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### getConfig

          public DatabaseStreamConfig getConfig()

      Return this database stream configuration.

      Returns:
        This database stream configuration.

    - #### getCursor

          public Cursor getCursor()

      Return the `Cursor` handle associated with this database stream.

      Returns:
        The cursor handle associated with this database stream.

    - #### read

          public OperationStatus read(DatabaseEntry data,
                                      long offset,
                                      int size)
                               throws DatabaseException,
                                      java.lang.IllegalArgumentException

      Read from the external file accessed by this database stream.

      Parameters:
        `data` - the data read from the file returned as output. Its byte array does not need to be initialized by the caller.

        `offset` - the position in bytes in the file where the reading starts.

        `size` - the number of bytes to read.

      Returns:
        `OperationStatus.SUCCESS` if the operation succeeds.

      Throws:
        `java.lang.IllegalArgumentException` - if a failure occurs.

        `java.lang.IllegalArgumentException` - if the operation fails.

        `DatabaseException` - if a failure occurs.

    - #### size

          public long size()
                    throws DatabaseException

      Return the size in bytes of the external file accessed by the database stream.

      Returns:
        The size in bytes of the file accessed by the database stream.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### write

          public OperationStatus write(DatabaseEntry data,
                                       long offset)
                                throws DatabaseException,
                                       java.lang.IllegalArgumentException

      Write to the external file accessed by the database stream.

      Parameters:
        `data` - the data `DatabaseEntry` to write into the file.

        `offset` - the position in bytes in the file where the writing starts.

      Returns:
        `OperationStatus.SUCCESS` if the operation succeeds.

      Throws:
        `java.lang.IllegalArgumentException` - if the operation fails.

        `DatabaseException` - if a failure occurs.

Copyright (c) 1996, 2017 Oracle and/or its affiliates. All rights reserved.