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