00001 /* 00002 * GroupAggregator.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_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 private: 00127 /** 00128 * Blocked copy constructor. 00129 */ 00130 GroupAggregator(const GroupAggregator&); 00131 00132 00133 // ----- InvocableMap::EntryAggregator interface ------------------------ 00134 00135 public: 00136 /** 00137 * {@inheritDoc} 00138 */ 00139 virtual Object::Holder aggregate(Set::View vSetEntries); 00140 00141 00142 // ----- PortableObject interface --------------------------------------- 00143 00144 public: 00145 /** 00146 * {@inheritDoc} 00147 */ 00148 virtual void readExternal(PofReader::Handle hIn); 00149 00150 /** 00151 * {@inheritDoc} 00152 */ 00153 virtual void writeExternal(PofWriter::Handle hOut) const; 00154 00155 00156 // ----- Object interface ----------------------------------------------- 00157 00158 public: 00159 /** 00160 * {@inheritDoc} 00161 */ 00162 virtual bool equals(Object::View v) const; 00163 00164 /** 00165 * {@inheritDoc} 00166 */ 00167 virtual size32_t hashCode() const; 00168 00169 /** 00170 * {@inheritDoc} 00171 */ 00172 virtual void toStream(std::ostream& out) const; 00173 00174 00175 // ----- data member accessors ------------------------------------------ 00176 00177 public: 00178 /** 00179 * Obtain the underlying ValueExtractor. 00180 * 00181 * @return the underlying ValueExtractor 00182 */ 00183 virtual ValueExtractor::View getExtractor() const; 00184 00185 /** 00186 * Obtain the underlying EntryAggregator. 00187 * 00188 * @return the underlying EntryAggregator 00189 */ 00190 virtual InvocableMap::EntryAggregator::Handle getAggregator(); 00191 00192 /** 00193 * Obtain the underlying EntryAggregator. 00194 * 00195 * @return the underlying EntryAggregator 00196 */ 00197 virtual InvocableMap::EntryAggregator::View getAggregator() const; 00198 00199 00200 // ----- data members --------------------------------------------------- 00201 00202 protected: 00203 /** 00204 * The underlying ValueExtractor. 00205 */ 00206 FinalView<ValueExtractor> f_vExtractor; 00207 00208 /** 00209 * The underlying EntryAggregator. 00210 */ 00211 FinalHandle<InvocableMap::EntryAggregator> f_hAggregator; 00212 00213 /** 00214 * The underlying Filter. 00215 */ 00216 FinalView<Filter> f_vFilter; 00217 }; 00218 00219 COH_CLOSE_NAMESPACE3 00220 00221 #endif // COH_GROUP_AGGREGATOR_HPP