00001 /* 00002 * MapIndex.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_MAP_INDEX_HPP 00017 #define COH_MAP_INDEX_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Comparator.hpp" 00022 #include "coherence/util/Map.hpp" 00023 #include "coherence/util/ValueExtractor.hpp" 00024 00025 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 00028 /** 00029 * MapIndex is used to correlate values stored in an <i>indexed Map</i> (or 00030 * attributes of those values) to the corresponding keys in the indexed Map. 00031 * 00032 * @author tb 2009.02.09 00033 */ 00034 class COH_EXPORT MapIndex 00035 : public interface_spec<MapIndex> 00036 { 00037 // ----- MapIndex interface --------------------------------------------- 00038 00039 public: 00040 /** 00041 * Obtain the ValueExtractor object that the MapIndex uses to extract 00042 * an indexable Object from a value stored in the indexed Map. This 00043 * property is never NULL. 00044 * 00045 * @return a ValueExtractor object, never NULL 00046 */ 00047 virtual ValueExtractor::View getValueExtractor() const = 0; 00048 00049 /** 00050 * Determine if the MapIndex orders the contents of the indexed 00051 * information. To determine in which way the contents are ordered, 00052 * get the Comparator from the <i>index contents</i> SortedMap object. 00053 * 00054 * @return true if the index contents are ordered, false otherwise 00055 */ 00056 virtual bool isOrdered() const = 0; 00057 00058 /** 00059 * Determine if indexed information for any entry in the indexed Map has 00060 * been excluded from this index. This information is used for 00061 * IndexAwareFilter implementations to determine the most optimal 00062 * way to apply the index. 00063 * 00064 * @return true if any entry of the indexed Map has been excluded from 00065 * the index, false otherwise 00066 * @since Coherence 3.6 00067 */ 00068 virtual bool isPartial() const = 0; 00069 00070 /** 00071 * Get the Map that contains the <i>index contents</i>. 00072 * <p> 00073 * The keys of the Map are the return values from the ValueExtractor 00074 * operating against the indexed Map's values, and for each key, the 00075 * corresponding value stored in the Map is a Set of keys to the 00076 * indexed Map. 00077 * <p> 00078 * If the MapIndex is known to be ordered, then the returned Map object 00079 * will be an instance of SortedMap. The SortedMap may or may 00080 * not have a Comparator object associated with it. 00081 * <p> 00082 * A client should assume that the returned Map object is read-only and 00083 * must not attempt to modify it. 00084 * 00085 * @return a Map (or a SortedMap) of the index contents 00086 */ 00087 virtual Map::View getIndexContents() const = 0; 00088 00089 /** 00090 * Using the index information if possible, get the value associated 00091 * with the specified key. This is expected to be more efficient than 00092 * using the ValueExtractor against an object containing the value, 00093 * because the index should already have the necessary information at 00094 * hand. 00095 * 00096 * @param vKey the key that specifies the object to extract the value 00097 * from 00098 * 00099 * @return the value that would be extracted by this MapIndex's 00100 * ValueExtractor from the object specified by the passed key; 00101 * getNoValue() if the index does not have the necessary 00102 * information 00103 */ 00104 virtual Object::Holder get(Object::View vKey) const = 0; 00105 00106 /** 00107 * Using the index information if possible, get the value associated 00108 * with the specified key. This is expected to be more efficient than 00109 * using the ValueExtractor against an object containing the value, 00110 * because the index should already have the necessary information at 00111 * hand. 00112 * 00113 * @param oKey the key that specifies the object to extract the value 00114 * from 00115 * 00116 * @return the value that would be extracted by this MapIndex's 00117 * ValueExtractor from the object specified by the passed key 00118 */ 00119 virtual Object::Holder get(Object::View vKey) = 0; 00120 00121 /** 00122 * Get the Comparator used to sort the index. 00123 * 00124 * @return the comparator 00125 * 00126 * @since Coherence 3.5 00127 */ 00128 virtual Comparator::View getComparator() const = 0; 00129 00130 /** 00131 * Update the index in response to a insert operation on a cache. 00132 * 00133 * @param vEntry the entry representing the object being inserted 00134 * 00135 * @since Coherence 3.5 00136 */ 00137 virtual void insert(Map::Entry::View vEntry) = 0; 00138 00139 /** 00140 * Update the index in response to an update operation on a cache. 00141 * 00142 * @param vEntry the entry representing the object being updated 00143 * 00144 * @since Coherence 3.5 00145 */ 00146 virtual void update(Map::Entry::View vEntry) = 0; 00147 00148 /** 00149 * Update the index in response to a remove operation on a cache. 00150 * 00151 * @param vEntry the entry representing the object being deleted 00152 * 00153 * @since Coherence 3.5 00154 */ 00155 virtual void remove(Map::Entry::View vEntry) = 0; 00156 00157 00158 // ---- constants ------------------------------------------------------- 00159 00160 public: 00161 /** 00162 * Constant used to indicate that the index does not contain requested 00163 * value. 00164 * 00165 * @return a constant used to indicate that the index does not 00166 * contain requested value. 00167 * 00168 * @since Coherence 3.6.1 00169 */ 00170 static Object::View getNoValue(); 00171 }; 00172 00173 COH_CLOSE_NAMESPACE2 00174 00175 #endif // COH_MAP_INDEX_HPP