Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/util/SortedMap.hpp

00001 /*
00002 * SortedMap.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_SORTED_MAP_HPP
00017 #define COH_SORTED_MAP_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 #include "coherence/util/Comparator.hpp"
00022 #include "coherence/util/Map.hpp"
00023 
00024 COH_OPEN_NAMESPACE2(coherence,util)
00025 
00026 
00027 /**
00028 * An interface for a map which guarantees its key's iteration order.
00029 *
00030 * @see Map
00031 * @see TreeMap
00032 *
00033 * @author tb  2009.02.13
00034 */
00035 class COH_EXPORT SortedMap
00036     : public interface_spec<SortedMap,
00037         implements<Map> >
00038     {
00039 
00040     // ----- Sorted Map interface -------------------------------------------
00041 
00042     public:
00043         /**
00044         * Returns the comparator used in sorting this map, or NULL if it is
00045         * the keys' natural ordering.
00046         *
00047         * @return the sorting comparator
00048         */
00049         virtual Comparator::View comparator() const = 0;
00050 
00051         /**
00052         * Returns the first (lowest sorted) key in the map.
00053         *
00054         * @return the first key
00055         * @throws NoSuchElementException if this map is empty.
00056         */
00057         virtual Object::View firstKey() const = 0;
00058 
00059         /**
00060         * Returns the last (highest sorted) key in the map.
00061         *
00062         * @return the last key
00063         *
00064         * @throws NoSuchElementException if this map is empty.
00065         */
00066         virtual Object::View lastKey() const = 0;
00067 
00068         /**
00069         * Returns a handle of the portion of the map strictly less than toKey.
00070         * The handle is backed by this map, so changes in one show up in the
00071         * other. The sub-map supports all optional operations of the original.
00072         *
00073         * @param vToKey the exclusive upper range of the sub-map
00074         *
00075         * @return the sub-map
00076         *
00077         * @throws ClassCastException if toKey is not comparable to the map
00078         *         contents
00079         * @throws IllegalArgumentException if this is a subMap, and toKey is
00080         *         out of range
00081         * @throws NullPointerException if toKey is NULL but the map does not
00082         *         allow NULL keys
00083         */
00084         virtual SortedMap::Handle headMap(Object::View vToKey) = 0;
00085 
00086         /**
00087         * Returns a view of the portion of the map strictly less than toKey.
00088         *
00089         * @param vToKey the exclusive upper range of the sub-map
00090         *
00091         * @return the sub-map
00092         *
00093         * @throws ClassCastException if toKey is not comparable to the map
00094         *         contents
00095         * @throws IllegalArgumentException if this is a subMap, and toKey is
00096         *         out of range
00097         * @throws NullPointerException if toKey is NULL but the map does not
00098         *         allow NULL keys
00099         */
00100         virtual SortedMap::View headMap(Object::View vToKey) const = 0;
00101 
00102         /**
00103         * Returns a handle of the portion of the map greater than or equal to
00104         * fromKey, and strictly less than toKey. The handle is backed by this
00105         * map, so changes in one show up in the other. The sub-map supports all
00106         * optional operations of the original.
00107         *
00108         * @param vFromKey the inclusive lower range of the sub-map
00109         * @param vToKey   the exclusive upper range of the sub-map
00110         *
00111         * @return the sub-map
00112         *
00113         * @throws ClassCastException if fromKey or toKey is not comparable to
00114         *         the map contents
00115         * @throws IllegalArgumentException if this is a subMap, and fromKey or
00116         *         toKey is out of range
00117         * @throws NullPointerException if fromKey or toKey is NULL but the map
00118         *         does not allow NULL keys
00119         */
00120         virtual SortedMap::Handle subMap(Object::View vFromKey,
00121                 Object::View vToKey) = 0;
00122 
00123         /**
00124         * Returns a view of the portion of the map greater than or equal to
00125         * fromKey, and strictly less than toKey.
00126         *
00127         * @param vFromKey the inclusive lower range of the sub-map
00128         * @param vToKey   the exclusive upper range of the sub-map
00129         *
00130         * @return the sub-map
00131         *
00132         * @throws ClassCastException if fromKey or toKey is not comparable to
00133         *         the map contents
00134         * @throws IllegalArgumentException if this is a subMap, and fromKey or
00135         *         toKey is out of range
00136         * @throws NullPointerException if fromKey or toKey is NULL but the map
00137         *         does not allow NULL keys
00138         */
00139         virtual SortedMap::View subMap(Object::View vFromKey,
00140                 Object::View vToKey) const = 0;
00141 
00142         /**
00143         * Returns a handle of the portion of the map greater than or equal to
00144         * fromKey. The handle is backed by this map, so changes in one show up
00145         * in the other. The sub-map supports all optional operations of the
00146         * original.
00147         *
00148         * @param vFromKey the inclusive lower range of the sub-map
00149         *
00150         * @return the sub-map
00151         *
00152         * @throws ClassCastException if fromKey is not comparable to the map
00153         *         contents
00154         * @throws IllegalArgumentException if this is a subMap, and fromKey is
00155         *         out of range
00156         * @throws NullPointerException if fromKey is NULL but the map does not
00157         *         allow NULL keys
00158         */
00159         virtual SortedMap::Handle tailMap(Object::View vFromKey) = 0;
00160 
00161         /**
00162         * Returns a view of the portion of the map greater than or equal to
00163         * fromKey.
00164         *
00165         * @param vFromKey the inclusive lower range of the sub-map
00166         *
00167         * @return the sub-map
00168         *
00169         * @throws ClassCastException if fromKey is not comparable to the map
00170         *         contents
00171         * @throws IllegalArgumentException if this is a subMap, and fromKey is
00172         *         out of range
00173         * @throws NullPointerException if fromKey is NULL but the map does not
00174         *         allow NULL keys
00175         */
00176         virtual SortedMap::View tailMap(Object::View vFromKey) const = 0;
00177     };
00178 
00179 COH_CLOSE_NAMESPACE2
00180 
00181 #endif // COH_SORTED_MAP_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.