00001 /* 00002 * IndexAwareFilter.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_INDEX_AWARE_FILTER_HPP 00017 #define COH_INDEX_AWARE_FILTER_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Map.hpp" 00022 #include "coherence/util/Set.hpp" 00023 #include "coherence/util/filter/EntryFilter.hpp" 00024 00025 COH_OPEN_NAMESPACE3(coherence,util,filter) 00026 00027 00028 /** 00029 * IndexAwareFilter is an extension to the EntryFilter interface that allows 00030 * a filter to use a Map index to fully or partially evaluate itself. 00031 * 00032 * @author tb 2009.02.09 00033 */ 00034 class COH_EXPORT IndexAwareFilter 00035 : public interface_spec<IndexAwareFilter, 00036 implements<EntryFilter> > 00037 { 00038 // ----- IndexAwareFilter interface ------------------------------------- 00039 00040 public: 00041 /** 00042 * Given a Map of available indexes, determine if this IndexAwareFilter 00043 * can use any of the indexes to assist in its processing, and if so, 00044 * determine how effective the use of that index would be. 00045 * The returned value is an effectiveness estimate of how well this 00046 * filter can use the specified indexes to filter the specified keys. 00047 * An operation that requires no more than a single access to the index 00048 * content (i.e. Equals, NotEquals) has an effectiveness of <b>one</b>. 00049 * Evaluation of a single entry is assumed to have an effectiveness 00050 * that depends on the index implementation and is usually measured as 00051 * a constant number of the single operations. This number is referred 00052 * to as <i>evaluation cost</i>. 00053 * 00054 * If the effectiveness of a filter evaluates to a number larger than 00055 * the <tt>keySet.size() * <evaluation cost></tt> then a user 00056 * could avoid using the index and iterate through the keySet calling 00057 * <tt>evaluate</tt> rather then <tt>applyIndex</tt>. 00058 * 00059 * @param vMapIndexes the available MapIndex objects keyed by 00060 * the related ValueExtractor; read-only 00061 * @param vSetKeys the set of keys that will be filtered; read-only 00062 * 00063 * @return an effectiveness estimate of how well this filter can use 00064 * the specified indexes to filter the specified keys 00065 */ 00066 virtual size32_t calculateEffectiveness(Map::View vMapIndexes, 00067 Set::View vSetKeys) const = 0; 00068 00069 /** 00070 * Filter remaining keys using a Map of available indexes. 00071 * The filter is responsible for removing all keys from the passed set 00072 * of keys that the applicable indexes can prove should be filtered. If 00073 * the filter does not fully evaluate the remaining keys using just the 00074 * index information, it must return a filter (which may be an 00075 * EntryFilter) that can complete the task using an iterating 00076 * implementation. If, on the other hand, the filter does fully 00077 * evaluate the remaining keys using just the index information, then 00078 * it should return NULL to indicate that no further filtering is 00079 * necessary. 00080 * 00081 * @param vMapIndexes the available MapIndex objects keyed by 00082 * the related ValueExtractor; read-only 00083 * @param hSetKeys the mutable set of keys that remain to be 00084 * filtered 00085 * 00086 * @return a Filter object (which may be an EntryFilter) that can be 00087 * used to process the remaining keys, or NULL if no additional 00088 * filter processing is necessary 00089 */ 00090 virtual Filter::View applyIndex(Map::View vMapIndexes, 00091 Set::Handle hSetKeys) const = 0; 00092 }; 00093 00094 COH_CLOSE_NAMESPACE3 00095 00096 #endif // COH_INDEX_AWARE_FILTER_HPP