Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/aggregator/GroupAggregator.hpp

    00001 /*
    00002 * GroupAggregator.hpp
    00003 *
    00004 * Copyright (c) 2000, 2010, 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_GROUP_AGGREGATOR_HPP
    00017 #define COH_GROUP_AGGREGATOR_HPP
    00018
    00019 #include "coherence/lang.ns"
    00020
    00021 #include "coherence/io/pof/PofReader.hpp"
    00022 #include "coherence/io/pof/PofWriter.hpp"
    00023 #include "coherence/io/pof/PortableObject.hpp"
    00024 #include "coherence/util/InvocableMap.hpp"
    00025 #include "coherence/util/Filter.hpp"
    00026 #include "coherence/util/ValueExtractor.hpp"
    00027
    00028 COH_OPEN_NAMESPACE3(coherence,util,aggregator)
    00029
    00030 using coherence::io::pof::PofReader;
    00031 using coherence::io::pof::PofWriter;
    00032 using coherence::io::pof::PortableObject;
    00033
    00034
    00035 /**
    00036 * The GroupAggregator provides an ability to split a subset of entries in an
    00037 * InvocableMap into a collection of non-intersecting subsets and then
    00038 * aggregate them separately and independently. The splitting (grouping) is
    00039 * performed using the results of the underlying ValueExtractor in such a way
    00040 * that two entries will belong to the same group if and only if the result of
    00041 * the corresponding ValueExtractor#extract extract call produces the
    00042 * same value or tuple (list of values). After the entries are split into the
    00043 * groups, the underlying aggregator is applied separately to each group. The
    00044 * result of the aggregation by the GroupAggregator is a Map that has distinct
    00045 * values (or tuples) as keys and results of the individual aggregation as
    00046 * values. Additionally, those results could be further reduced using an
    00047 * optional Filter object.
    00048 *
    00049 * Informally speaking, this aggregator is analogous to the SQL "group by" and
    00050 * "having" clauses. Note that the "having" Filter is applied independently on
    00051 * each server against the partial aggregation results; this generally implies
    00052 * that data affinity is required to ensure that all required data used to
    00053 * generate a given result exists within a single cache partition.
    00054 * In other words, the "group by" predicate should not span multiple
    00055 * partitions if the "having" clause is used.
    00056 *
    00057 * The GroupAggregator is somewhat similar to the DistinctValues
    00058 * aggregator, which returns back a list of distinct values (tuples) without
    00059 * performing any additional aggregation work.
    00060 *
    00061 * <b>Unlike many other concrete EntryAggregator implementations that are
    00062 * constructed directly, instances of GroupAggregator should only be created
    00063 * using one of the factory methods:</b>
    00064 * #create(ValueExtractor, InvocableMap::EntryAggregator)
    00065 * #create(vExtractor, hAggregator),
    00066 * #create(ValueExtractor, InvocableMap::EntryAggregator, Filter),
    00067 *
    00068 * @author djl  2008.05.16
    00069 */
    00070 class COH_EXPORT GroupAggregator
    00071     : public class_spec<GroupAggregator,
    00072         extends<Object>,
    00073         implements<PortableObject, InvocableMap::EntryAggregator> >
    00074     {
    00075     friend class factory<GroupAggregator>;
    00076
    00077     // ----- factory methods ------------------------------------------------
    00078
    00079     public:
    00080         /**
    00081          * Default constructor (necessary for the PortableObject interface).
    00082          */
    00083          static GroupAggregator::Handle create();
    00084
    00085          /**
    00086          * Create an instance of GroupAggregator based on a specified
    00087          * extractor and an coherence::util::InvocableMap::EntryAggregator
    00088          * and a result evaluation filter.
    00089          * <br>
    00090          * If the specified aggregator is an instance of
    00091          * coherence::util::InvocableMap::ParallelAwareAggregator, then a
    00092          * parallel-aware instance of the GroupAggregator will be created.
    00093          * Otherwise, the resulting GroupAggregator will not be
    00094          * parallel-aware and could be ill-suited for aggregations run
    00095          * against large partitioned caches.
    00096          *
    00097          * @param vExtractor   a ValueExtractor that will be used to split a
    00098          *                     set of InvocableMap entries into distinct
    00099          *                     groups
    00100          * @param hAggregator  an underlying EntryAggregator
    00101          * @param vFilter      an optional Filter object used to filter out
    00102          *                     results of individual group aggregation
    00103          *                     results
    00104          */
    00105          static GroupAggregator::Handle create(
    00106                  ValueExtractor::View vExtractor,
    00107                  InvocableMap::EntryAggregator::Handle hAggregator,
    00108                  Filter::View vFilter = NULL);
    00109
    00110
    00111     // ----- constructors ---------------------------------------------------
    00112
    00113     protected:
    00114         /**
    00115         * @internal
    00116         */
    00117         GroupAggregator();
    00118
    00119         /**
    00120         * @internal
    00121         */
    00122         GroupAggregator(ValueExtractor::View vExtractor,
    00123                 InvocableMap::EntryAggregator::Handle hAggregator,
    00124                 Filter::View vFilter);
    00125
    00126
    00127     // ----- InvocableMap::EntryAggregator interface ------------------------
    00128
    00129     public:
    00130         /**
    00131         * {@inheritDoc}
    00132         */
    00133         virtual Object::Holder aggregate(Set::View vSetEntries);
    00134
    00135
    00136     // ----- PortableObject interface ---------------------------------------
    00137
    00138     public:
    00139         /**
    00140         * {@inheritDoc}
    00141         */
    00142         virtual void readExternal(PofReader::Handle hIn);
    00143
    00144         /**
    00145         * {@inheritDoc}
    00146         */
    00147         virtual void writeExternal(PofWriter::Handle hOut) const;
    00148
    00149
    00150     // ----- Object interface -----------------------------------------------
    00151
    00152     public:
    00153         /**
    00154         * {@inheritDoc}
    00155         */
    00156         virtual bool equals(Object::View v) const;
    00157
    00158         /**
    00159         * {@inheritDoc}
    00160         */
    00161         virtual size32_t hashCode() const;
    00162
    00163         /**
    00164         * {@inheritDoc}
    00165         */
    00166         virtual void toStream(std::ostream& out) const;
    00167
    00168
    00169     // ----- data member accessors ------------------------------------------
    00170
    00171     public:
    00172         /**
    00173         * Obtain the underlying ValueExtractor.
    00174         *
    00175         * @return the underlying ValueExtractor
    00176         */
    00177         virtual ValueExtractor::View getExtractor() const;
    00178
    00179         /**
    00180         * Obtain the underlying EntryAggregator.
    00181         *
    00182         * @return the underlying EntryAggregator
    00183         */
    00184         virtual  InvocableMap::EntryAggregator::Handle getAggregator();
    00185
    00186         /**
    00187         * Obtain the underlying EntryAggregator.
    00188         *
    00189         * @return the underlying EntryAggregator
    00190         */
    00191         virtual  InvocableMap::EntryAggregator::View getAggregator() const;
    00192
    00193
    00194     // ----- data members ---------------------------------------------------
    00195
    00196     protected:
    00197         /**
    00198         * The underlying ValueExtractor.
    00199         */
    00200         MemberView<ValueExtractor> m_vExtractor;
    00201
    00202         /**
    00203         * The underlying EntryAggregator.
    00204         */
    00205         MemberHandle<InvocableMap::EntryAggregator> m_hAggregator;
    00206
    00207         /**
    00208         * The underlying Filter.
    00209         */
    00210         MemberView<Filter> m_vFilter;
    00211     };
    00212
    00213 COH_CLOSE_NAMESPACE3
    00214
    00215 #endif // COH_GROUP_AGGREGATOR_HPP

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.