00001 /* 00002 * Collections.hpp 00003 * 00004 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_COLLECTIONS_HPP 00017 #define COH_COLLECTIONS_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Comparator.hpp" 00022 #include "coherence/util/List.hpp" 00023 #include "coherence/util/Map.hpp" 00024 #include "coherence/util/Set.hpp" 00025 #include "coherence/util/SortedMap.hpp" 00026 00027 COH_OPEN_NAMESPACE2(coherence,util) 00028 00029 00030 /** 00031 * This class consists exclusively of static methods that operate on or return 00032 * collections. 00033 * 00034 * @author tb 2008.04.04 00035 */ 00036 class COH_EXPORT Collections 00037 { 00038 // ----- static methods ------------------------------------------------- 00039 00040 public: 00041 /** 00042 * Sorts the specified list into ascending order, according to the 00043 * natural ordering of its elements. All elements in the list must 00044 * implement the Comparable interface. Furthermore, all elements 00045 * in the list must be mutually comparable. 00046 * 00047 * This sort is guaranteed to be stable: equal elements will not be 00048 * reordered as a result of the sort. 00049 * 00050 * The specified list must be modifiable, but need not be resizable. 00051 * 00052 * @param hList the list to be sorted 00053 * @throws ClassCastException if the list contains elements that are 00054 * not mutually comparable 00055 * @throws UnsupportedOperationException if the specified list's 00056 * list-iterator does not support the set operation 00057 */ 00058 static void sort(List::Handle hList); 00059 00060 /** 00061 * Sorts the specified list according to the order induced by the 00062 * specified comparator. All elements in the list must be mutually 00063 * comparable using the specified comparator 00064 * 00065 * This sort is guaranteed to be stable: equal elements will not be 00066 * reordered as a result of the sort. 00067 * 00068 * The specified list must be modifiable, but need not be resizable. 00069 * 00070 * @param hList the list to be sorted. 00071 * @param hComparator the comparator to determine the order of the 00072 * list. A null value indicates that the 00073 * elements' natural ordering should be used. 00074 * @throws ClassCastException if the list contains elements that are 00075 * not mutually comparable using the specified comparator. 00076 * @throws UnsupportedOperationException if the specified list's 00077 * list-iterator does not support the set operation. 00078 */ 00079 static void sort(List::Handle hList, Comparator::Handle hComparator); 00080 00081 /** 00082 * Returns an immutable set containing only the specified object. 00083 * 00084 * @param ohElement the sole object to be stored in the returned set 00085 * 00086 * @return an immutable set containing only the specified object 00087 */ 00088 static Set::View singleton(Object::Holder ohElement); 00089 00090 /** 00091 * Returns an immutable list containing only the specified object. 00092 * 00093 * @param ohElement the sole object to be stored in the returned list 00094 * 00095 * @return an immutable list containing only the specified object 00096 */ 00097 static List::View singletonList(Object::Holder ohElement); 00098 00099 /** 00100 * Returns an immutable map, mapping only the specified key to the 00101 * specified value. 00102 * 00103 * @param vKey the sole key to be stored in the returned map 00104 * @param ohValue the value to which the returned map maps key 00105 * 00106 * @return an immutable map containing only the specified key-value 00107 * mapping 00108 */ 00109 static Map::View singletonMap(Object::View vKey, Object::Holder ohValue); 00110 00111 /** 00112 * Returns a synchronized (thread-safe) map backed by the specified 00113 * map. In order to guarantee serial access, it is critical that 00114 * <strong>all</strong> access to the backing map is accomplished 00115 * through the returned map. 00116 * <p> 00117 * It is imperative that the user manually synchronize on the returned 00118 * map when iterating over any of its collection views: 00119 * <pre> 00120 * Map::Handle m = Collections::synchronizedMap(HashMap::create()); 00121 * ... 00122 * Set::View s = m->keySet(); // Needn't be in synchronized block 00123 * ... 00124 * synchronized(m) { // Synchronizing on m, not s! 00125 * // Must be in synchronized block 00126 * Iterator::Handle i = s->iterator(); 00127 * while (i->hasNext()) 00128 * foo(i->next()); 00129 * } 00130 * </pre> 00131 * Failure to follow this advice may result in non-deterministic behavior. 00132 * 00133 * @param hMap the map to be synchronized 00134 * 00135 * @return an synchronized wrapper for a map 00136 */ 00137 static Map::Handle synchronizedMap(Map::Handle hMap); 00138 00139 /** 00140 * Returns a synchronized (thread-safe) map backed by the specified 00141 * map. 00142 * 00143 * @param vMap the map to be synchronized 00144 * 00145 * @return an synchronized wrapper for a map 00146 */ 00147 static Map::View synchronizedMap(Map::View vMap); 00148 00149 /** 00150 * Returns a synchronized (thread-safe) sorted map backed by the 00151 * specified sorted map. In order to guarantee serial access, it 00152 * is critical that <strong>all</strong> access to the backing sorted 00153 * map is accomplished through the returned sorted map (or its views). 00154 * <p> 00155 * It is imperative that the user manually synchronize on the returned 00156 * sorted map when iterating over any of its collection views, or the 00157 * collections views of any of its <tt>subMap</tt>, <tt>headMap</tt> 00158 * or <tt>tailMap</tt> views. 00159 * <pre> 00160 * SortedMap::Handle m = Collections::synchronizedSortedMap( 00161 * TreeMap::create()); 00162 * ... 00163 * Set::View s = m->keySet(); // Needn't be in synchronized block 00164 * ... 00165 * synchronized(m) { // Synchronizing on m, not s! 00166 * // Must be in synchronized block 00167 * Iterator::Handle i = s->iterator(); 00168 * while (i->hasNext()) 00169 * foo(i->next()); 00170 * } 00171 * </pre> 00172 * or: 00173 * <pre> 00174 * SortedMap::Handle m = Collections::synchronizedSortedMap( 00175 * TreeMap::create()); 00176 * SortedMap::Handle m2 = m->subMap(foo, bar); 00177 * ... 00178 * Set::View s2 = m2->keySet(); // Needn't be in synchronized block 00179 * ... 00180 * synchronized(m) { // Synchronizing on m, not m2 or s2! 00181 * // Must be in synchronized block 00182 * Iterator::Handle i = s->iterator(); 00183 * while (i->hasNext()) 00184 * foo(i->next()); 00185 * } 00186 * </pre> 00187 * Failure to follow this advice may result in non-deterministic behavior. 00188 * 00189 * @param hSortedMap the sorted map to be synchronized 00190 * 00191 * @return an synchronized wrapper for a sorted map 00192 */ 00193 static SortedMap::Handle synchronizedSortedMap(SortedMap::Handle hSortedMap); 00194 00195 /** 00196 * Returns a synchronized (thread-safe) map backed by the specified 00197 * sorted map. 00198 * 00199 * @param vSortedMap the sorted map to be synchronized 00200 * 00201 * @return an synchronized wrapper for a sorted map 00202 */ 00203 static SortedMap::View synchronizedSortedMap(SortedMap::View vSortedMap); 00204 00205 /** 00206 * Returns an unmodifiable view of the specified collection. This 00207 * method allows modules to provide users with "read-only" access to 00208 * internal collections. Query operations on the returned collection 00209 * "read through" to the specified collection, and attempts to modify 00210 * the returned collection, whether direct or via its iterator, result 00211 * in an UnsupportedOperationException. 00212 * 00213 * The returned collection does <i>not</i> pass the hashCode and 00214 * equals operations through to the backing collection, but relies on 00215 * <tt>Object</tt>'s <tt>equals</tt> and <tt>hashCode</tt> methods. 00216 * This is necessary to preserve the contracts of these operations in 00217 * the case that the backing collection is a set or a list. 00218 * 00219 * @param vCollection the collection for which an unmodifiable view 00220 * is to be returned. 00221 * @return an unmodifiable view of the specified collection. 00222 */ 00223 static Collection::Handle unmodifiableCollection(Collection::View 00224 vCollection); 00225 00226 /** 00227 * Returns an unmodifiable view of the specified set. This method 00228 * allows modules to provide users with "read-only" access to internal 00229 * sets. Query operations on the returned set "read through" to the 00230 * specified set, and attempts to modify the returned set, whether 00231 * direct or via its iterator, result in an 00232 * UnsupportedOperationException. 00233 * 00234 * @param vSet the set for which an unmodifiable view is to be returned. 00235 * @return an unmodifiable view of the specified set. 00236 */ 00237 static Set::Handle unmodifiableSet(Set::View vSet); 00238 00239 /** 00240 * Returns an unmodifiable view of an empty set. 00241 * 00242 * @return an unmodifiable view of an empty set. 00243 */ 00244 static Set::View emptySet(); 00245 00246 /** 00247 * Returns an unmodifiable view of an empty map. 00248 * 00249 * @return an unmodifiable view of an empty map. 00250 */ 00251 static Map::View emptyMap(); 00252 00253 /** 00254 * Write out the contents of a Iterator. 00255 * 00256 * @param out the stream to write the Iterator to 00257 * @param hIter the Iterator to write 00258 */ 00259 static void toStream(std::ostream& out, Iterator::Handle hIter); 00260 00261 /** 00262 * Write out the contents of a Collection. 00263 * 00264 * @param out the stream to write the Collection to 00265 * @param vCol the Collection to write 00266 */ 00267 static void toStream(std::ostream& out, Collection::View vCol); 00268 00269 /** 00270 * Write out the contents of a Map. 00271 * 00272 * @param out the stream to write the Map to 00273 * @param vCol the Map to write 00274 */ 00275 static void toStream(std::ostream& out, Map::View vMap); 00276 00277 /** 00278 * Write out the contents of a Entry. 00279 * 00280 * @param out the stream to write the Entry to 00281 * @param vEntry the Entry to write 00282 */ 00283 static void toStream(std::ostream& out, Map::Entry::View vEntry); 00284 00285 /** 00286 * Return the contents of the collection as an ObjectArray. 00287 * If the collection fits in the specified array, it is returned, 00288 * otherwise, a new array is allocated that is the size of this 00289 * collection. 00290 * 00291 * If the collection fits in the array with aditional room 00292 * then the element in the array immediately following the end of the 00293 * collection is set to NULL. This can be useful in determining the 00294 * length of this collection if the caller knows that the collection 00295 * does not contain any NULL elements. 00296 * 00297 * @param vCol the Collection to turn into an array 00298 * @param hao an array in which to store the collection's contents 00299 * 00300 * @return a ObjectArray containing all the elements of the collection 00301 * in the same order as returned by the collection's Iterator 00302 * 00303 * @see Iterator 00304 */ 00305 static ObjectArray::Handle toArray(Collection::View vCol, 00306 ObjectArray::Handle hao = NULL); 00307 }; 00308 00309 COH_CLOSE_NAMESPACE2 00310 00311 #endif // COH_COLLECTIONS_HPP