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_SIMPLE_MAP_INDEX_HPP 00008 #define COH_SIMPLE_MAP_INDEX_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/util/Comparator.hpp" 00013 #include "coherence/util/Filter.hpp" 00014 #include "coherence/util/Map.hpp" 00015 #include "coherence/util/MapIndex.hpp" 00016 #include "coherence/util/MapTrigger.hpp" 00017 #include "coherence/util/Set.hpp" 00018 #include "coherence/util/ValueExtractor.hpp" 00019 00020 COH_OPEN_NAMESPACE2(coherence,util) 00021 00022 00023 /** 00024 * SimpleMapIndex is a MapIndex implementation used to correlate property values 00025 * extracted from resource map entries with corresponding keys using what is 00026 * commonly known as an <i>Inverted Index algorithm.</i>. 00027 * 00028 * @author tb 2009.02.09 00029 * @since Coherence 3.5 00030 */ 00031 class COH_EXPORT SimpleMapIndex 00032 : public class_spec<SimpleMapIndex, 00033 extends<Object>, 00034 implements<MapIndex> > 00035 { 00036 friend class factory<SimpleMapIndex>; 00037 00038 // ----- constructors --------------------------------------------------- 00039 00040 protected: 00041 /** 00042 * Construct an index from the given map. 00043 * 00044 * @param vExtractor the ValueExtractor object that is used to 00045 * extract an indexable Object from a value stored 00046 * in the indexed Map. Must not be NULL. 00047 * @param fOrdered true iff the contents of the indexed information 00048 * should be ordered; false otherwise 00049 * @param vComparator the Comparator object which imposes an ordering 00050 * on entries in the indexed map; or <tt>NULL</tt> 00051 * if the entries' values natural ordering should 00052 * be used 00053 * @param fInit initialize the index if true, default is true 00054 */ 00055 SimpleMapIndex(ValueExtractor::View vExtractor, bool fOrdered, 00056 Comparator::View vComparator, bool fInit = true); 00057 00058 00059 // ----- MapIndex interface --------------------------------------------- 00060 00061 public: 00062 /** 00063 * {@inheritDoc} 00064 */ 00065 virtual ValueExtractor::View getValueExtractor() const; 00066 00067 /** 00068 * {@inheritDoc} 00069 */ 00070 virtual bool isOrdered() const; 00071 00072 /** 00073 * {@inheritDoc} 00074 */ 00075 virtual bool isPartial() const; 00076 00077 /** 00078 * {@inheritDoc} 00079 */ 00080 virtual Map::View getIndexContents() const; 00081 00082 /** 00083 * {@inheritDoc} 00084 */ 00085 virtual Object::Holder get(Object::View vKey) const; 00086 00087 /** 00088 * {@inheritDoc} 00089 */ 00090 virtual Object::Holder get(Object::View vKey); 00091 00092 /** 00093 * {@inheritDoc} 00094 */ 00095 virtual Comparator::View getComparator() const; 00096 00097 /** 00098 * {@inheritDoc} 00099 */ 00100 virtual void insert(Map::Entry::View vEntry); 00101 00102 /** 00103 * {@inheritDoc} 00104 */ 00105 virtual void update(Map::Entry::View vEntry); 00106 00107 /** 00108 * {@inheritDoc} 00109 */ 00110 virtual void remove(Map::Entry::View vEntry); 00111 00112 protected: 00113 /** 00114 * Check the entry against the set of entries not included in the index and 00115 * update the set if necessary. 00116 * 00117 * @param vEntry the entry to be checked 00118 * @param fExclude true if the insert or update of the entry into the index 00119 * caused an exception 00120 */ 00121 void updateExcludedKeys(Map::Entry::View vEntry, bool fExclude); 00122 00123 /** 00124 * Check if the entry with the given key is excluded from the index. 00125 * 00126 * @param vKey the key to test 00127 * 00128 * @return true if the key is in the list of keys currently excluded 00129 * from the index, false if the entry with the key is in the index 00130 */ 00131 bool isKeyExcluded(Object::View vKey) const; 00132 00133 00134 // ----- Object interface ----------------------------------------------- 00135 00136 public: 00137 /** 00138 * {@inheritDoc} 00139 */ 00140 virtual bool equals(Object::View v) const; 00141 00142 /** 00143 * {@inheritDoc} 00144 */ 00145 virtual size32_t hashCode() const; 00146 00147 /** 00148 * {@inheritDoc} 00149 */ 00150 virtual TypedHandle<const String> toString() const; 00151 00152 00153 // ----- helpers -------------------------------------------------------- 00154 00155 protected: 00156 /** 00157 * Initialize the index's data structures. 00158 * 00159 * @param fForwardIndex specifies whether or not a forward index 00160 * map is supported, default is true 00161 */ 00162 virtual void init(bool fForwardIndex = true); 00163 00164 /** 00165 * Get the forward index entry associated with the specified key. 00166 * 00167 * @param vKey the key 00168 * 00169 * @return the entry associated with the given key. 00170 */ 00171 virtual Map::Entry::View getForwardEntry(Object::View vKey) const; 00172 00173 /** 00174 * Get the forward index entry associated with the specified key. 00175 * 00176 * @param vKey the key 00177 * 00178 * @return the entry associated with the given key. 00179 */ 00180 virtual Map::Entry::Handle getForwardEntry(Object::View vKey); 00181 00182 /** 00183 * Remove the forward index entry for the specified key. 00184 * 00185 * @param vKey the key to remove the forward index entry for 00186 */ 00187 void removeForwardEntry(Object::View vKey); 00188 00189 /** 00190 * Extract the "new" value from the specified entry. 00191 * 00192 * @param vEntry the entry to extract the "new" value from 00193 * 00194 * @return the extracted "new" value, or no_value if the extraction failed 00195 */ 00196 Object::Holder extractNewValue(Map::Entry::View vEntry); 00197 00198 /** 00199 * Extract the "old" value from the specified entry. 00200 * 00201 * @param vEntry the entry to extract the "old" value from 00202 * 00203 * @return the extracted "old" value, or no_value if the extraction failed 00204 */ 00205 Object::Holder extractOldValue(MapTrigger::Entry::View vEntry); 00206 00207 /** 00208 * Return a Collection representation of the specified value, which could be 00209 * a Collection, ObjectArray, scalar, or no_value. 00210 * 00211 * @param vValue the value 00212 * 00213 * @return a Collection representation of the specified value, or an empty 00214 * Collection if no_value 00215 */ 00216 Collection::View ensureCollection(Object::View vValue); 00217 00218 /** 00219 * Instantiate and initialize the forward index. 00220 * 00221 * Note: To optimize the memory footprint of the forward index, any 00222 * subclasses of the SimpleMapIndex that override this method must also 00223 * implement the #getForwardEntry(Object) method accordingly. 00224 * 00225 * @return the forward index. 00226 */ 00227 Map::Handle instantiateForwardIndex() const; 00228 00229 /** 00230 * Instantiate and initialize the inverse index. 00231 * 00232 * @param fOrdered true iff the contents of the indexed information 00233 * should be ordered; false otherwise 00234 * @param vComparator the Comparator object which imposes an ordering 00235 * on entries in the index map; or <tt>NULL</tt> 00236 * if the entries' values natural ordering should be 00237 * used 00238 * 00239 * @return the inverse index. 00240 */ 00241 virtual Map::Handle instantiateInverseIndex(bool fOrdered, 00242 Comparator::View vComparator) const; 00243 00244 /** 00245 * Add a new mapping from the given indexed value to the given key in the 00246 * inverse index. 00247 * 00248 * @param ohIxValue the indexed value (serves as a key in the inverse index) 00249 * @param vKey the key to insert into the inverse index 00250 * 00251 * @return an already existing reference that is "equal" to the specified 00252 * value (if available) 00253 */ 00254 virtual Object::Holder addInverseMapping(Object::Holder ohIxValue, 00255 Object::View vKey); 00256 00257 /** 00258 * Add a new mapping from the given indexed value to the given key in 00259 * the supplied index. 00260 * 00261 * @param hMapIndex the index to which to add the mapping 00262 * @param ohIxValue the indexed value 00263 * @param vKey the key 00264 * 00265 * @return an already existing reference that is "equal" to the specified 00266 * value (if available) 00267 */ 00268 virtual Object::Holder addInverseMapping(Map::Handle hMapIndex, 00269 Object::Holder ohIxValue, Object::View vKey); 00270 00271 /** 00272 * Add new mappings from the elements of the given value to the given key 00273 * in the supplied index. The given value is expected to be either a 00274 * Collection or an Object array. 00275 * 00276 * @param hMapIndex the index to which to add the mapping 00277 * @param ohIxValue the indexed Collection value (each element serves 00278 * as a key in the inverse index) 00279 * @param vKey the key to insert into the inverse index 00280 * 00281 * @return an already existing reference that is "equal" to the specified 00282 * value (if available) 00283 */ 00284 virtual Object::Holder addInverseCollectionMapping(Map::Handle hMapIndex, 00285 Object::Holder ohIxValue, Object::View vKey); 00286 00287 /** 00288 * Remove the mapping from the given indexed value to the given key from 00289 * the inverse index. 00290 * 00291 * @param ohIxValue the indexed value 00292 * @param vKey the key 00293 * @param vColIgnore the Collection of values to ignore (exclude from removal), or NULL 00294 */ 00295 virtual void removeInverseMapping(Object::Holder ohIxValue, Object::View vKey, 00296 Collection::View vColIgnore); 00297 00298 /** 00299 * Remove the mapping from the given indexed value to the given key from 00300 * the inverse index. 00301 * 00302 * @param ohIxValue the indexed value 00303 * @param vKey the key 00304 */ 00305 virtual void removeInverseMapping(Object::Holder ohIxValue, Object::View vKey); 00306 00307 /** 00308 * Remove the mapping from the given indexed value to the given key 00309 * from the supplied index. 00310 * 00311 * @param hMapIndex the index from which to remove the mapping 00312 * @param ohIxValue the indexed value 00313 * @param vKey the key 00314 */ 00315 virtual void removeInverseMapping(Map::Handle hMapIndex, 00316 Object::Holder ohIxValue, 00317 Object::View vKey); 00318 00319 /** 00320 * Update this index in response to a insert operation on a cache. 00321 * 00322 * @param vEntry the entry representing the object being inserted 00323 */ 00324 virtual void insertInternal(Map::Entry::View vEntry); 00325 00326 /** 00327 * Update this index in response to an update operation on a cache. 00328 * 00329 * @param vEntry the entry representing the object being updated 00330 */ 00331 virtual void updateInternal(Map::Entry::View vEntry); 00332 00333 /** 00334 * Update this index in response to a remove operation on a cache. 00335 * 00336 * @param vEntry the entry representing the object being removed 00337 */ 00338 virtual void removeInternal(Map::Entry::View vEntry); 00339 00340 /** 00341 * Log messages for missing inverse index. 00342 * 00343 * @param vIxValue the indexed value 00344 * @param vKey the key 00345 */ 00346 virtual void logMissingIdx(Object::View vIxValue, Object::View vKey); 00347 00348 /** 00349 * Given that the old value is known to be a Collection or an array, 00350 * collect all the enclosed elements that are not part of the new value. 00351 * 00352 * @param vIxValueOld the old value (must be a collection or an array) 00353 * @param vIxValueNew the new value 00354 * 00355 * @return the set of values that are contained in the old collection or array, 00356 * but not part of the new value 00357 */ 00358 virtual Set::Handle collectRemoved(Object::View vIxValueOld, Object::View vIxValueNew); 00359 00360 /** 00361 * Factory method used to create a new set containing the keys associated 00362 * with a single value. 00363 * 00364 * @return a Set 00365 */ 00366 virtual Set::Handle instantiateSet() const; 00367 00368 00369 // ----- data members --------------------------------------------------- 00370 00371 protected: 00372 /** 00373 * ValueExtractor object that this MapIndex uses to extract an 00374 * indexable Object from a [converted] value stored in the Storage. 00375 */ 00376 FinalView<ValueExtractor> f_vValueExtractor; 00377 00378 /** 00379 * Specifies whether or not this MapIndex orders the contents of the 00380 * indexed information. 00381 */ 00382 const bool m_fOrdered; 00383 00384 /** 00385 * Comparator used to sort the index. Used iff the Ordered is true. 00386 * Could be null, which implicates a natural order. 00387 */ 00388 FinalView<Comparator> f_vComparator; 00389 00390 /** 00391 * Map that contains the index values (forward index). The keys of the 00392 * Map are the keys to the ResourceMap and the values are the extracted 00393 * values. This map is used by the IndexAwareComparators to avoid a 00394 * conversion and value extraction steps. 00395 */ 00396 FinalHandle<Map> f_hMapForward; 00397 00398 /** 00399 * Map that contains the index contents (inverse index). The keys of 00400 * the Map are the return values from the ValueExtractor operating 00401 * against the values of the resource map, and for each key, the 00402 * corresponding value stored in the Map is a Set of keys to the 00403 * resource map. 00404 */ 00405 FinalHandle<Map> f_hMapInverse; 00406 00407 /** 00408 * If a value extracted by the ValueExtractor is a Collection, this 00409 * property specifies whether or not it should be treated as a 00410 * collection of contained attributes or indexed as a single composite 00411 * attribute. 00412 */ 00413 const bool m_fSplitCollection; 00414 00415 /** 00416 * The time at which the most recent logging of "missing inverse index" 00417 * messages started. 00418 */ 00419 int64_t m_ldtLogMissingIdx; 00420 00421 /** 00422 * The number of "missing inverse index" messages that have been logged. 00423 */ 00424 int m_cLogMissingIdx; 00425 00426 /** 00427 * A set of keys for the entries, which could not be included in the index. 00428 */ 00429 FinalHandle<Set> f_hSetKeyExcluded; 00430 00431 /** 00432 * Specifies whether or not index updates are permitted(immutable values). 00433 * 00434 * @since Coherence 12.2.1 00435 */ 00436 const bool m_fImmutableValues; 00437 }; 00438 00439 COH_CLOSE_NAMESPACE2 00440 00441 #endif // COH_SIMPLE_MAP_INDEX_HPP