Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/Collections.hpp

    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

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.