Sequence (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.je

## Class Sequence

- java.lang.Object
- - com.sleepycat.je.Sequence

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class Sequence
      extends Object
      implements Closeable

  A Sequence handle is used to manipulate a sequence record in a database. Sequence handles are opened using the `Database.openSequence` method.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes a sequence.
    `long` | `get(Transaction txn, int delta)` Returns the next available element in the sequence and changes the sequence value by `delta`.
    `Database` | `getDatabase()` Returns the Database handle associated with this sequence.
    `DatabaseEntry` | `getKey()` Returns the DatabaseEntry used to open this sequence.
    `SequenceStats` | `getStats(StatsConfig config)` Returns statistical information about the sequence.

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

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

- - ### Method Detail

    - #### close

          public void close()
                     throws DatabaseException

      Closes a sequence. Any unused cached values are lost.

      The sequence handle may not be used again after this method has been called, regardless of the method's success or failure.

      WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `DatabaseException`

    - #### get

          public long get(Transaction txn,
                 int delta)
                   throws DatabaseException

      Returns the next available element in the sequence and changes the sequence value by `delta`. The value of `delta` must be greater than zero. If there are enough cached values in the sequence handle then they will be returned. Otherwise the next value will be fetched from the database and incremented (decremented) by enough to cover the `delta` and the next batch of cached values. This method is synchronized to protect updating of the cached value, since multiple threads may share a single handle. Multiple handles for the same database/key may be used to increase concurrency.

      The `txn` handle must be null if the sequence handle was opened with a non-zero cache size.

      For maximum concurrency, a non-zero cache size should be specified prior to opening the sequence handle, the `txn` handle should be `null`, and `SequenceConfig.setAutoCommitNoSync` should be called to disable log flushes.

      Parameters:
        `txn` - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified.
        `delta` - the amount by which to increment or decrement the sequence
      Returns:
        the next available element in the sequence
      Throws:
        `SequenceOverflowException` - if the end of the sequence is reached and wrapping is not configured.
        `SequenceIntegrityException` - if the sequence record has been deleted.
        `OperationFailureException` - if one of the Write Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalArgumentException` - if the delta is less than or equal to zero, or larger than the size of the sequence's range.
        `DatabaseException`

    - #### getDatabase

          public Database getDatabase()

      Returns the Database handle associated with this sequence.
      Returns:
        The Database handle associated with this sequence.

    - #### getKey

          public DatabaseEntry getKey()

      Returns the DatabaseEntry used to open this sequence.
      Returns:
        The DatabaseEntry used to open this sequence.

    - #### getStats

          public SequenceStats getStats(StatsConfig config)
                                 throws DatabaseException

      Returns statistical information about the sequence.

      In the presence of multiple threads or processes accessing an active sequence, the information returned by this method may be out-of-date.

      The getStats method cannot be transaction-protected. For this reason, it should be called in a thread of control that has no open cursors or active transactions.

      Parameters:
        `config` - The statistics returned; if null, default statistics are returned.
      Returns:
        Sequence statistics.
      Throws:
        `SequenceIntegrityException` - if the sequence record has been deleted.
        `DatabaseException`

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.