001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.execute.ExecAggregator
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.sql.execute;
023:
024: import org.apache.derby.iapi.types.DataValueDescriptor;
025: import org.apache.derby.iapi.error.StandardException;
026: import org.apache.derby.iapi.services.io.Formatable;
027:
028: /**
029: * An ExecAggregator is the interface that execution uses
030: * to an aggregate. System defined aggregates will implement
031: * this directly.
032:
033: <P>
034: The life time of an ExecAggregator is as follows.
035:
036: <OL>
037: <LI> An ExecAggregator instance is created using the defined class name.
038: <LI> Its setup() method is called to define its role (COUNT(*), SUM, etc.).
039: <LI> Its newAggregator() method may be called any number of times to create
040: new working aggregators as required. These aggregators have the same role
041: and must be created in an initialized state.
042: <LI> accumlate and merge will be called across these set of aggregators
043: <LI> One of these aggregators will be used as the final one for obtaining the result
044: </OL>
045:
046:
047: * <P>
048: */
049: public interface ExecAggregator extends Formatable {
050: /**
051: Set's up the aggregate for processing.
052: */
053: public void setup(String aggregateName);
054:
055: /**
056: * Iteratively accumulates the addend into the aggregator.
057: * Called on each member of the set of values that is being
058: * aggregated.
059: *
060: * @param addend the DataValueDescriptor addend (current input to
061: * the aggregation)
062: * @param ga a result set getter
063: *
064: * @exception StandardException on error
065: */
066: public void accumulate(DataValueDescriptor addend, Object ga)
067: throws StandardException;
068:
069: /**
070: * Merges one aggregator into a another aggregator.
071: * Merges two partial aggregates results into a single result.
072: * Needed for: <UL>
073: * <LI> parallel aggregation </LI>
074: * <LI> vector aggregation (GROUP BY) </LI>
075: * <LI> distinct aggregates (e.g. MAX(DISTINCT Col)) </LI></UL><p>
076: *
077: * An example of a merge would be: given two COUNT()
078: * aggregators, C1 and C2, a merge of C1 into C2 would
079: * set C1.count += C2.count. So, given a <i>CountAggregator</i>
080: * with a <i>getCount()</i> method that returns its counts, its
081: * merge method might look like this: <pre>
082:
083: public void merge(ExecAggregator inputAggregator) throws StandardException
084: {
085: count += ((CountAccgregator)inputAggregator).getCount();
086: } </pre>
087: *
088: *
089: * @param inputAggregator the other Aggregator
090: * (input partial aggregate)
091: *
092: * @exception StandardException on error
093: */
094: public void merge(ExecAggregator inputAggregator)
095: throws StandardException;
096:
097: /**
098: * Produces the result to be returned by the query.
099: * The last processing of the aggregate.
100: *
101: * @exception StandardException on error
102: */
103: public DataValueDescriptor getResult() throws StandardException;
104:
105: /**
106: Return a new initialized copy of this aggregator, any state
107: set by the setup() method of the original Aggregator must be
108: copied into the new aggregator.
109: *
110: * @return ExecAggregator the new aggregator
111: */
112: public ExecAggregator newAggregator();
113:
114: /**
115: Return true if the aggregation eliminated at least one
116: null from the input data set.
117: */
118: public boolean didEliminateNulls();
119: }
|