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