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_LIMIT_FILTER_HPP 00008 #define COH_LIMIT_FILTER_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/io/pof/PortableObject.hpp" 00013 #include "coherence/io/pof/PofReader.hpp" 00014 #include "coherence/io/pof/PofWriter.hpp" 00015 #include "coherence/util/Comparator.hpp" 00016 #include "coherence/util/Filter.hpp" 00017 #include "coherence/util/Map.hpp" 00018 #include "coherence/util/Set.hpp" 00019 #include "coherence/util/filter/EntryFilter.hpp" 00020 #include "coherence/util/filter/IndexAwareFilter.hpp" 00021 00022 COH_OPEN_NAMESPACE3(coherence,util,filter) 00023 00024 using coherence::io::pof::PortableObject; 00025 using coherence::io::pof::PofReader; 00026 using coherence::io::pof::PofWriter; 00027 00028 /** 00029 * Filter which truncates the results of another filter. This filter is a 00030 * mutable object that is modified by the query processor. Clients are 00031 * supposed to hold a reference to this filter and repetitively pass it to 00032 * query methods after setting a desired page context calling 00033 * #setPage, #nextPage(), or #previousPage. 00034 * 00035 * @author djl 2008.04.14 00036 */ 00037 class COH_EXPORT LimitFilter 00038 : public cloneable_spec<LimitFilter, 00039 extends<Object>, 00040 implements<IndexAwareFilter, PortableObject> > 00041 { 00042 friend class factory<LimitFilter>; 00043 00044 // ----- constructors --------------------------------------------------- 00045 00046 protected: 00047 /** 00048 * Default constructor (necessary for the PortableObject interface). 00049 */ 00050 LimitFilter(); 00051 00052 /** 00053 * Construct a LimitFilter filter. 00054 * 00055 * @param vFilter the filter whose results this Filter truncates 00056 * @param cPageSize the sie of the page 00057 */ 00058 LimitFilter(Filter::View vFilter, int32_t cPageSize); 00059 00060 /** 00061 * Copy constructor. 00062 */ 00063 LimitFilter(const LimitFilter& that); 00064 00065 00066 // ----- Entry Filter interface ----------------------------------------- 00067 00068 public: 00069 /** 00070 * {@inheritDoc} 00071 */ 00072 virtual bool evaluateEntry(Map::Entry::View vEntry) const; 00073 00074 00075 // ----- Filter interface ----------------------------------------------- 00076 00077 public: 00078 /** 00079 * {@inheritDoc} 00080 */ 00081 virtual bool evaluate(Object::View v) const; 00082 00083 00084 // ----- IndexAwareFilter interface ------------------------------------- 00085 00086 public: 00087 /** 00088 * {@inheritDoc} 00089 */ 00090 virtual size32_t calculateEffectiveness(Map::View vMapIndexes, 00091 Set::View vSetKeys) const; 00092 00093 /** 00094 * {@inheritDoc} 00095 */ 00096 virtual Filter::View applyIndex(Map::View vMapIndexes, 00097 Set::Handle hSetKeys) const; 00098 00099 00100 // ----- PortableObject interface --------------------------------------- 00101 00102 public: 00103 /** 00104 * {@inheritDoc} 00105 */ 00106 virtual void readExternal(PofReader::Handle hIn); 00107 00108 /** 00109 * {@inheritDoc} 00110 */ 00111 virtual void writeExternal(PofWriter::Handle hOut) const; 00112 00113 00114 // ----- Object interface ----------------------------------------------- 00115 00116 public: 00117 /** 00118 * Output a human-readable description of this Object to the given 00119 * stream. 00120 * 00121 * @param out the stream used to output the description 00122 */ 00123 virtual TypedHandle<const String> toString() const; 00124 00125 00126 // ----- data member accessors ------------------------------------------ 00127 00128 public: 00129 /** 00130 * Obtain the Filter whose results are truncated by this filter. 00131 * 00132 * @return the filter whose results are truncated by this filter 00133 */ 00134 virtual Filter::View getFilter() const; 00135 00136 /** 00137 * Obtain the page size (expressed as a number of entries per page). 00138 * 00139 * @return the page size 00140 */ 00141 virtual int32_t getPageSize() const; 00142 00143 /** 00144 * Set the page size (expressed as a number of entries per page). 00145 * 00146 * @param cPageSize the page size 00147 */ 00148 virtual void setPageSize(int32_t cPageSize); 00149 00150 /** 00151 * Obtain a current page number (zero-based). 00152 * 00153 * @return the page number 00154 */ 00155 virtual int32_t getPage() const; 00156 00157 /** 00158 * Set the page number (zero-based). Setting the page number to zero 00159 * will reset the filter's state. 00160 * 00161 * @param nPage the page number 00162 */ 00163 virtual void setPage(int32_t nPage); 00164 00165 /** 00166 * Obtain the Comparator used to partition the entry values into 00167 * pages. 00168 * 00169 * This method is intended to be used only by query processors. 00170 * Clients should not modify the content of this property. 00171 * 00172 * @return the Comparator object 00173 */ 00174 virtual Comparator::View getComparator() const; 00175 00176 /** 00177 * Set the Comparator used to partition the values into pages. 00178 * 00179 * This method is intended to be used only by query processors. 00180 * Clients should not modify the content of this property. 00181 * 00182 * @param vComparator Comparator object 00183 */ 00184 virtual void setComparator(Comparator::View vComparator) const; 00185 00186 /** 00187 * Obtain the top anchor object, which is the last value object 00188 * on a previous page. 00189 * 00190 * This method is intended to be used only by query processors. 00191 * Clients 00192 * should not modify the content of this property. 00193 * 00194 * @return top anchor object 00195 */ 00196 virtual Object::View getTopAnchor() const; 00197 00198 /** 00199 * Set the top anchor object. 00200 * 00201 * This method is intended to be used only by query processors. 00202 * Clients should not modify the content of this property. 00203 * 00204 * @param vAnchor the top anchor object 00205 */ 00206 virtual void setTopAnchor(Object::View vAnchor) const; 00207 00208 /** 00209 * Obtain the bottom anchor object, which is the last value object 00210 * on the current page. 00211 * 00212 * This method is intended to be used only by query processors. 00213 * Clients should not modify the content of this property. 00214 * 00215 * @return bottom anchor object 00216 */ 00217 virtual Object::View getBottomAnchor() const; 00218 00219 /** 00220 * Set the bottom anchor object. 00221 * 00222 * This method is intended to be used only by query processors. 00223 * Clients 00224 * should not modify the content of this property. 00225 * 00226 * @param vAnchor the bottom anchor object 00227 */ 00228 virtual void setBottomAnchor(Object::View vAnchor) const; 00229 00230 /** 00231 * Obtain the cookie object. 00232 * 00233 * This method is intended to be used only by query processors. 00234 * Clients should not modify the content of this property. 00235 * 00236 * @return cookie object 00237 */ 00238 virtual Object::View getCookie() const; 00239 00240 /** 00241 * Set the cookie object. 00242 * 00243 * This method is intended to be used only by query processors. 00244 * Clients should not modify the content of this property. 00245 * 00246 * @param vCookie the cookie object 00247 */ 00248 virtual void setCookie(Object::View vCookie) const; 00249 00250 00251 // ----- helpers -------------------------------------------------------- 00252 00253 public: 00254 /** 00255 * Switch to the next page. 00256 */ 00257 virtual void nextPage(); 00258 00259 /** 00260 * Switch to the previous page. 00261 */ 00262 virtual void previousPage(); 00263 00264 /** 00265 * Extract a subset of the specified array to fit the filter's 00266 * parameters (i.e. page size and page number). If this filter has a 00267 * comparator, the specified array is presumed to be sorted 00268 * accordingly. 00269 * 00270 * The returned array is guaranteed to iterate exactly in the same 00271 * order as the original array. 00272 * 00273 * @param haEntry an original array of entries 00274 * 00275 * @return an array of entries extracted accordingly to the filter 00276 * parameters 00277 */ 00278 virtual ObjectArray::Handle extractPage(ObjectArray::Handle haEntry) const; 00279 00280 /** 00281 * Extract a subset of the specified iterator to fit the filter's 00282 * parameters (i.e. page size and page number). The returned array is 00283 * guaranteed to iterate exactly in the same order as the original 00284 * iterator. 00285 * 00286 * @param hIter an original entry iterator 00287 * 00288 * @return an array of entries extracted accordingly to the filter 00289 * parameters 00290 */ 00291 virtual ObjectArray::Handle extractPage(Iterator::Handle hIter) const; 00292 00293 00294 // ----- data members --------------------------------------------------- 00295 00296 private: 00297 /** 00298 * The Filter whose results are truncated by this filter. 00299 */ 00300 FinalView<Filter> f_vFilter; 00301 00302 /** 00303 * The number of entries per page. 00304 */ 00305 int32_t m_cPageSize; 00306 00307 /** 00308 * The page number. 00309 */ 00310 int32_t m_nPage; 00311 00312 /** 00313 * The comparator used to partition the entry values into pages. 00314 */ 00315 mutable FinalView<Comparator> f_vComparator; 00316 00317 /** 00318 * The top anchor object (the last object on a previous page). 00319 */ 00320 mutable MemberView<Object> m_vAnchorTop; 00321 00322 /** 00323 * The bottom anchor object (the last object on the current page). 00324 */ 00325 mutable MemberView<Object> m_vAnchorBottom; 00326 00327 /** 00328 * The cookie object used by the query processors to store a transient 00329 * state of the request (on a client side). 00330 */ 00331 mutable MemberView<Object> m_vCookie; 00332 }; 00333 00334 COH_CLOSE_NAMESPACE3 00335 00336 #endif // COH_LIMIT_FILTER_HPP 00337