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