001: /*-
002: * See the file LICENSE for redistribution information.
003: *
004: * Copyright (c) 2000,2008 Oracle. All rights reserved.
005: *
006: * $Id: StoredCollections.java,v 1.29.2.2 2008/01/07 15:14:06 cwl Exp $
007: */
008:
009: package com.sleepycat.collections;
010:
011: import java.util.Collection;
012: import java.util.Iterator;
013: import java.util.List;
014: import java.util.Map;
015: import java.util.Set;
016: import java.util.SortedMap;
017: import java.util.SortedSet;
018:
019: import com.sleepycat.je.CursorConfig;
020:
021: /**
022: * Static methods operating on collections and maps.
023: *
024: * <p>This class consists exclusively of static methods that operate on or
025: * return stored collections and maps, jointly called containers. It contains
026: * methods for changing certain properties of a container. Because container
027: * properties are immutable, these methods always return a new container
028: * instance. This allows stored container instances to be used safely by
029: * multiple threads. Creating the new container instance is not expensive and
030: * creates only two new objects.</p>
031: *
032: * <p>When a container is created with a particular property, all containers
033: * and iterators derived from that container will inherit the property. For
034: * example, if a read-uncommitted Map is created then calls to its subMap(),
035: * values(), entrySet(), and keySet() methods will create read-uncommitted
036: * containers also.</p>
037: *
038: * <p>Method names beginning with "configured" create a new container with a
039: * specified {@link CursorConfig} from a given stored container. This allows
040: * configuring a container for read-committed isolation, read-uncommitted
041: * isolation, or any other property supported by <code>CursorConfig</code>.
042: * All operations performed with the resulting container will be performed with
043: * the specified cursor configuration.</p>
044: */
045: public class StoredCollections {
046:
047: private StoredCollections() {
048: }
049:
050: /**
051: * Creates a configured collection from a given stored collection.
052: *
053: * @param storedCollection the base collection.
054: *
055: * @param config is the cursor configuration to be used for all operations
056: * performed via the new collection instance; null may be specified to use
057: * the default configuration.
058: *
059: * @return the configured collection.
060: *
061: * @throws ClassCastException if the given container is not a
062: * StoredContainer.
063: */
064: public static Collection configuredCollection(
065: Collection storedCollection, CursorConfig config) {
066:
067: return (Collection) ((StoredContainer) storedCollection)
068: .configuredClone(config);
069: }
070:
071: /**
072: * Creates a configured list from a given stored list.
073: *
074: * <p>Note that this method may not be called in the JE product, since the
075: * StoredList class is not supported.</p>
076: *
077: * @param storedList the base list.
078: *
079: * @param config is the cursor configuration to be used for all operations
080: * performed via the new list instance; null may be specified to use the
081: * default configuration.
082: *
083: * @return the configured list.
084: *
085: * @throws ClassCastException if the given container is not a
086: * StoredContainer.
087: */
088: public static List configuredList(List storedList,
089: CursorConfig config) {
090:
091: return (List) ((StoredContainer) storedList)
092: .configuredClone(config);
093: }
094:
095: /**
096: * Creates a configured map from a given stored map.
097: *
098: * @param storedMap the base map.
099: *
100: * @param config is the cursor configuration to be used for all operations
101: * performed via the new map instance; null may be specified to use the
102: * default configuration.
103: *
104: * @return the configured map.
105: *
106: * @throws ClassCastException if the given container is not a
107: * StoredContainer.
108: */
109: public static Map configuredMap(Map storedMap, CursorConfig config) {
110:
111: return (Map) ((StoredContainer) storedMap)
112: .configuredClone(config);
113: }
114:
115: /**
116: * Creates a configured set from a given stored set.
117: *
118: * @param storedSet the base set.
119: *
120: * @param config is the cursor configuration to be used for all operations
121: * performed via the new set instance; null may be specified to use the
122: * default configuration.
123: *
124: * @return the configured set.
125: *
126: * @throws ClassCastException if the given container is not a
127: * StoredContainer.
128: */
129: public static Set configuredSet(Set storedSet, CursorConfig config) {
130:
131: return (Set) ((StoredContainer) storedSet)
132: .configuredClone(config);
133: }
134:
135: /**
136: * Creates a configured sorted map from a given stored sorted map.
137: *
138: * @param storedSortedMap the base map.
139: *
140: * @param config is the cursor configuration to be used for all operations
141: * performed via the new map instance; null may be specified to use the
142: * default configuration.
143: *
144: * @return the configured map.
145: *
146: * @throws ClassCastException if the given container is not a
147: * StoredContainer.
148: */
149: public static SortedMap configuredSortedMap(
150: SortedMap storedSortedMap, CursorConfig config) {
151:
152: return (SortedMap) ((StoredContainer) storedSortedMap)
153: .configuredClone(config);
154: }
155:
156: /**
157: * Creates a configured sorted set from a given stored sorted set.
158: *
159: * @param storedSortedSet the base set.
160: *
161: * @param config is the cursor configuration to be used for all operations
162: * performed via the new set instance; null may be specified to use the
163: * default configuration.
164: *
165: * @return the configured set.
166: *
167: * @throws ClassCastException if the given container is not a
168: * StoredContainer.
169: */
170: public static SortedSet configuredSortedSet(
171: SortedSet storedSortedSet, CursorConfig config) {
172:
173: return (SortedSet) ((StoredContainer) storedSortedSet)
174: .configuredClone(config);
175: }
176:
177: /**
178: * @deprecated This method has been replaced by {@link
179: * #configuredCollection} in order to conform to ANSI database isolation
180: * terminology. To obtain a dirty-read collection, pass
181: * <code>CursorConfig.READ_UNCOMMITTED</code>
182: */
183: public static Collection dirtyReadCollection(
184: Collection storedCollection) {
185:
186: /* We can't use READ_UNCOMMITTED until is is added to DB core. */
187: return configuredCollection(storedCollection,
188: CursorConfig.DIRTY_READ);
189: }
190:
191: /**
192: * @deprecated This method has been replaced by {@link #configuredList} in
193: * order to conform to ANSI database isolation terminology. To obtain a
194: * dirty-read list, pass <code>CursorConfig.READ_UNCOMMITTED</code>
195: */
196: public static List dirtyReadList(List storedList) {
197:
198: /* We can't use READ_UNCOMMITTED until is is added to DB core. */
199: return configuredList(storedList, CursorConfig.DIRTY_READ);
200: }
201:
202: /**
203: * @deprecated This method has been replaced by {@link #configuredMap} in
204: * order to conform to ANSI database isolation terminology. To obtain a
205: * dirty-read map, pass <code>CursorConfig.READ_UNCOMMITTED</code>
206: */
207: public static Map dirtyReadMap(Map storedMap) {
208:
209: /* We can't use READ_UNCOMMITTED until is is added to DB core. */
210: return configuredMap(storedMap, CursorConfig.DIRTY_READ);
211: }
212:
213: /**
214: * @deprecated This method has been replaced by {@link #configuredSet} in
215: * order to conform to ANSI database isolation terminology. To obtain a
216: * dirty-read set, pass <code>CursorConfig.READ_UNCOMMITTED</code>
217: */
218: public static Set dirtyReadSet(Set storedSet) {
219:
220: /* We can't use READ_UNCOMMITTED until is is added to DB core. */
221: return configuredSet(storedSet, CursorConfig.DIRTY_READ);
222: }
223:
224: /**
225: * @deprecated This method has been replaced by {@link
226: * #configuredSortedMap} in order to conform to ANSI database isolation
227: * terminology. To obtain a dirty-read map, pass
228: * <code>CursorConfig.READ_UNCOMMITTED</code>
229: */
230: public static SortedMap dirtyReadSortedMap(SortedMap storedSortedMap) {
231:
232: /* We can't use READ_UNCOMMITTED until is is added to DB core. */
233: return configuredSortedMap(storedSortedMap,
234: CursorConfig.DIRTY_READ);
235: }
236:
237: /**
238: * @deprecated This method has been replaced by {@link
239: * #configuredSortedSet} in order to conform to ANSI database isolation
240: * terminology. To obtain a dirty-read set, pass
241: * <code>CursorConfig.READ_UNCOMMITTED</code>
242: */
243: public static SortedSet dirtyReadSortedSet(SortedSet storedSortedSet) {
244:
245: /* We can't use READ_UNCOMMITTED until is is added to DB core. */
246: return configuredSortedSet(storedSortedSet,
247: CursorConfig.DIRTY_READ);
248: }
249:
250: /**
251: * Clones an iterator preserving its current position.
252: *
253: * @param iter an iterator to clone.
254: *
255: * @return a new {@code Iterator} having the same position as the given
256: * iterator.
257: *
258: * @throws ClassCastException if the given iterator was not obtained via a
259: * {@link StoredCollection} method.
260: */
261: public static Iterator iterator(Iterator iter) {
262:
263: return ((BaseIterator) iter).dup();
264: }
265: }
|