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