00001 /* 00002 * Collections.hpp 00003 * 00004 * Copyright (c) 2000, 2010, 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 00026 COH_OPEN_NAMESPACE2(coherence,util) 00027 00028 00029 /** 00030 * This class consists exclusively of static methods that operate on or return 00031 * collections. 00032 * 00033 * @author tb 2008.04.04 00034 */ 00035 class COH_EXPORT Collections 00036 { 00037 // ----- static methods ------------------------------------------------- 00038 00039 public: 00040 /** 00041 * Sorts the specified list into ascending order, according to the 00042 * natural ordering of its elements. All elements in the list must 00043 * implement the Comparable interface. Furthermore, all elements 00044 * in the list must be mutually comparable. 00045 * 00046 * This sort is guaranteed to be stable: equal elements will not be 00047 * reordered as a result of the sort. 00048 * 00049 * The specified list must be modifiable, but need not be resizable. 00050 * 00051 * @param hList the list to be sorted 00052 * @throws ClassCastException if the list contains elements that are 00053 * not mutually comparable 00054 * @throws UnsupportedOperationException if the specified list's 00055 * list-iterator does not support the set operation 00056 */ 00057 static void sort(List::Handle hList); 00058 00059 /** 00060 * Sorts the specified list according to the order induced by the 00061 * specified comparator. All elements in the list must be mutually 00062 * comparable using the specified comparator 00063 * 00064 * This sort is guaranteed to be stable: equal elements will not be 00065 * reordered as a result of the sort. 00066 * 00067 * The specified list must be modifiable, but need not be resizable. 00068 * 00069 * @param hList the list to be sorted. 00070 * @param hComparator the comparator to determine the order of the 00071 * list. A null value indicates that the 00072 * elements' natural ordering should be used. 00073 * @throws ClassCastException if the list contains elements that are 00074 * not mutually comparable using the specified comparator. 00075 * @throws UnsupportedOperationException if the specified list's 00076 * list-iterator does not support the set operation. 00077 */ 00078 static void sort(List::Handle hList, Comparator::Handle hComparator); 00079 00080 /** 00081 * Returns an immutable set containing only the specified object. 00082 * 00083 * @param ohElement the sole object to be stored in the returned set 00084 * 00085 * @return an immutable set containing only the specified object 00086 */ 00087 static Set::View singleton(Object::Holder ohElement); 00088 00089 /** 00090 * Returns an immutable list containing only the specified object. 00091 * 00092 * @param ohElement the sole object to be stored in the returned list 00093 * 00094 * @return an immutable list containing only the specified object 00095 */ 00096 static List::View singletonList(Object::Holder ohElement); 00097 00098 /** 00099 * Returns an immutable map, mapping only the specified key to the 00100 * specified value. 00101 * 00102 * @param vKey the sole key to be stored in the returned map 00103 * @param ohValue the value to which the returned map maps key 00104 * 00105 * @return an immutable map containing only the specified key-value 00106 * mapping 00107 */ 00108 static Map::View singletonMap(Object::View vKey, Object::Holder ohValue); 00109 00110 /** 00111 * Returns an unmodifiable view of the specified collection. This 00112 * method allows modules to provide users with "read-only" access to 00113 * internal collections. Query operations on the returned collection 00114 * "read through" to the specified collection, and attempts to modify 00115 * the returned collection, whether direct or via its iterator, result 00116 * in an UnsupportedOperationException. 00117 * 00118 * The returned collection does <i>not</i> pass the hashCode and 00119 * equals operations through to the backing collection, but relies on 00120 * <tt>Object</tt>'s <tt>equals</tt> and <tt>hashCode</tt> methods. 00121 * This is necessary to preserve the contracts of these operations in 00122 * the case that the backing collection is a set or a list. 00123 * 00124 * @param vCollection the collection for which an unmodifiable view 00125 * is to be returned. 00126 * @return an unmodifiable view of the specified collection. 00127 */ 00128 static Collection::Handle unmodifiableCollection(Collection::View 00129 vCollection); 00130 00131 /** 00132 * Returns an unmodifiable view of the specified set. This method 00133 * allows modules to provide users with "read-only" access to internal 00134 * sets. Query operations on the returned set "read through" to the 00135 * specified set, and attempts to modify the returned set, whether 00136 * direct or via its iterator, result in an 00137 * UnsupportedOperationException. 00138 * 00139 * @param vSet the set for which an unmodifiable view is to be returned. 00140 * @return an unmodifiable view of the specified set. 00141 */ 00142 static Set::Handle unmodifiableSet(Set::View vSet); 00143 00144 /** 00145 * Returns an unmodifiable view of an empty set. 00146 * 00147 * @return an unmodifiable view of an empty set. 00148 */ 00149 static Set::View emptySet(); 00150 00151 /** 00152 * Returns an unmodifiable view of an empty map. 00153 * 00154 * @return an unmodifiable view of an empty map. 00155 */ 00156 static Map::View emptyMap(); 00157 00158 /** 00159 * Write out the contents of a Iterator. 00160 * 00161 * @param out the stream to write the Iterator to 00162 * @param hIter the Iterator to write 00163 */ 00164 static void toStream(std::ostream& out, Iterator::Handle hIter); 00165 00166 /** 00167 * Write out the contents of a Collection. 00168 * 00169 * @param out the stream to write the Collection to 00170 * @param vCol the Collection to write 00171 */ 00172 static void toStream(std::ostream& out, Collection::View vCol); 00173 00174 /** 00175 * Write out the contents of a Map. 00176 * 00177 * @param out the stream to write the Map to 00178 * @param vCol the Map to write 00179 */ 00180 static void toStream(std::ostream& out, Map::View vMap); 00181 00182 /** 00183 * Write out the contents of a Entry. 00184 * 00185 * @param out the stream to write the Entry to 00186 * @param vEntry the Entry to write 00187 */ 00188 static void toStream(std::ostream& out, Map::Entry::View vEntry); 00189 00190 /** 00191 * Return the contents of the collection as an ObjectArray. 00192 * If the collection fits in the specified array, it is returned, 00193 * otherwise, a new array is allocated that is the size of this 00194 * collection. 00195 * 00196 * If the collection fits in the array with aditional room 00197 * then the element in the array immediately following the end of the 00198 * collection is set to NULL. This can be useful in determining the 00199 * length of this collection if the caller knows that the collection 00200 * does not contain any NULL elements. 00201 * 00202 * @param vCol the Collection to turn into an array 00203 * @param hao an array in which to store the collection's contents 00204 * 00205 * @return a ObjectArray containing all the elements of the collection 00206 * in the same order as returned by the collection's Iterator 00207 * 00208 * @see Iterator 00209 */ 00210 static ObjectArray::Handle toArray(Collection::View vCol, 00211 ObjectArray::Handle hao = NULL); 00212 }; 00213 00214 COH_CLOSE_NAMESPACE2 00215 00216 #endif // COH_COLLECTIONS_HPP