/*- * See the file LICENSE for redistribution information. * * Copyright (c) 2000-2003 * Sleepycat Software. All rights reserved. * * $Id: StoredCollections.java,v 1.2 2004/03/30 01:23:34 jtownsen Exp $ */ package com.sleepycat.bdb.collection; import com.sleepycat.db.DbEnv; 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; /** * This class consists exclusively of static methods that operate on or return * stored collections. It contains methods for changing certain properties of a * collection. Because collection properties are immutable, these methods * always return a new collection reference. This allows stored collections to * be used safely by multiple threads. Note that creating the new collection * reference is not expensive and creates only two new objects. * * <p>When a collection is created with a particular property, all collections * and iterators derieved from that collection will inherit the property. For * example, if a dirty-read Map is created then calls to subMap(), values(), * entrySet(), and keySet() will create dirty-read collections also.</p> * * <p><b>Dirty-Read</b> Methods names beginning with dirtyRead create a new * dirty-read container from a given stored container. When dirty-read is * enabled, data will be read that has been modified by another transaction but * not committed. Using dirty-read can improve concurrency since reading will * not wait for other transactions to complete. For a non-transactional * container (when {@link StoredContainer#isTransactional} returns false), * dirty-read has no effect. If {@link StoredContainer#isDirtyReadAllowed} * returns false, dirty-read also has no effect. If dirty-ready is enabled * (and allowed) for a container, {@link StoredContainer#isDirtyReadEnabled} * will return true. Dirty-read is disabled by default for a container.</p> * * <p><b>Auto-Commit</b> Methods names beginning with autoCommit create a new * auto-commit container from a given stored container. If auto-commit is * enabled for a container (or for its {@link DbEnv}), a transaction will be * started and committed automatically for each write operation when no * transaction is already active. Auto-commit only applies to container * methods. It does not apply to iterator methods and these always require an * active transaction. For a non-transactional container (where {@link * StoredContainer#isTransactional} returns false) auto-commit has no effect. * If auto-commit is enabled for a transactional container or its environment, * {@link StoredContainer#isAutoCommit} will return true. Auto-commit is * disabled by default for a container but may be enabled for an entire * environment using {@link DbEnv#setFlags}.</p> */ public class StoredCollections { private StoredCollections() {} /** * Creates a dirty-read collection from a given stored collection. * * @param storedCollection the base collection. * * @return the dirty-read collection. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Collection dirtyReadCollection(Collection storedCollection) { return (Collection) ((StoredContainer) storedCollection).dirtyReadClone(); } /** * Creates a dirty-read list from a given stored list. * * @param storedList the base list. * * @return the dirty-read list. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static List dirtyReadList(List storedList) { return (List) ((StoredContainer) storedList).dirtyReadClone(); } /** * Creates a dirty-read map from a given stored map. * * @param storedMap the base map. * * @return the dirty-read map. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Map dirtyReadMap(Map storedMap) { return (Map) ((StoredContainer) storedMap).dirtyReadClone(); } /** * Creates a dirty-read set from a given stored set. * * @param storedSet the base set. * * @return the dirty-read set. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Set dirtyReadSet(Set storedSet) { return (Set) ((StoredContainer) storedSet).dirtyReadClone(); } /** * Creates a dirty-read sorted map from a given stored sorted map. * * @param storedSortedMap the base map. * * @return the dirty-read map. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static SortedMap dirtyReadSortedMap(SortedMap storedSortedMap) { return (SortedMap) ((StoredContainer) storedSortedMap).dirtyReadClone(); } /** * Creates a dirty-read sorted set from a given stored sorted set. * * @param storedSortedSet the base set. * * @return the dirty-read set. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static SortedSet dirtyReadSortedSet(SortedSet storedSortedSet) { return (SortedSet) ((StoredContainer) storedSortedSet).dirtyReadClone(); } /** * Creates a auto-commit collection from a given stored collection. * * @param storedCollection the base collection. * * @return the auto-commit collection. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Collection autoCommitCollection(Collection storedCollection) { return (Collection) ((StoredContainer) storedCollection).autoCommitClone(); } /** * Creates a auto-commit list from a given stored list. * * @param storedList the base list. * * @return the auto-commit list. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static List autoCommitList(List storedList) { return (List) ((StoredContainer) storedList).autoCommitClone(); } /** * Creates a auto-commit map from a given stored map. * * @param storedMap the base map. * * @return the auto-commit map. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Map autoCommitMap(Map storedMap) { return (Map) ((StoredContainer) storedMap).autoCommitClone(); } /** * Creates a auto-commit set from a given stored set. * * @param storedSet the base set. * * @return the auto-commit set. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static Set autoCommitSet(Set storedSet) { return (Set) ((StoredContainer) storedSet).autoCommitClone(); } /** * Creates a auto-commit sorted map from a given stored sorted map. * * @param storedSortedMap the base map. * * @return the auto-commit map. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static SortedMap autoCommitSortedMap(SortedMap storedSortedMap) { return (SortedMap) ((StoredContainer) storedSortedMap).autoCommitClone(); } /** * Creates a auto-commit sorted set from a given stored sorted set. * * @param storedSortedSet the base set. * * @return the auto-commit set. * * @throws ClassCastException if the given container is not a * StoredContainer. */ public static SortedSet autoCommitSortedSet(SortedSet storedSortedSet) { return (SortedSet) ((StoredContainer) storedSortedSet).autoCommitClone(); } /** * Clones a stored iterator preserving its current position. * * @param storedIterator an iterator to clone. * * @return a new {@link StoredIterator} having the same position as the * given iterator. * * @throws ClassCastException if the given iterator is not a * StoredIterator. */ public static Iterator iterator(Iterator storedIterator) { return (Iterator) ((StoredIterator) storedIterator).clone(); } }