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