00001 /* 00002 * SimpleMapIndex.hpp 00003 * 00004 * Copyright (c) 2000, 2010, 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 virtual void init(); 00147 00148 /** 00149 * Get the forward index entry associated with the specified key. 00150 * 00151 * @param vKey the key 00152 * 00153 * @return the entry associated with the given key. 00154 */ 00155 virtual Map::Entry::View getForwardEntry(Object::View vKey) const; 00156 00157 /** 00158 * Get the forward index entry associated with the specified key. 00159 * 00160 * @param vKey the key 00161 * 00162 * @return the entry associated with the given key. 00163 */ 00164 virtual Map::Entry::Handle getForwardEntry(Object::View vKey); 00165 00166 /** 00167 * Instantiate and initialize the forward index. 00168 * <p/> 00169 * Note: To optimize the memory footprint of the forward index, any 00170 * subclasses of the SimpleMapIndex that override this method must also 00171 * implement the #getForwardEntry(Object) method accordingly. 00172 * 00173 * @return the forward index. 00174 */ 00175 Map::Handle instantiateForwardIndex() const; 00176 00177 /** 00178 * Instantiate and initialize the inverse index. 00179 * 00180 * @param fOrdered true iff the contents of the indexed information 00181 * should be ordered; false otherwise 00182 * @param vComparator the Comparator object which imposes an ordering 00183 * on entries in the index map; or <tt>NULL</tt> 00184 * if the entries' values natural ordering should be 00185 * used 00186 * 00187 * @return the inverse index. 00188 */ 00189 virtual Map::Handle instantiateInverseIndex(bool fOrdered, 00190 Comparator::View vComparator) const; 00191 00192 /** 00193 * Add a new mapping from the given indexed value to the given key in the 00194 * inverse index. 00195 * 00196 * @param ohIxValue the indexed value (serves as a key in the inverse index) 00197 * @param vKey the key to insert into the inverse index 00198 * 00199 * @return an already existing reference that is "equal" to the specified 00200 * value (if available) 00201 */ 00202 virtual Object::Holder addInverseMapping(Object::Holder ohIxValue, 00203 Object::View vKey); 00204 00205 /** 00206 * Add a new mapping from the given indexed value to the given key in 00207 * the supplied index. 00208 * 00209 * @param hMapIndex the index to which to add the mapping 00210 * @param ohIxValue the indexed value 00211 * @param vKey the key 00212 * 00213 * @return an already existing reference that is "equal" to the specified 00214 * value (if available) 00215 */ 00216 virtual Object::Holder addInverseMapping(Map::Handle hMapIndex, 00217 Object::Holder ohIxValue, Object::View vKey); 00218 00219 /** 00220 * Add new mappings from the elements of the given value to the given key 00221 * in the supplied index. The given value is expected to be either a 00222 * Collection or an Object array. 00223 * 00224 * @param hMapIndex the index to which to add the mapping 00225 * @param ohIxValue the indexed Collection value (each element serves 00226 * as a key in the inverse index) 00227 * @param vKey the key to insert into the inverse index 00228 * 00229 * @return an already existing reference that is "equal" to the specified 00230 * value (if available) 00231 */ 00232 virtual Object::Holder addInverseCollectionMapping(Map::Handle hMapIndex, 00233 Object::Holder ohIxValue, Object::View vKey); 00234 00235 /** 00236 * Remove the mapping from the given indexed value to the given key from 00237 * the inverse index. 00238 * 00239 * @param ohIxValue the indexed value 00240 * @param vKey the key 00241 */ 00242 virtual void removeInverseMapping(Object::Holder ohIxValue, Object::View vKey); 00243 00244 /** 00245 * Remove the mapping from the given indexed value to the given key 00246 * from the supplied index. 00247 * 00248 * @param hMapIndex the index from which to remove the mapping 00249 * @param ohIxValue the indexed value 00250 * @param vKey the key 00251 */ 00252 virtual void removeInverseMapping(Map::Handle hMapIndex, 00253 Object::Holder ohIxValue, 00254 Object::View vKey); 00255 00256 /** 00257 * Update this index in response to a insert operation on a cache. 00258 * 00259 * @param vEntry the entry representing the object being inserted 00260 */ 00261 virtual void insertInternal(Map::Entry::View vEntry); 00262 00263 /** 00264 * Update this index in response to an update operation on a cache. 00265 * 00266 * @param vEntry the entry representing the object being updated 00267 */ 00268 virtual void updateInternal(Map::Entry::View vEntry); 00269 00270 /** 00271 * Update this index in response to a remove operation on a cache. 00272 * 00273 * @param vEntry the entry representing the object being removed 00274 */ 00275 virtual void removeInternal(Map::Entry::View vEntry); 00276 00277 /** 00278 * Factory method used to create a new set containing the keys associated 00279 * with a single value. 00280 * 00281 * @return a Set 00282 */ 00283 virtual Set::Handle instantiateSet() const; 00284 00285 00286 // ----- data members --------------------------------------------------- 00287 00288 protected: 00289 /** 00290 * ValueExtractor object that this MapIndex uses to extract an 00291 * indexable Object from a [converted] value stored in the Storage. 00292 */ 00293 FinalView<ValueExtractor> m_vValueExtractor; 00294 00295 /** 00296 * Specifies whether or not this MapIndex orders the contents of the 00297 * indexed information. 00298 */ 00299 const bool m_fOrdered; 00300 00301 /** 00302 * Comparator used to sort the index. Used iff the Ordered is true. 00303 * Could be null, which implicates a natural order. 00304 */ 00305 FinalView<Comparator> m_vComparator; 00306 00307 /** 00308 * Map that contains the index values (forward index). The keys of the 00309 * Map are the keys to the ResourceMap and the values are the extracted 00310 * values. This map is used by the IndexAwareComparators to avoid a 00311 * conversion and value extraction steps. 00312 */ 00313 FinalHandle<Map> m_hMapForward; 00314 00315 /** 00316 * Map that contains the index contents (inverse index). The keys of 00317 * the Map are the return values from the ValueExtractor operating 00318 * against the values of the resource map, and for each key, the 00319 * corresponding value stored in the Map is a Set of keys to the 00320 * resource map. 00321 */ 00322 FinalHandle<Map> m_hMapInverse; 00323 00324 /** 00325 * If a value extracted by the ValueExtractor is a Collection, this 00326 * property specifies whether or not it should be treated as a 00327 * collection of contained attributes or indexed as a single composite 00328 * attribute. 00329 */ 00330 const bool m_fSplitCollection; 00331 }; 00332 00333 COH_CLOSE_NAMESPACE2 00334 00335 #endif // COH_SIMPLE_MAP_INDEX_HPP