Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/QueryMap.hpp

    00001 /*
    00002 * QueryMap.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_QUERY_MAP_HPP
    00017 #define COH_QUERY_MAP_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/Set.hpp"
    00025 #include "coherence/util/ValueExtractor.hpp"
    00026
    00027 COH_OPEN_NAMESPACE2(coherence,util)
    00028
    00029
    00030 /**
    00031 * Map with additional query features.
    00032 *
    00033 * @author jh  2008.02.27
    00034 */
    00035 class COH_EXPORT QueryMap
    00036     : public interface_spec<QueryMap,
    00037         implements<Map> >
    00038     {
    00039     // ----- QueryMap interface ---------------------------------------------
    00040
    00041     public:
    00042         /**
    00043         * Return a set of the keys contained in this map for entries that
    00044         * satisfy the criteria expressed by the filter.
    00045         *
    00046         * Unlike the {@link Map#keySet()} method, the set returned by this
    00047         * method may not be backed by the map, so changes to the set may not
    00048         * reflected in the map, and vice-versa.
    00049         *
    00050         * @param vFilter  the Filter object representing the criteria that
    00051         *                 the entries of this map should satisfy
    00052         *
    00053         * @return a set of keys for entries that satisfy the specified
    00054         *         criteria
    00055         */
    00056         virtual Set::View keySet(Filter::View vFilter) const = 0;
    00057
    00058         /**
    00059         * Return a set of the entries contained in this map that satisfy the
    00060         * criteria expressed by the filter. Each element in the returned set
    00061         * is a Map::Entry.
    00062         *
    00063         * Unlike the Map#entrySet() method, the set returned by this
    00064         * method may not be backed by the map, so changes to the set may not
    00065         * be reflected in the map, and vice-versa.
    00066         *
    00067         * @param vFilter  the Filter object representing the criteria that
    00068         *                the entries of this map should satisfy
    00069         *
    00070         * @return a set of entries that satisfy the specified criteria
    00071         */
    00072         virtual Set::View entrySet(Filter::View vFilter) const = 0;
    00073
    00074         /**
    00075         * Return a set of the entries contained in this map that satisfy the
    00076         * criteria expressed by the filter. Each element in the returned set
    00077         * is a Map::Entry. It is further guaranteed that its iterator will
    00078         * traverse the set in such a way that the entry values come up
    00079         * in ascending order, sorted by the specified Comparator or
    00080         * according to the <i>natural ordering</i> (see Comparable).
    00081         *
    00082         * Unlike the Map#entrySet() method, the set returned by this
    00083         * method may not be backed by the map, so changes to the set may not
    00084         * be reflected in the map, and vice-versa.
    00085         *
    00086         * @param vFilter      the Filter object representing the criteria
    00087         *                     that the entries of this map should satisfy
    00088         * @param vComparator  the Comparator object which imposes an ordering
    00089         *                     on entries in the resulting set; or
    00090         *                     <tt>NULL</tt> if the entries' values natural
    00091         *                     ordering should be used
    00092         *
    00093         * @return a set of entries that satisfy the specified criteria
    00094         */
    00095         virtual Set::View entrySet(Filter::View vFilter,
    00096                 Comparator::View vComparator) const = 0;
    00097
    00098         /**
    00099         * Add an index to this QueryMap. This allows to correlate values
    00100         * stored in this <i>indexed Map</i> (or attributes of those values)
    00101         * to the corresponding keys in the indexed Map and increase the
    00102         * performance of <tt>keySet</tt> and <tt>entrySet</tt> methods.
    00103         *
    00104         * This method is only intended as a hint to the cache implementation,
    00105         * and as such it may be ignored by the cache if indexes are not
    00106         * supported or if the desired index (or a similar index) already
    00107         * exists. It is expected that an application will call this method to
    00108         * suggest an index even if the index may already exist, just so that
    00109         * the application is certain that index has been suggested. For
    00110         * example in a distributed environment, each server will likely
    00111         * suggest the same set of indexes when it starts, and there is no
    00112         * downside to the application blindly requesting those indexes
    00113         * regardless of whether another server has already requested the same
    00114         * indexes.
    00115         *
    00116         * @param vExtractor   the ValueExtractor object that is used to
    00117         *                     extract an indexable Object from a value stored
    00118         *                     in the indexed Map.  Must not be <tt>NULL</tt>.
    00119         * @param fOrdered     true iff the contents of the indexed
    00120         *                     information should be ordered; false otherwise
    00121         * @param vComparator  the Comparator object which imposes an ordering
    00122         *                     on entries in the indexed map; or <tt>NULL</tt>
    00123         *                     if the entries' values natural ordering should
    00124         *                     be used
    00125         */
    00126         virtual void addIndex(ValueExtractor::View vExtractor, bool fOrdered,
    00127                 Comparator::View vComparator) = 0;
    00128
    00129         /**
    00130         * Remove an index from this QueryMap.
    00131         *
    00132         * @param vExtractor  the ValueExtractor object that is used to
    00133         *                    extract an indexable Object from a value stored
    00134         *                    in the Map
    00135         */
    00136         virtual void removeIndex(ValueExtractor::View vExtractor) = 0;
    00137
    00138
    00139     // ----- Map interface --------------------------------------------------
    00140
    00141     public:
    00142         /**
    00143         * {@inheritDoc}
    00144         */
    00145         using Map::keySet;
    00146
    00147         /**
    00148         * {@inheritDoc}
    00149         */
    00150         using Map::entrySet;
    00151
    00152
    00153     // ----- inner interface: Entry -----------------------------------------
    00154
    00155     public:
    00156         /**
    00157         * A QueryMap::Entry exposes additional index-related operation that
    00158         * the basic Map::Entry does not.
    00159         */
    00160         class COH_EXPORT Entry
    00161             : public interface_spec<Entry,
    00162                 implements<Map::Entry> >
    00163             {
    00164             // ----- QueryMap::Entry interface --------------------------
    00165
    00166             public:
    00167                 /**
    00168                 * Extract a value out of the Entry's value. Calling this
    00169                 * method is semantically equivalent to
    00170                 * <tt>vExtractor->extract(getValue())</tt>, but this method
    00171                 * may be significantly less expensive. For example, the
    00172                 * resultant value may be obtained from a forward index,
    00173                 * avoiding a potential object de-serialization.
    00174                 *
    00175                 * @param vExtractor  a ValueExtractor to apply to the Entry's
    00176                 *                    value
    00177                 *
    00178                 * @return the extracted value
    00179                 */
    00180                 virtual Object::Holder extract(
    00181                         ValueExtractor::View vExtractor) const = 0;
    00182             };
    00183     };
    00184
    00185 COH_CLOSE_NAMESPACE2
    00186
    00187 #endif // COH_QUERY_MAP_HPP

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.