C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/util/filter/IndexAwareFilter.hpp

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() * &lt;evaluation cost&gt;</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
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.