lang/java/src/com/sleepycat/collections/StoredSortedMap.java

   1 /*-
   2  * See the file LICENSE for redistribution information.
   3  *
   4  * Copyright (c) 2000, 2012 Oracle and/or its affiliates.  All rights reserved.
   5  *
   6  */
   7
   8 package com.sleepycat.collections;
   9
  10 import java.util.Comparator;
  11 import java.util.SortedMap;
  12
  13 import com.sleepycat.bind.EntityBinding;
  14 import com.sleepycat.bind.EntryBinding;
  15 import com.sleepycat.db.Database;
  16 import com.sleepycat.db.OperationStatus;
  17 import com.sleepycat.util.RuntimeExceptionWrapper;
  18
  19 /**
  20  * A SortedMap view of a {@link Database}.
  21  *
  22  * <p>In addition to the standard SortedMap methods, this class provides the
  23  * following methods for stored sorted maps only.  Note that the use of these
  24  * methods is not compatible with the standard Java collections interface.</p>
  25  * <ul>
  26  * <li>{@link #headMap(Object, boolean)}</li>
  27  * <li>{@link #tailMap(Object, boolean)}</li>
  28  * <li>{@link #subMap(Object, boolean, Object, boolean)}</li>
  29  * </ul>
  30  *
  31  * @author Mark Hayes
  32  */
  33 public class StoredSortedMap<K, V>
  34     extends StoredMap<K, V>
  35     implements SortedMap<K, V> {
  36
  37     /**
  38      * Creates a sorted map view of a {@link Database}.
  39      *
  40      * @param database is the Database underlying the new collection.
  41      *
  42      * @param keyBinding is the binding used to translate between key buffers
  43      * and key objects.
  44      *
  45      * @param valueBinding is the binding used to translate between value
  46      * buffers and value objects.
  47      *
  48      * @param writeAllowed is true to create a read-write collection or false
  49      * to create a read-only collection.
  50      *
  51      * @throws IllegalArgumentException if formats are not consistently
  52      * defined or a parameter is invalid.
  53      *
  54      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
  55      * including a {@code DatabaseException} on BDB (C edition).
  56      */
  57     public StoredSortedMap(Database database,
  58                            EntryBinding<K> keyBinding,
  59                            EntryBinding<V> valueBinding,
  60                            boolean writeAllowed) {
  61
  62         super(new DataView(database, keyBinding, valueBinding, null,
  63                            writeAllowed, null));
  64     }
  65
  66     /**
  67      * Creates a sorted map view of a {@link Database} with a {@link
  68      * PrimaryKeyAssigner}.  Writing is allowed for the created map.
  69      *
  70      * @param database is the Database underlying the new collection.
  71      *
  72      * @param keyBinding is the binding used to translate between key buffers
  73      * and key objects.
  74      *
  75      * @param valueBinding is the binding used to translate between value
  76      * buffers and value objects.
  77      *
  78      * @param keyAssigner is used by the {@link #append} method to assign
  79      * primary keys.
  80      *
  81      * @throws IllegalArgumentException if formats are not consistently
  82      * defined or a parameter is invalid.
  83      *
  84      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
  85      * including a {@code DatabaseException} on BDB (C edition).
  86      */
  87     public StoredSortedMap(Database database,
  88                            EntryBinding<K> keyBinding,
  89                            EntryBinding<V> valueBinding,
  90                            PrimaryKeyAssigner keyAssigner) {
  91
  92         super(new DataView(database, keyBinding, valueBinding, null,
  93                            true, keyAssigner));
  94     }
  95
  96     /**
  97      * Creates a sorted map entity view of a {@link Database}.
  98      *
  99      * @param database is the Database underlying the new collection.
 100      *
 101      * @param keyBinding is the binding used to translate between key buffers
 102      * and key objects.
 103      *
 104      * @param valueEntityBinding is the binding used to translate between
 105      * key/value buffers and entity value objects.
 106      *
 107      * @param writeAllowed is true to create a read-write collection or false
 108      * to create a read-only collection.
 109      *
 110      * @throws IllegalArgumentException if formats are not consistently
 111      * defined or a parameter is invalid.
 112      *
 113      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 114      * including a {@code DatabaseException} on BDB (C edition).
 115      */
 116     public StoredSortedMap(Database database,
 117                            EntryBinding<K> keyBinding,
 118                            EntityBinding<V> valueEntityBinding,
 119                            boolean writeAllowed) {
 120
 121         super(new DataView(database, keyBinding, null, valueEntityBinding,
 122                            writeAllowed, null));
 123     }
 124
 125     /**
 126      * Creates a sorted map entity view of a {@link Database} with a {@link
 127      * PrimaryKeyAssigner}.  Writing is allowed for the created map.
 128      *
 129      * @param database is the Database underlying the new collection.
 130      *
 131      * @param keyBinding is the binding used to translate between key buffers
 132      * and key objects.
 133      *
 134      * @param valueEntityBinding is the binding used to translate between
 135      * key/value buffers and entity value objects.
 136      *
 137      * @param keyAssigner is used by the {@link #append} method to assign
 138      * primary keys.
 139      *
 140      * @throws IllegalArgumentException if formats are not consistently
 141      * defined or a parameter is invalid.
 142      *
 143      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 144      * including a {@code DatabaseException} on BDB (C edition).
 145      */
 146     public StoredSortedMap(Database database,
 147                            EntryBinding<K> keyBinding,
 148                            EntityBinding<V> valueEntityBinding,
 149                            PrimaryKeyAssigner keyAssigner) {
 150
 151         super(new DataView(database, keyBinding, null, valueEntityBinding,
 152                            true, keyAssigner));
 153     }
 154
 155     StoredSortedMap(DataView mapView) {
 156
 157         super(mapView);
 158     }
 159
 160     /**
 161      * Returns null since comparators are not supported.  The natural ordering
 162      * of a stored collection is data byte order, whether the data classes
 163      * implement the {@link java.lang.Comparable} interface or not.
 164      * This method does not conform to the {@link SortedMap#comparator}
 165      * interface.
 166      *
 167      * @return null.
 168      */
 169     public Comparator<? super K> comparator() {
 170
 171         return null;
 172     }
 173
 174     /**
 175      * Returns the first (lowest) key currently in this sorted map.
 176      * This method conforms to the {@link SortedMap#firstKey} interface.
 177      *
 178      * @return the first key.
 179      *
 180      *
 181      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 182      * including a {@code DatabaseException} on BDB (C edition).
 183      */
 184     public K firstKey() {
 185
 186         return getFirstOrLastKey(true);
 187     }
 188
 189     /**
 190      * Returns the last (highest) element currently in this sorted map.
 191      * This method conforms to the {@link SortedMap#lastKey} interface.
 192      *
 193      * @return the last key.
 194      *
 195      *
 196      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 197      * including a {@code DatabaseException} on BDB (C edition).
 198      */
 199     public K lastKey() {
 200
 201         return getFirstOrLastKey(false);
 202     }
 203
 204     private K getFirstOrLastKey(boolean doGetFirst) {
 205
 206         DataCursor cursor = null;
 207         try {
 208             cursor = new DataCursor(view, false);
 209             OperationStatus status;
 210             if (doGetFirst) {
 211                 status = cursor.getFirst(false);
 212             } else {
 213                 status = cursor.getLast(false);
 214             }
 215             return (K) ((status == OperationStatus.SUCCESS) ?
 216                 cursor.getCurrentKey() :
 217                 null);
 218         } catch (Exception e) {
 219             throw StoredContainer.convertException(e);
 220         } finally {
 221             closeCursor(cursor);
 222         }
 223     }
 224
 225     /**
 226      * Returns a view of the portion of this sorted set whose keys are
 227      * strictly less than toKey.
 228      * This method conforms to the {@link SortedMap#headMap} interface.
 229      *
 230      * <p>Note that the return value is a StoredStoredMap and must be treated
 231      * as such; for example, its iterators must be explicitly closed.</p>
 232      *
 233      * @param toKey is the upper bound.
 234      *
 235      * @return the submap.
 236      *
 237      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 238      * including a {@code DatabaseException} on BDB (C edition).
 239      */
 240     public SortedMap<K, V> headMap(K toKey) {
 241
 242         return subMap(null, false, toKey, false);
 243     }
 244
 245     /**
 246      * Returns a view of the portion of this sorted map whose elements are
 247      * strictly less than toKey, optionally including toKey.
 248      * This method does not exist in the standard {@link SortedMap} interface.
 249      *
 250      * <p>Note that the return value is a StoredStoredMap and must be treated
 251      * as such; for example, its iterators must be explicitly closed.</p>
 252      *
 253      * @param toKey is the upper bound.
 254      *
 255      * @param toInclusive is true to include toKey.
 256      *
 257      * @return the submap.
 258      *
 259      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 260      * including a {@code DatabaseException} on BDB (C edition).
 261      */
 262     public SortedMap<K, V> headMap(K toKey, boolean toInclusive) {
 263
 264         return subMap(null, false, toKey, toInclusive);
 265     }
 266
 267     /**
 268      * Returns a view of the portion of this sorted map whose elements are
 269      * greater than or equal to fromKey.
 270      * This method conforms to the {@link SortedMap#tailMap} interface.
 271      *
 272      * <p>Note that the return value is a StoredStoredMap and must be treated
 273      * as such; for example, its iterators must be explicitly closed.</p>
 274      *
 275      * @param fromKey is the lower bound.
 276      *
 277      * @return the submap.
 278      *
 279      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 280      * including a {@code DatabaseException} on BDB (C edition).
 281      */
 282     public SortedMap<K, V> tailMap(K fromKey) {
 283
 284         return subMap(fromKey, true, null, false);
 285     }
 286
 287     /**
 288      * Returns a view of the portion of this sorted map whose elements are
 289      * strictly greater than fromKey, optionally including fromKey.
 290      * This method does not exist in the standard {@link SortedMap} interface.
 291      *
 292      * <p>Note that the return value is a StoredStoredMap and must be treated
 293      * as such; for example, its iterators must be explicitly closed.</p>
 294      *
 295      * @param fromKey is the lower bound.
 296      *
 297      * @param fromInclusive is true to include fromKey.
 298      *
 299      * @return the submap.
 300      *
 301      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 302      * including a {@code DatabaseException} on BDB (C edition).
 303      */
 304     public SortedMap<K, V> tailMap(K fromKey, boolean fromInclusive) {
 305
 306         return subMap(fromKey, fromInclusive, null, false);
 307     }
 308
 309     /**
 310      * Returns a view of the portion of this sorted map whose elements range
 311      * from fromKey, inclusive, to toKey, exclusive.
 312      * This method conforms to the {@link SortedMap#subMap} interface.
 313      *
 314      * <p>Note that the return value is a StoredStoredMap and must be treated
 315      * as such; for example, its iterators must be explicitly closed.</p>
 316      *
 317      * @param fromKey is the lower bound.
 318      *
 319      * @param toKey is the upper bound.
 320      *
 321      * @return the submap.
 322      *
 323      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 324      * including a {@code DatabaseException} on BDB (C edition).
 325      */
 326     public SortedMap<K, V> subMap(K fromKey, K toKey) {
 327
 328         return subMap(fromKey, true, toKey, false);
 329     }
 330
 331     /**
 332      * Returns a view of the portion of this sorted map whose elements are
 333      * strictly greater than fromKey and strictly less than toKey,
 334      * optionally including fromKey and toKey.
 335      * This method does not exist in the standard {@link SortedMap} interface.
 336      *
 337      * <p>Note that the return value is a StoredStoredMap and must be treated
 338      * as such; for example, its iterators must be explicitly closed.</p>
 339      *
 340      * @param fromKey is the lower bound.
 341      *
 342      * @param fromInclusive is true to include fromKey.
 343      *
 344      * @param toKey is the upper bound.
 345      *
 346      * @param toInclusive is true to include toKey.
 347      *
 348      * @return the submap.
 349      *
 350      * @throws RuntimeExceptionWrapper if a checked exception is thrown,
 351      * including a {@code DatabaseException} on BDB (C edition).
 352      */
 353     public SortedMap<K, V> subMap(K fromKey,
 354                                   boolean fromInclusive,
 355                                   K toKey,
 356                                   boolean toInclusive) {
 357         try {
 358             return new StoredSortedMap(
 359                view.subView(fromKey, fromInclusive, toKey, toInclusive, null));
 360         } catch (Exception e) {
 361             throw StoredContainer.convertException(e);
 362         }
 363     }
 364 }