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