/*- * See the file LICENSE for redistribution information. * * Copyright (c) 2000,2008 Oracle. All rights reserved. * * $Id: StoredCollections.java,v 12.7 2008/01/08 20:58:36 bostic Exp $ */ package com.sleepycat.collections; import java.util.Collection; import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.Set; import java.util.SortedMap; import java.util.SortedSet; import com.sleepycat.db.CursorConfig; /** * Static methods operating on collections and maps. * * <p>This class consists exclusively of static methods that operate on or * return stored collections and maps, jointly called containers. It contains * methods for changing certain properties of a container. Because container * properties are immutable, these methods always return a new container * instance. This allows stored container instances to be used safely by * multiple threads. Creating the new container instance is not expensive and * creates only two new objects.</p> * * <p>When a container is created with a particular property, all containers * and iterators derived from that container will inherit the property. For * example, if a read-uncommitted Map is created then calls to its subMap(), * values(), entrySet(), and keySet() methods will create read-uncommitted * containers also.</p> * * <p>Method names beginning with "configured" create a new container with a * specified {@link CursorConfig} from a given stored container. This allows * configuring a container for read-committed isolation, read-uncommitted * isolation, or any other property supported by <code>CursorConfig</code>. * All operations performed with the resulting container will be performed with * the specified cursor configuration.</p> */ public class StoredCollections { private StoredCollections() {} /** * Creates a configured collection from a given stored collection. * * @param storedCollection the base collection. * * @param config is the cursor configuration to be used for all operations * performed via the new collection instance; null may be specified to use * the default configuration. * * @return the configured collection. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Collection configuredCollection(Collection storedCollection, CursorConfig config) { return (Collection) ((StoredContainer) storedCollection).configuredClone(config); } /** * Creates a configured list from a given stored list. * * <p>Note that this method may not be called in the JE product, since the * StoredList class is not supported.</p> * * @param storedList the base list. * * @param config is the cursor configuration to be used for all operations * performed via the new list instance; null may be specified to use the * default configuration. * * @return the configured list. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static List configuredList(List storedList, CursorConfig config) { return (List) ((StoredContainer) storedList).configuredClone(config); } /** * Creates a configured map from a given stored map. * * @param storedMap the base map. * * @param config is the cursor configuration to be used for all operations * performed via the new map instance; null may be specified to use the * default configuration. * * @return the configured map. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Map configuredMap(Map storedMap, CursorConfig config) { return (Map) ((StoredContainer) storedMap).configuredClone(config); } /** * Creates a configured set from a given stored set. * * @param storedSet the base set. * * @param config is the cursor configuration to be used for all operations * performed via the new set instance; null may be specified to use the * default configuration. * * @return the configured set. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Set configuredSet(Set storedSet, CursorConfig config) { return (Set) ((StoredContainer) storedSet).configuredClone(config); } /** * Creates a configured sorted map from a given stored sorted map. * * @param storedSortedMap the base map. * * @param config is the cursor configuration to be used for all operations * performed via the new map instance; null may be specified to use the * default configuration. * * @return the configured map. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static SortedMap configuredSortedMap(SortedMap storedSortedMap, CursorConfig config) { return (SortedMap) ((StoredContainer) storedSortedMap).configuredClone(config); } /** * Creates a configured sorted set from a given stored sorted set. * * @param storedSortedSet the base set. * * @param config is the cursor configuration to be used for all operations * performed via the new set instance; null may be specified to use the * default configuration. * * @return the configured set. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static SortedSet configuredSortedSet(SortedSet storedSortedSet, CursorConfig config) { return (SortedSet) ((StoredContainer) storedSortedSet).configuredClone(config); } /** * @deprecated This method has been replaced by {@link * #configuredCollection} in order to conform to ANSI database isolation * terminology. To obtain a dirty-read collection, pass * <code>CursorConfig.READ_UNCOMMITTED</code> */ public static Collection dirtyReadCollection(Collection storedCollection) { /* We can't use READ_UNCOMMITTED until is is added to DB core. */ return configuredCollection (storedCollection, CursorConfig.DIRTY_READ); } /** * @deprecated This method has been replaced by {@link #configuredList} in * order to conform to ANSI database isolation terminology. To obtain a * dirty-read list, pass <code>CursorConfig.READ_UNCOMMITTED</code> */ public static List dirtyReadList(List storedList) { /* We can't use READ_UNCOMMITTED until is is added to DB core. */ return configuredList(storedList, CursorConfig.DIRTY_READ); } /** * @deprecated This method has been replaced by {@link #configuredMap} in * order to conform to ANSI database isolation terminology. To obtain a * dirty-read map, pass <code>CursorConfig.READ_UNCOMMITTED</code> */ public static Map dirtyReadMap(Map storedMap) { /* We can't use READ_UNCOMMITTED until is is added to DB core. */ return configuredMap(storedMap, CursorConfig.DIRTY_READ); } /** * @deprecated This method has been replaced by {@link #configuredSet} in * order to conform to ANSI database isolation terminology. To obtain a * dirty-read set, pass <code>CursorConfig.READ_UNCOMMITTED</code> */ public static Set dirtyReadSet(Set storedSet) { /* We can't use READ_UNCOMMITTED until is is added to DB core. */ return configuredSet(storedSet, CursorConfig.DIRTY_READ); } /** * @deprecated This method has been replaced by {@link * #configuredSortedMap} in order to conform to ANSI database isolation * terminology. To obtain a dirty-read map, pass * <code>CursorConfig.READ_UNCOMMITTED</code> */ public static SortedMap dirtyReadSortedMap(SortedMap storedSortedMap) { /* We can't use READ_UNCOMMITTED until is is added to DB core. */ return configuredSortedMap (storedSortedMap, CursorConfig.DIRTY_READ); } /** * @deprecated This method has been replaced by {@link * #configuredSortedSet} in order to conform to ANSI database isolation * terminology. To obtain a dirty-read set, pass * <code>CursorConfig.READ_UNCOMMITTED</code> */ public static SortedSet dirtyReadSortedSet(SortedSet storedSortedSet) { /* We can't use READ_UNCOMMITTED until is is added to DB core. */ return configuredSortedSet (storedSortedSet, CursorConfig.DIRTY_READ); } /** * Clones an iterator preserving its current position. * * @param iter an iterator to clone. * * @return a new {@code Iterator} having the same position as the given * iterator. * * @throws ClassCastException if the given iterator was not obtained via a * {@link StoredCollection} method. */ public static Iterator iterator(Iterator iter) { return ((BaseIterator) iter).dup(); } }