00001 /* 00002 * QueryMap.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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