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