00001 /* 00002 * SimpleMapIndex.hpp 00003 * 00004 * Copyright (c) 2000, 2011, 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/Set.hpp" 00026 #include "coherence/util/ValueExtractor.hpp" 00027 00028 COH_OPEN_NAMESPACE2(coherence,util) 00029 00030 00031 /** 00032 * SimpleMapIndex is a MapIndex implementation used to correlate property values 00033 * extracted from resource map entries with corresponding keys using what is 00034 * commonly known as an <i>Inverted Index algorithm.</i>. 00035 * 00036 * @author tb 2009.02.09 00037 * @since Coherence 3.5 00038 */ 00039 class COH_EXPORT SimpleMapIndex 00040 : public class_spec<SimpleMapIndex, 00041 extends<Object>, 00042 implements<MapIndex> > 00043 { 00044 friend class factory<SimpleMapIndex>; 00045 00046 // ----- constructors --------------------------------------------------- 00047 00048 protected: 00049 /** 00050 * Construct an index from the given map. 00051 * 00052 * @param vExtractor the ValueExtractor object that is used to 00053 * extract an indexable Object from a value stored 00054 * in the indexed Map. Must not be NULL. 00055 * @param fOrdered true iff the contents of the indexed information 00056 * should be ordered; false otherwise 00057 * @param vComparator the Comparator object which imposes an ordering 00058 * on entries in the indexed map; or <tt>NULL</tt> 00059 * if the entries' values natural ordering should 00060 * be used 00061 * @param fInit initialize the index if true, default is true 00062 */ 00063 SimpleMapIndex(ValueExtractor::View vExtractor, bool fOrdered, 00064 Comparator::View vComparator, bool fInit = true); 00065 00066 00067 // ----- MapIndex interface --------------------------------------------- 00068 00069 public: 00070 /** 00071 * {@inheritDoc} 00072 */ 00073 virtual ValueExtractor::View getValueExtractor() const; 00074 00075 /** 00076 * {@inheritDoc} 00077 */ 00078 virtual bool isOrdered() const; 00079 00080 /** 00081 * {@inheritDoc} 00082 */ 00083 virtual bool isPartial() const; 00084 00085 /** 00086 * {@inheritDoc} 00087 */ 00088 virtual Map::View getIndexContents() const; 00089 00090 /** 00091 * {@inheritDoc} 00092 */ 00093 virtual Object::Holder get(Object::View vKey) const; 00094 00095 /** 00096 * {@inheritDoc} 00097 */ 00098 virtual Object::Holder get(Object::View vKey); 00099 00100 /** 00101 * {@inheritDoc} 00102 */ 00103 virtual Comparator::View getComparator() const; 00104 00105 /** 00106 * {@inheritDoc} 00107 */ 00108 virtual void insert(Map::Entry::View vEntry); 00109 00110 /** 00111 * {@inheritDoc} 00112 */ 00113 virtual void update(Map::Entry::View vEntry); 00114 00115 /** 00116 * {@inheritDoc} 00117 */ 00118 virtual void remove(Map::Entry::View vEntry); 00119 00120 00121 // ----- Object interface ----------------------------------------------- 00122 00123 public: 00124 /** 00125 * {@inheritDoc} 00126 */ 00127 virtual bool equals(Object::View v) const; 00128 00129 /** 00130 * {@inheritDoc} 00131 */ 00132 virtual size32_t hashCode() const; 00133 00134 /** 00135 * {@inheritDoc} 00136 */ 00137 virtual void toStream(std::ostream& out) const; 00138 00139 00140 // ----- helpers -------------------------------------------------------- 00141 00142 protected: 00143 /** 00144 * Initialize the index's data structures. 00145 * 00146 * @param fForwardIndex specifies whether or not a forward index 00147 * map is supported, default is true 00148 */ 00149 virtual void init(bool fForwardIndex = true); 00150 00151 /** 00152 * Get the forward index entry associated with the specified key. 00153 * 00154 * @param vKey the key 00155 * 00156 * @return the entry associated with the given key. 00157 */ 00158 virtual Map::Entry::View getForwardEntry(Object::View vKey) const; 00159 00160 /** 00161 * Get the forward index entry associated with the specified key. 00162 * 00163 * @param vKey the key 00164 * 00165 * @return the entry associated with the given key. 00166 */ 00167 virtual Map::Entry::Handle getForwardEntry(Object::View vKey); 00168 00169 /** 00170 * Instantiate and initialize the forward index. 00171 * <p/> 00172 * Note: To optimize the memory footprint of the forward index, any 00173 * subclasses of the SimpleMapIndex that override this method must also 00174 * implement the #getForwardEntry(Object) method accordingly. 00175 * 00176 * @return the forward index. 00177 */ 00178 Map::Handle instantiateForwardIndex() const; 00179 00180 /** 00181 * Instantiate and initialize the inverse index. 00182 * 00183 * @param fOrdered true iff the contents of the indexed information 00184 * should be ordered; false otherwise 00185 * @param vComparator the Comparator object which imposes an ordering 00186 * on entries in the index map; or <tt>NULL</tt> 00187 * if the entries' values natural ordering should be 00188 * used 00189 * 00190 * @return the inverse index. 00191 */ 00192 virtual Map::Handle instantiateInverseIndex(bool fOrdered, 00193 Comparator::View vComparator) const; 00194 00195 /** 00196 * Add a new mapping from the given indexed value to the given key in the 00197 * inverse index. 00198 * 00199 * @param ohIxValue the indexed value (serves as a key in the inverse index) 00200 * @param vKey the key to insert into the inverse index 00201 * 00202 * @return an already existing reference that is "equal" to the specified 00203 * value (if available) 00204 */ 00205 virtual Object::Holder addInverseMapping(Object::Holder ohIxValue, 00206 Object::View vKey); 00207 00208 /** 00209 * Add a new mapping from the given indexed value to the given key in 00210 * the supplied index. 00211 * 00212 * @param hMapIndex the index to which to add the mapping 00213 * @param ohIxValue the indexed value 00214 * @param vKey the key 00215 * 00216 * @return an already existing reference that is "equal" to the specified 00217 * value (if available) 00218 */ 00219 virtual Object::Holder addInverseMapping(Map::Handle hMapIndex, 00220 Object::Holder ohIxValue, Object::View vKey); 00221 00222 /** 00223 * Add new mappings from the elements of the given value to the given key 00224 * in the supplied index. The given value is expected to be either a 00225 * Collection or an Object array. 00226 * 00227 * @param hMapIndex the index to which to add the mapping 00228 * @param ohIxValue the indexed Collection value (each element serves 00229 * as a key in the inverse index) 00230 * @param vKey the key to insert into the inverse index 00231 * 00232 * @return an already existing reference that is "equal" to the specified 00233 * value (if available) 00234 */ 00235 virtual Object::Holder addInverseCollectionMapping(Map::Handle hMapIndex, 00236 Object::Holder ohIxValue, Object::View vKey); 00237 00238 /** 00239 * Remove the mapping from the given indexed value to the given key from 00240 * the inverse index. 00241 * 00242 * @param ohIxValue the indexed value 00243 * @param vKey the key 00244 */ 00245 virtual void removeInverseMapping(Object::Holder ohIxValue, Object::View vKey); 00246 00247 /** 00248 * Remove the mapping from the given indexed value to the given key 00249 * from the supplied index. 00250 * 00251 * @param hMapIndex the index from which to remove the mapping 00252 * @param ohIxValue the indexed value 00253 * @param vKey the key 00254 */ 00255 virtual void removeInverseMapping(Map::Handle hMapIndex, 00256 Object::Holder ohIxValue, 00257 Object::View vKey); 00258 00259 /** 00260 * Update this index in response to a insert operation on a cache. 00261 * 00262 * @param vEntry the entry representing the object being inserted 00263 */ 00264 virtual void insertInternal(Map::Entry::View vEntry); 00265 00266 /** 00267 * Update this index in response to an update operation on a cache. 00268 * 00269 * @param vEntry the entry representing the object being updated 00270 */ 00271 virtual void updateInternal(Map::Entry::View vEntry); 00272 00273 /** 00274 * Update this index in response to a remove operation on a cache. 00275 * 00276 * @param vEntry the entry representing the object being removed 00277 */ 00278 virtual void removeInternal(Map::Entry::View vEntry); 00279 00280 /** 00281 * Factory method used to create a new set containing the keys associated 00282 * with a single value. 00283 * 00284 * @return a Set 00285 */ 00286 virtual Set::Handle instantiateSet() const; 00287 00288 00289 // ----- data members --------------------------------------------------- 00290 00291 protected: 00292 /** 00293 * ValueExtractor object that this MapIndex uses to extract an 00294 * indexable Object from a [converted] value stored in the Storage. 00295 */ 00296 FinalView<ValueExtractor> m_vValueExtractor; 00297 00298 /** 00299 * Specifies whether or not this MapIndex orders the contents of the 00300 * indexed information. 00301 */ 00302 const bool m_fOrdered; 00303 00304 /** 00305 * Comparator used to sort the index. Used iff the Ordered is true. 00306 * Could be null, which implicates a natural order. 00307 */ 00308 FinalView<Comparator> m_vComparator; 00309 00310 /** 00311 * Map that contains the index values (forward index). The keys of the 00312 * Map are the keys to the ResourceMap and the values are the extracted 00313 * values. This map is used by the IndexAwareComparators to avoid a 00314 * conversion and value extraction steps. 00315 */ 00316 FinalHandle<Map> m_hMapForward; 00317 00318 /** 00319 * Map that contains the index contents (inverse index). The keys of 00320 * the Map are the return values from the ValueExtractor operating 00321 * against the values of the resource map, and for each key, the 00322 * corresponding value stored in the Map is a Set of keys to the 00323 * resource map. 00324 */ 00325 FinalHandle<Map> m_hMapInverse; 00326 00327 /** 00328 * If a value extracted by the ValueExtractor is a Collection, this 00329 * property specifies whether or not it should be treated as a 00330 * collection of contained attributes or indexed as a single composite 00331 * attribute. 00332 */ 00333 const bool m_fSplitCollection; 00334 }; 00335 00336 COH_CLOSE_NAMESPACE2 00337 00338 #endif // COH_SIMPLE_MAP_INDEX_HPP