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