1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
5 *
6 * $Id: StoredCollections.java,v 12.7 2008/01/08 20:58:36 bostic Exp $
7 */
8
9package com.sleepycat.collections;
10
11import java.util.Collection;
12import java.util.Iterator;
13import java.util.List;
14import java.util.Map;
15import java.util.Set;
16import java.util.SortedMap;
17import java.util.SortedSet;
18
19import com.sleepycat.db.CursorConfig;
20
21/**
22 * Static methods operating on collections and maps.
23 *
24 * <p>This class consists exclusively of static methods that operate on or
25 * return stored collections and maps, jointly called containers. It contains
26 * methods for changing certain properties of a container.  Because container
27 * properties are immutable, these methods always return a new container
28 * instance.  This allows stored container instances to be used safely by
29 * multiple threads.  Creating the new container instance is not expensive and
30 * creates only two new objects.</p>
31 *
32 * <p>When a container is created with a particular property, all containers
33 * and iterators derived from that container will inherit the property.  For
34 * example, if a read-uncommitted Map is created then calls to its subMap(),
35 * values(), entrySet(), and keySet() methods will create read-uncommitted
36 * containers also.</p>
37 *
38 * <p>Method names beginning with "configured" create a new container with a
39 * specified {@link CursorConfig} from a given stored container.  This allows
40 * configuring a container for read-committed isolation, read-uncommitted
41 * isolation, or any other property supported by <code>CursorConfig</code>.
42 * All operations performed with the resulting container will be performed with
43 * the specified cursor configuration.</p>
44 */
45public class StoredCollections {
46
47    private StoredCollections() {}
48
49    /**
50     * Creates a configured collection from a given stored collection.
51     *
52     * @param storedCollection the base collection.
53     *
54     * @param config is the cursor configuration to be used for all operations
55     * performed via the new collection instance; null may be specified to use
56     * the default configuration.
57     *
58     * @return the configured collection.
59     *
60     * @throws ClassCastException if the given container is not a
61     * StoredContainer.
62     */
63    public static Collection configuredCollection(Collection storedCollection,
64                                                  CursorConfig config) {
65
66        return (Collection)
67            ((StoredContainer) storedCollection).configuredClone(config);
68    }
69
70    /**
71     * Creates a configured list from a given stored list.
72     *
73     * <p>Note that this method may not be called in the JE product, since the
74     * StoredList class is not supported.</p>
75     *
76     * @param storedList the base list.
77     *
78     * @param config is the cursor configuration to be used for all operations
79     * performed via the new list instance; null may be specified to use the
80     * default configuration.
81     *
82     * @return the configured list.
83     *
84     * @throws ClassCastException if the given container is not a
85     * StoredContainer.
86     */
87    public static List configuredList(List storedList, CursorConfig config) {
88
89        return (List) ((StoredContainer) storedList).configuredClone(config);
90    }
91
92    /**
93     * Creates a configured map from a given stored map.
94     *
95     * @param storedMap the base map.
96     *
97     * @param config is the cursor configuration to be used for all operations
98     * performed via the new map instance; null may be specified to use the
99     * default configuration.
100     *
101     * @return the configured map.
102     *
103     * @throws ClassCastException if the given container is not a
104     * StoredContainer.
105     */
106    public static Map configuredMap(Map storedMap, CursorConfig config) {
107
108        return (Map) ((StoredContainer) storedMap).configuredClone(config);
109    }
110
111    /**
112     * Creates a configured set from a given stored set.
113     *
114     * @param storedSet the base set.
115     *
116     * @param config is the cursor configuration to be used for all operations
117     * performed via the new set instance; null may be specified to use the
118     * default configuration.
119     *
120     * @return the configured set.
121     *
122     * @throws ClassCastException if the given container is not a
123     * StoredContainer.
124     */
125    public static Set configuredSet(Set storedSet, CursorConfig config) {
126
127        return (Set) ((StoredContainer) storedSet).configuredClone(config);
128    }
129
130    /**
131     * Creates a configured sorted map from a given stored sorted map.
132     *
133     * @param storedSortedMap the base map.
134     *
135     * @param config is the cursor configuration to be used for all operations
136     * performed via the new map instance; null may be specified to use the
137     * default configuration.
138     *
139     * @return the configured map.
140     *
141     * @throws ClassCastException if the given container is not a
142     * StoredContainer.
143     */
144    public static SortedMap configuredSortedMap(SortedMap storedSortedMap,
145                                                CursorConfig config) {
146
147        return (SortedMap)
148            ((StoredContainer) storedSortedMap).configuredClone(config);
149    }
150
151    /**
152     * Creates a configured sorted set from a given stored sorted set.
153     *
154     * @param storedSortedSet the base set.
155     *
156     * @param config is the cursor configuration to be used for all operations
157     * performed via the new set instance; null may be specified to use the
158     * default configuration.
159     *
160     * @return the configured set.
161     *
162     * @throws ClassCastException if the given container is not a
163     * StoredContainer.
164     */
165    public static SortedSet configuredSortedSet(SortedSet storedSortedSet,
166                                                CursorConfig config) {
167
168        return (SortedSet)
169            ((StoredContainer) storedSortedSet).configuredClone(config);
170    }
171
172    /**
173     * @deprecated This method has been replaced by {@link
174     * #configuredCollection} in order to conform to ANSI database isolation
175     * terminology.  To obtain a dirty-read collection, pass
176     * <code>CursorConfig.READ_UNCOMMITTED</code>
177     */
178    public static Collection dirtyReadCollection(Collection storedCollection) {
179
180        /* We can't use READ_UNCOMMITTED until is is added to DB core. */
181        return configuredCollection
182            (storedCollection, CursorConfig.DIRTY_READ);
183    }
184
185    /**
186     * @deprecated This method has been replaced by {@link #configuredList} in
187     * order to conform to ANSI database isolation terminology.  To obtain a
188     * dirty-read list, pass <code>CursorConfig.READ_UNCOMMITTED</code>
189     */
190    public static List dirtyReadList(List storedList) {
191
192        /* We can't use READ_UNCOMMITTED until is is added to DB core. */
193        return configuredList(storedList, CursorConfig.DIRTY_READ);
194    }
195
196    /**
197     * @deprecated This method has been replaced by {@link #configuredMap} in
198     * order to conform to ANSI database isolation terminology.  To obtain a
199     * dirty-read map, pass <code>CursorConfig.READ_UNCOMMITTED</code>
200     */
201    public static Map dirtyReadMap(Map storedMap) {
202
203        /* We can't use READ_UNCOMMITTED until is is added to DB core. */
204        return configuredMap(storedMap, CursorConfig.DIRTY_READ);
205    }
206
207    /**
208     * @deprecated This method has been replaced by {@link #configuredSet} in
209     * order to conform to ANSI database isolation terminology.  To obtain a
210     * dirty-read set, pass <code>CursorConfig.READ_UNCOMMITTED</code>
211     */
212    public static Set dirtyReadSet(Set storedSet) {
213
214        /* We can't use READ_UNCOMMITTED until is is added to DB core. */
215        return configuredSet(storedSet, CursorConfig.DIRTY_READ);
216    }
217
218    /**
219     * @deprecated This method has been replaced by {@link
220     * #configuredSortedMap} in order to conform to ANSI database isolation
221     * terminology.  To obtain a dirty-read map, pass
222     * <code>CursorConfig.READ_UNCOMMITTED</code>
223     */
224    public static SortedMap dirtyReadSortedMap(SortedMap storedSortedMap) {
225
226        /* We can't use READ_UNCOMMITTED until is is added to DB core. */
227        return configuredSortedMap
228            (storedSortedMap, CursorConfig.DIRTY_READ);
229    }
230
231    /**
232     * @deprecated This method has been replaced by {@link
233     * #configuredSortedSet} in order to conform to ANSI database isolation
234     * terminology.  To obtain a dirty-read set, pass
235     * <code>CursorConfig.READ_UNCOMMITTED</code>
236     */
237    public static SortedSet dirtyReadSortedSet(SortedSet storedSortedSet) {
238
239        /* We can't use READ_UNCOMMITTED until is is added to DB core. */
240        return configuredSortedSet
241            (storedSortedSet, CursorConfig.DIRTY_READ);
242    }
243
244    /**
245     * Clones an iterator preserving its current position.
246     *
247     * @param iter an iterator to clone.
248     *
249     * @return a new {@code Iterator} having the same position as the given
250     * iterator.
251     *
252     * @throws ClassCastException if the given iterator was not obtained via a
253     * {@link StoredCollection} method.
254     */
255    public static Iterator iterator(Iterator iter) {
256
257        return ((BaseIterator) iter).dup();
258    }
259}
260