coherence/util/filter/LimitFilter.hpp

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