00001 /* 00002 * SortedMap.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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