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

com.sleepycat.collections

## Class StoredSortedMap<K,V>

- java.lang.Object
- - com.sleepycat.collections.StoredContainer
  - - com.sleepycat.collections.StoredMap<K,V>
    - - com.sleepycat.collections.StoredSortedMap<K,V>

- All Implemented Interfaces:
    Cloneable, ConcurrentMap<K,V>, Map<K,V>, SortedMap<K,V>

      public class StoredSortedMap<K,V>
      extends StoredMap<K,V>
      implements SortedMap<K,V>

  A SortedMap view of a `Database`.

  In addition to the standard SortedMap methods, this class provides the following methods for stored sorted maps only. Note that the use of these methods is not compatible with the standard Java collections interface.

  - `headMap(Object, boolean)`
  - `tailMap(Object, boolean)`
  - `subMap(Object, boolean, Object, boolean)`
  Author:
    Mark Hayes

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StoredSortedMap(Database database, EntryBinding<K> keyBinding, EntityBinding<V> valueEntityBinding, boolean writeAllowed)` Creates a sorted map entity view of a `Database`.
    `StoredSortedMap(Database database, EntryBinding<K> keyBinding, EntityBinding<V> valueEntityBinding, PrimaryKeyAssigner keyAssigner)` Creates a sorted map entity view of a `Database` with a `PrimaryKeyAssigner`.
    `StoredSortedMap(Database database, EntryBinding<K> keyBinding, EntryBinding<V> valueBinding, boolean writeAllowed)` Creates a sorted map view of a `Database`.
    `StoredSortedMap(Database database, EntryBinding<K> keyBinding, EntryBinding<V> valueBinding, PrimaryKeyAssigner keyAssigner)` Creates a sorted map view of a `Database` with a `PrimaryKeyAssigner`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Comparator<? super K>` | `comparator()` Returns null since comparators are not supported.
    `K` | `firstKey()` Returns the first (lowest) key currently in this sorted map.
    `SortedMap<K,V>` | `headMap(K toKey)` Returns a view of the portion of this sorted set whose keys are strictly less than toKey.
    `SortedMap<K,V>` | `headMap(K toKey, boolean toInclusive)` Returns a view of the portion of this sorted map whose elements are strictly less than toKey, optionally including toKey.
    `K` | `lastKey()` Returns the last (highest) element currently in this sorted map.
    `SortedMap<K,V>` | `subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)` Returns a view of the portion of this sorted map whose elements are strictly greater than fromKey and strictly less than toKey, optionally including fromKey and toKey.
    `SortedMap<K,V>` | `subMap(K fromKey, K toKey)` Returns a view of the portion of this sorted map whose elements range from fromKey, inclusive, to toKey, exclusive.
    `SortedMap<K,V>` | `tailMap(K fromKey)` Returns a view of the portion of this sorted map whose elements are greater than or equal to fromKey.
    `SortedMap<K,V>` | `tailMap(K fromKey, boolean fromInclusive)` Returns a view of the portion of this sorted map whose elements are strictly greater than fromKey, optionally including fromKey.

    - ### Methods inherited from class com.sleepycat.collections.StoredMap

      `append, containsKey, containsValue, duplicates, duplicatesMap, entrySet, equals, get, hashCode, keySet, put, putAll, putIfAbsent, remove, remove, replace, replace, size, toString, values`

    - ### Methods inherited from class com.sleepycat.collections.StoredContainer

      `areDuplicatesAllowed, areDuplicatesOrdered, areKeyRangesAllowed, areKeysRenumbered, clear, getCursorConfig, isEmpty, isOrdered, isSecondary, isTransactional, isWriteAllowed`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.SortedMap

      `entrySet, keySet, values`

    - ### Methods inherited from interface java.util.Map

      `clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size`

- - ### Constructor Detail

    - #### StoredSortedMap

          public StoredSortedMap(Database database,
                         EntryBinding<K> keyBinding,
                         EntryBinding<V> valueBinding,
                         boolean writeAllowed)

      Creates a sorted map view of a `Database`.
      Parameters:
        `database` - is the Database underlying the new collection.
        `keyBinding` - is the binding used to translate between key buffers and key objects.
        `valueBinding` - is the binding used to translate between value buffers and value objects.
        `writeAllowed` - is true to create a read-write collection or false to create a read-only collection.
      Throws:
        `IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### StoredSortedMap

          public StoredSortedMap(Database database,
                         EntryBinding<K> keyBinding,
                         EntryBinding<V> valueBinding,
                         PrimaryKeyAssigner keyAssigner)

      Creates a sorted map view of a `Database` with a `PrimaryKeyAssigner`. Writing is allowed for the created map.
      Parameters:
        `database` - is the Database underlying the new collection.
        `keyBinding` - is the binding used to translate between key buffers and key objects.
        `valueBinding` - is the binding used to translate between value buffers and value objects.
        `keyAssigner` - is used by the `StoredMap.append(V)` method to assign primary keys.
      Throws:
        `IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### StoredSortedMap

          public StoredSortedMap(Database database,
                         EntryBinding<K> keyBinding,
                         EntityBinding<V> valueEntityBinding,
                         boolean writeAllowed)

      Creates a sorted map entity view of a `Database`.
      Parameters:
        `database` - is the Database underlying the new collection.
        `keyBinding` - is the binding used to translate between key buffers and key objects.
        `valueEntityBinding` - is the binding used to translate between key/value buffers and entity value objects.
        `writeAllowed` - is true to create a read-write collection or false to create a read-only collection.
      Throws:
        `IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### StoredSortedMap

          public StoredSortedMap(Database database,
                         EntryBinding<K> keyBinding,
                         EntityBinding<V> valueEntityBinding,
                         PrimaryKeyAssigner keyAssigner)

      Creates a sorted map entity view of a `Database` with a `PrimaryKeyAssigner`. Writing is allowed for the created map.
      Parameters:
        `database` - is the Database underlying the new collection.
        `keyBinding` - is the binding used to translate between key buffers and key objects.
        `valueEntityBinding` - is the binding used to translate between key/value buffers and entity value objects.
        `keyAssigner` - is used by the `StoredMap.append(V)` method to assign primary keys.
      Throws:
        `IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

  - ### Method Detail

    - #### comparator

          public Comparator<? super K> comparator()

      Returns null since comparators are not supported. The natural ordering of a stored collection is data byte order, whether the data classes implement the `Comparable` interface or not. This method does not conform to the `SortedMap.comparator()` interface.
      Specified by:
        `comparator` in interface `SortedMap<K,V>`
      Returns:
        null.

    - #### firstKey

          public K firstKey()

      Returns the first (lowest) key currently in this sorted map. This method conforms to the `SortedMap.firstKey()` interface.
      Specified by:
        `firstKey` in interface `SortedMap<K,V>`
      Returns:
        the first key.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### lastKey

          public K lastKey()

      Returns the last (highest) element currently in this sorted map. This method conforms to the `SortedMap.lastKey()` interface.
      Specified by:
        `lastKey` in interface `SortedMap<K,V>`
      Returns:
        the last key.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### headMap

          public SortedMap<K,V> headMap(K toKey)

      Returns a view of the portion of this sorted set whose keys are strictly less than toKey. This method conforms to the `SortedMap.headMap(K)` interface.

      Note that the return value is a StoredStoredMap and must be treated as such; for example, its iterators must be explicitly closed.

      Specified by:
        `headMap` in interface `SortedMap<K,V>`
      Parameters:
        `toKey` - is the upper bound.
      Returns:
        the submap.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### headMap

          public SortedMap<K,V> headMap(K toKey,
                               boolean toInclusive)

      Returns a view of the portion of this sorted map whose elements are strictly less than toKey, optionally including toKey. This method does not exist in the standard `SortedMap` interface.

      Note that the return value is a StoredStoredMap and must be treated as such; for example, its iterators must be explicitly closed.

      Parameters:
        `toKey` - is the upper bound.
        `toInclusive` - is true to include toKey.
      Returns:
        the submap.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### tailMap

          public SortedMap<K,V> tailMap(K fromKey)

      Returns a view of the portion of this sorted map whose elements are greater than or equal to fromKey. This method conforms to the `SortedMap.tailMap(K)` interface.

      Note that the return value is a StoredStoredMap and must be treated as such; for example, its iterators must be explicitly closed.

      Specified by:
        `tailMap` in interface `SortedMap<K,V>`
      Parameters:
        `fromKey` - is the lower bound.
      Returns:
        the submap.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### tailMap

          public SortedMap<K,V> tailMap(K fromKey,
                               boolean fromInclusive)

      Returns a view of the portion of this sorted map whose elements are strictly greater than fromKey, optionally including fromKey. This method does not exist in the standard `SortedMap` interface.

      Note that the return value is a StoredStoredMap and must be treated as such; for example, its iterators must be explicitly closed.

      Parameters:
        `fromKey` - is the lower bound.
        `fromInclusive` - is true to include fromKey.
      Returns:
        the submap.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### subMap

          public SortedMap<K,V> subMap(K fromKey,
                              K toKey)

      Returns a view of the portion of this sorted map whose elements range from fromKey, inclusive, to toKey, exclusive. This method conforms to the `SortedMap.subMap(K, K)` interface.

      Note that the return value is a StoredStoredMap and must be treated as such; for example, its iterators must be explicitly closed.

      Specified by:
        `subMap` in interface `SortedMap<K,V>`
      Parameters:
        `fromKey` - is the lower bound.
        `toKey` - is the upper bound.
      Returns:
        the submap.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

    - #### subMap

          public SortedMap<K,V> subMap(K fromKey,
                              boolean fromInclusive,
                              K toKey,
                              boolean toInclusive)

      Returns a view of the portion of this sorted map whose elements are strictly greater than fromKey and strictly less than toKey, optionally including fromKey and toKey. This method does not exist in the standard `SortedMap` interface.

      Note that the return value is a StoredStoredMap and must be treated as such; for example, its iterators must be explicitly closed.

      Parameters:
        `fromKey` - is the lower bound.
        `fromInclusive` - is true to include fromKey.
        `toKey` - is the upper bound.
        `toInclusive` - is true to include toKey.
      Returns:
        the submap.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C edition).

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