1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
5 *
6 * $Id: StoredSortedKeySet.java,v 12.8 2008/01/08 20:58:36 bostic Exp $
7 */
8
9package com.sleepycat.collections;
10
11import java.util.Comparator;
12import java.util.SortedSet;
13
14import com.sleepycat.bind.EntryBinding;
15import com.sleepycat.db.Database;
16
17/**
18 * The SortedSet returned by Map.keySet() and which can also be constructed
19 * directly if a Map is not needed.
20 * Since this collection is a set it only contains one element for each key,
21 * even when duplicates are allowed.  Key set iterators are therefore
22 * particularly useful for enumerating the unique keys of a store or index that
23 * allows duplicates.
24 *
25 * <p>In addition to the standard SortedSet methods, this class provides the
26 * following methods for stored sorted sets only.  Note that the use of these
27 * methods is not compatible with the standard Java collections interface.</p>
28 * <ul>
29 * <li>{@link #headSet(Object, boolean)}</li>
30 * <li>{@link #tailSet(Object, boolean)}</li>
31 * <li>{@link #subSet(Object, boolean, Object, boolean)}</li>
32 * </ul>
33 *
34 * @author Mark Hayes
35 */
36public class StoredSortedKeySet extends StoredKeySet implements SortedSet {
37
38    /**
39     * Creates a sorted key set view of a {@link Database}.
40     *
41     * @param database is the Database underlying the new collection.
42     *
43     * @param keyBinding is the binding used to translate between key buffers
44     * and key objects.
45     *
46     * @param writeAllowed is true to create a read-write collection or false
47     * to create a read-only collection.
48     *
49     * @throws IllegalArgumentException if formats are not consistently
50     * defined or a parameter is invalid.
51     *
52     * @throws RuntimeExceptionWrapper if a {@link
53     * com.sleepycat.db.DatabaseException} is thrown.
54     */
55    public StoredSortedKeySet(Database database, EntryBinding keyBinding,
56                              boolean writeAllowed) {
57
58        super(new DataView(database, keyBinding, null, null,
59                           writeAllowed, null));
60    }
61
62    StoredSortedKeySet(DataView keySetView) {
63
64        super(keySetView);
65    }
66
67    /**
68     * Returns null since comparators are not supported.  The natural ordering
69     * of a stored collection is data byte order, whether the data classes
70     * implement the {@link java.lang.Comparable} interface or not.
71     * This method does not conform to the {@link SortedSet#comparator}
72     * interface.
73     *
74     * @return null.
75     */
76    public Comparator comparator() {
77
78        return null;
79    }
80
81    /**
82     * Returns the first (lowest) element currently in this sorted set.
83     * This method conforms to the {@link SortedSet#first} interface.
84     *
85     * @return the first element.
86     *
87     * @throws RuntimeExceptionWrapper if a {@link
88     * com.sleepycat.db.DatabaseException} is thrown.
89     */
90    public Object first() {
91
92        return getFirstOrLast(true);
93    }
94
95    /**
96     * Returns the last (highest) element currently in this sorted set.
97     * This method conforms to the {@link SortedSet#last} interface.
98     *
99     * @return the last element.
100     *
101     * @throws RuntimeExceptionWrapper if a {@link
102     * com.sleepycat.db.DatabaseException} is thrown.
103     */
104    public Object last() {
105
106        return getFirstOrLast(false);
107    }
108
109    /**
110     * Returns a view of the portion of this sorted set whose elements are
111     * strictly less than toKey.
112     * This method conforms to the {@link SortedSet#headSet} interface.
113     *
114     * <p>Note that the return value is a StoredCollection and must be treated
115     * as such; for example, its iterators must be explicitly closed.</p>
116     *
117     * @param toKey is the upper bound.
118     *
119     * @return the subset.
120     *
121     * @throws RuntimeExceptionWrapper if a {@link
122     * com.sleepycat.db.DatabaseException} is thrown.
123     */
124    public SortedSet headSet(Object toKey) {
125
126        return subSet(null, false, toKey, false);
127    }
128
129    /**
130     * Returns a view of the portion of this sorted set whose elements are
131     * strictly less than toKey, optionally including toKey.
132     * This method does not exist in the standard {@link SortedSet} interface.
133     *
134     * <p>Note that the return value is a StoredCollection and must be treated
135     * as such; for example, its iterators must be explicitly closed.</p>
136     *
137     * @param toKey is the upper bound.
138     *
139     * @param toInclusive is true to include toKey.
140     *
141     * @return the subset.
142     *
143     * @throws RuntimeExceptionWrapper if a {@link
144     * com.sleepycat.db.DatabaseException} is thrown.
145     */
146    public SortedSet headSet(Object toKey, boolean toInclusive) {
147
148        return subSet(null, false, toKey, toInclusive);
149    }
150
151    /**
152     * Returns a view of the portion of this sorted set whose elements are
153     * greater than or equal to fromKey.
154     * This method conforms to the {@link SortedSet#tailSet} interface.
155     *
156     * <p>Note that the return value is a StoredCollection and must be treated
157     * as such; for example, its iterators must be explicitly closed.</p>
158     *
159     * @param fromKey is the lower bound.
160     *
161     * @return the subset.
162     *
163     * @throws RuntimeExceptionWrapper if a {@link
164     * com.sleepycat.db.DatabaseException} is thrown.
165     */
166    public SortedSet tailSet(Object fromKey) {
167
168        return subSet(fromKey, true, null, false);
169    }
170
171    /**
172     * Returns a view of the portion of this sorted set whose elements are
173     * strictly greater than fromKey, optionally including fromKey.
174     * This method does not exist in the standard {@link SortedSet} interface.
175     *
176     * <p>Note that the return value is a StoredCollection and must be treated
177     * as such; for example, its iterators must be explicitly closed.</p>
178     *
179     * @param fromKey is the lower bound.
180     *
181     * @param fromInclusive is true to include fromKey.
182     *
183     * @return the subset.
184     *
185     * @throws RuntimeExceptionWrapper if a {@link
186     * com.sleepycat.db.DatabaseException} is thrown.
187     */
188    public SortedSet tailSet(Object fromKey, boolean fromInclusive) {
189
190        return subSet(fromKey, fromInclusive, null, false);
191    }
192
193    /**
194     * Returns a view of the portion of this sorted set whose elements range
195     * from fromKey, inclusive, to toKey, exclusive.
196     * This method conforms to the {@link SortedSet#subSet} interface.
197     *
198     * <p>Note that the return value is a StoredCollection and must be treated
199     * as such; for example, its iterators must be explicitly closed.</p>
200     *
201     * @param fromKey is the lower bound.
202     *
203     * @param toKey is the upper bound.
204     *
205     * @return the subset.
206     *
207     * @throws RuntimeExceptionWrapper if a {@link
208     * com.sleepycat.db.DatabaseException} is thrown.
209     */
210    public SortedSet subSet(Object fromKey, Object toKey) {
211
212        return subSet(fromKey, true, toKey, false);
213    }
214
215    /**
216     * Returns a view of the portion of this sorted set whose elements are
217     * strictly greater than fromKey and strictly less than toKey,
218     * optionally including fromKey and toKey.
219     * This method does not exist in the standard {@link SortedSet} interface.
220     *
221     * <p>Note that the return value is a StoredCollection and must be treated
222     * as such; for example, its iterators must be explicitly closed.</p>
223     *
224     * @param fromKey is the lower bound.
225     *
226     * @param fromInclusive is true to include fromKey.
227     *
228     * @param toKey is the upper bound.
229     *
230     * @param toInclusive is true to include toKey.
231     *
232     * @return the subset.
233     *
234     * @throws RuntimeExceptionWrapper if a {@link
235     * com.sleepycat.db.DatabaseException} is thrown.
236     */
237    public SortedSet subSet(Object fromKey, boolean fromInclusive,
238                            Object toKey, boolean toInclusive) {
239
240        try {
241            return new StoredSortedKeySet(
242               view.subView(fromKey, fromInclusive, toKey, toInclusive, null));
243        } catch (Exception e) {
244            throw StoredContainer.convertException(e);
245        }
246    }
247}
248