• Home
• com.oracle.coherence.ce
• coherence
• 22.06.2
• source code
• Aggregators.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.tangosol.util.Aggregators Maven / Gradle / Ivy

/*
 * Copyright (c) 2000, 2021, Oracle and/or its affiliates.
 *
 * Licensed under the Universal Permissive License v 1.0 as shown at
 * http://oss.oracle.com/licenses/upl.
 */
package com.tangosol.util;

import com.tangosol.util.aggregator.AsynchronousAggregator;
import com.tangosol.util.aggregator.BigDecimalAverage;
import com.tangosol.util.aggregator.BigDecimalMax;
import com.tangosol.util.aggregator.BigDecimalMin;
import com.tangosol.util.aggregator.BigDecimalSum;
import com.tangosol.util.aggregator.ComparableMax;
import com.tangosol.util.aggregator.ComparableMin;
import com.tangosol.util.aggregator.CompositeAggregator;
import com.tangosol.util.aggregator.Count;
import com.tangosol.util.aggregator.DistinctValues;
import com.tangosol.util.aggregator.DoubleAverage;
import com.tangosol.util.aggregator.DoubleMax;
import com.tangosol.util.aggregator.DoubleMin;
import com.tangosol.util.aggregator.DoubleSum;
import com.tangosol.util.aggregator.GroupAggregator;
import com.tangosol.util.aggregator.LongMax;
import com.tangosol.util.aggregator.LongMin;
import com.tangosol.util.aggregator.LongSum;
import com.tangosol.util.aggregator.ReducerAggregator;
import com.tangosol.util.aggregator.ScriptAggregator;
import com.tangosol.util.aggregator.TopNAggregator;

import com.tangosol.util.function.Remote;

import java.math.BigDecimal;

import java.util.Collection;
import java.util.Comparator;
import java.util.List;
import java.util.Map;

/**
 * Simple Aggregator DSL.
 * 

 * The methods in this class are for the most part simple factory methods for
 * various {@link InvocableMap.EntryAggregator} classes, but in some cases provide additional type
 * safety. They also tend to make the code more readable, especially if imported
 * statically, so their use is strongly encouraged in lieu of direct construction
 * of {@code InvocableMap.EntryAggregator} classes.
 *
 * @author lh, hr  2018.06.12
 */
@SuppressWarnings({"unchecked", "rawtypes", "Convert2MethodRef"})
public class Aggregators
    {
    /**
     * Return an AsynchronousAggregator for a given streaming aggregator.
     *
     * @param aggregator  the underlying streaming aggregator
     *
     * @param  the type of the Map entry keys
     * @param  the type of the Map entry values
     * @param 
 the type of the intermediate result during the parallel stage
     * @param  the type of the value returned by the StreamingAggregator
     */
    public static  AsynchronousAggregator
        asynchronous(InvocableMap.StreamingAggregator aggregator)
        {
        return new AsynchronousAggregator(aggregator);
        }

    /**
     * Return an AsynchronousAggregator for a given streaming aggregator.
     *
     * @param aggregator    the underlying streaming aggregator
     * @param iUnitOrderId  the unit-of-order id for this aggregator
     */
    public static   InvocableMap.EntryAggregator
        asynchronous(InvocableMap.StreamingAggregator aggregator, int iUnitOrderId)
        {
        return new AsynchronousAggregator(aggregator, iUnitOrderId);
        }

    /**
     * Return an aggregator that calculates a average of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        average(ValueExtractor extractor)
        {
        return new DoubleAverage(extractor);
        }

    /**
     * Return an aggregator that calculates a average of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator average(String sMethod)
        {
        return new DoubleAverage(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a maximum of the double values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Double}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        max(Remote.ToDoubleFunction extractor)
        {
        return new DoubleMax(ValueExtractor.of((T t) -> extractor.applyAsDouble(t)));
        }

    /**
     * Return an aggregator that calculates a minimum of the double values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Double}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        min(Remote.ToDoubleFunction extractor)
        {
        return new DoubleMin(ValueExtractor.of((T t) -> extractor.applyAsDouble(t)));
        }

    /**
     * Return an aggregator that calculates a sum of the double values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Double}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        sum(Remote.ToDoubleFunction extractor)
        {
        return new DoubleSum(ValueExtractor.of((T t) -> extractor.applyAsDouble(t)));
        }

    /**
     * Return an aggregator that calculates an average of the double values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Double}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        average(Remote.ToDoubleFunction extractor)
        {
        return new DoubleAverage(ValueExtractor.of((T t) -> extractor.applyAsDouble(t)));
        }

    /**
     * Return an aggregator that calculates a maximum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        doubleMax(ValueExtractor extractor)
        {
        return new DoubleMax(extractor);
        }

    /**
     * Return an aggregator that calculates a maximum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator doubleMax(String sMethod)
        {
        return new DoubleMax(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a minimum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        doubleMin(ValueExtractor extractor)
        {
        return new DoubleMin(extractor);
        }

    /**
     * Return an aggregator that calculates a minimum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator doubleMin(String sMethod)
        {
        return new DoubleMin(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a sum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        doubleSum(ValueExtractor extractor)
        {
        return new DoubleSum(extractor);
        }

    /**
     * Return an aggregator that calculates a sum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java double values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator doubleSum(String sMethod)
        {
        return new DoubleSum(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a maximum of the int values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link Integer}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        max(Remote.ToIntFunction extractor)
        {
        return new LongMax(ValueExtractor.of((T t) -> (long) extractor.applyAsInt(t)));
        }

    /**
     * Return an aggregator that calculates a minimum of the int values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link Integer}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        min(Remote.ToIntFunction extractor)
        {
        return new LongMin(ValueExtractor.of((T t) -> (long) extractor.applyAsInt(t)));
        }

    /**
     * Return an aggregator that calculates a sum of the int values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link Integer}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        sum(Remote.ToIntFunction extractor)
        {
        return new LongSum(ValueExtractor.of((T t) -> (long) extractor.applyAsInt(t)));
        }

    /**
     * Return an aggregator that calculates an average of the int values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link Integer}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        average(Remote.ToIntFunction extractor)
        {
        return new DoubleAverage(ValueExtractor.of((T t) -> (long) extractor.applyAsInt(t)));
        }

    /**
     * Return an aggregator that calculates a maximum of the long values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Long}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        max(Remote.ToLongFunction extractor)
        {
        return new LongMax(ValueExtractor.of((T t) -> extractor.applyAsLong(t)));
        }

    /**
     * Return an aggregator that calculates a minimum of the long values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Long}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        min(Remote.ToLongFunction extractor)
        {
        return new LongMin(ValueExtractor.of((T t) -> extractor.applyAsLong(t)));
        }

    /**
     * Return an aggregator that calculates a sum of the long values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Long}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        sum(Remote.ToLongFunction extractor)
        {
        return new LongSum(ValueExtractor.of((T t) -> extractor.applyAsLong(t)));
        }

    /**
     * Return an aggregator that calculates an average of the long values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Long}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        average(Remote.ToLongFunction extractor)
        {
        return new DoubleAverage(ValueExtractor.of((T t) -> extractor.applyAsLong(t)));
        }

    /**
     * Return an aggregator that calculates a maximum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java long values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        longMax(ValueExtractor extractor)
        {
        return new LongMax(extractor);
        }

    /**
     * Return an aggregator that calculates a maximum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java long values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator longMax(String sMethod)
        {
        return new LongMax(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a minimum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java long values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        longMin(ValueExtractor extractor)
        {
        return new LongMin(extractor);
        }

    /**
     * Return an aggregator that calculates a minimum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java long values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator longMin(String sMethod)
        {
        return new LongMin(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a sum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java long values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        longSum(ValueExtractor extractor)
        {
        return new LongSum(extractor);
        }

    /**
     * Return an aggregator that calculates a sum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as Java long values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator longSum(String sMethod)
        {
        return new LongSum(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a maximum of the BigDecimal values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link BigDecimal}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        max(Remote.ToBigDecimalFunction extractor)
        {
        return new BigDecimalMax(ValueExtractor.of((T t) -> extractor.apply(t)));
        }

    /**
     * Return an aggregator that calculates a minimum of the BigDecimal values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link BigDecimal}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        min(Remote.ToBigDecimalFunction extractor)
        {
        return new BigDecimalMin(ValueExtractor.of((T t) -> extractor.apply(t)));
        }

    /**
     * Return an aggregator that calculates a sum of the BigDecimal values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link BigDecimal}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        sum(Remote.ToBigDecimalFunction extractor)
        {
        return new BigDecimalSum(ValueExtractor.of((T t) -> extractor.apply(t)));
        }

    /**
     * Return an aggregator that calculates an average of the BigDecimal values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is an {@link BigDecimal}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        average(Remote.ToBigDecimalFunction extractor)
        {
        return new BigDecimalAverage(ValueExtractor.of((T t) -> extractor.apply(t)));
        }

    /**
     * Return an aggregator that calculates a average of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        bigDecimalAverage(ValueExtractor extractor)
        {
        return new BigDecimalAverage(extractor);
        }

    /**
     * Return an aggregator that calculates a average of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator  bigDecimalAverage(String sMethod)
        {
        return bigDecimalAverage(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a maximum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        bigDecimalMax(ValueExtractor extractor)
        {
        return new BigDecimalMax(extractor);
        }

    /**
     * Return an aggregator that calculates a maximum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator  bigDecimalMax(String sMethod)
        {
        return bigDecimalMax(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a minimum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        bigDecimalMin(ValueExtractor extractor)
        {
        return new BigDecimalMin(extractor);
        }

    /**
     * Return an aggregator that calculates a minimum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator  bigDecimalMin(String sMethod)
        {
        return bigDecimalMin(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a sum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static  InvocableMap.StreamingAggregator
        bigDecimalSum(ValueExtractor extractor)
        {
        return  new BigDecimalSum(extractor);
        }

    /**
     * Return an aggregator that calculates a sum of the numeric values extracted
     * from a set of entries in a Map. All the extracted Number objects will be treated
     * as {@link BigDecimal} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object that is a {@link Number}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator  bigDecimalSum(String sMethod)
        {
        return bigDecimalSum(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a maximum of the Comparable values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Comparable}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static > InvocableMap.StreamingAggregator
        max(Remote.ToComparableFunction extractor)
        {
        return new ComparableMax(ValueExtractor.of((T t) -> extractor.apply(t)));
        }

    /**
     * Return an aggregator that calculates a minimum of the Comparable values extracted
     * from a set of entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object that is a {@link Comparable}
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     */
    public static > InvocableMap.StreamingAggregator
        min(Remote.ToComparableFunction extractor)
        {
        return new ComparableMin(ValueExtractor.of((T t) -> extractor.apply(t)));
        }

    /**
     * Return an aggregator that calculates a maximum of the {@link Comparable} values
     * extracted from a set of entries in a Map. All the extracted objects will be
     * treated as {@link Comparable} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any object that implements {@link Comparable}
     *                   interface
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMax(ValueExtractor extractor)
        {
        return new ComparableMax(extractor);
        }

    /**
     * Return an aggregator that calculates a maximum of the values extracted from a set
     * of entries in a Map. All the extracted objects will ordered using the specified
     * {@link Comparator}.
     *
     * @param extractor  the extractor that provides an object to be compared
     * @param comparator the comparator used to compare the extracted object
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMax(ValueExtractor extractor, Comparator comparator)
        {
        return  new ComparableMax(extractor, comparator);
        }

    /**
     * Return an aggregator that calculates a maximum of the {@link Comparable} values
     * extracted from a set of entries in a Map. All the extracted objects will be
     * treated as {@link Comparable} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any object that implements {@link Comparable}
     *                 interface
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMax(String sMethod)
        {
        return comparableMax(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a maximum of the values extracted from a set
     * of entries in a Map. All the extracted objects will ordered using the specified
     * {@link Comparator}.
     *
     * @param sMethod    the name of the method that returns the value to be compared
     * @param comparator the comparator used to compare the extracted object
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMax(String sMethod, Comparator comparator)
        {
        return new ComparableMax(Extractors.extract(sMethod), comparator);
        }

    /**
     * Return an aggregator that calculates a minimum of the {@link Comparable} values
     * extracted from a set of entries in a Map. All the extracted objects will be
     * treated as {@link Comparable} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any object that implements {@link Comparable}
     *                   interface
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMin(ValueExtractor extractor)
        {
        return new ComparableMin(extractor);
        }

    /**
     * Return an aggregator that calculates a minimum of the values extracted from a set
     * of entries in a Map. All the extracted objects will ordered using the specified
     * {@link Comparator}.
     *
     * @param extractor  the extractor that provides an object to be compared
     * @param comparator the comparator used to compare the extracted object
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMin(ValueExtractor extractor, Comparator comparator)
        {
        return new ComparableMin(extractor, comparator);
        }

    /**
     * Return an aggregator that calculates a minimum of the {@link Comparable} values
     * extracted from a set of entries in a Map. All the extracted objects will be
     * treated as {@link Comparable} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any object that implements {@link Comparable}
     *                 interface
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMin(String sMethod)
        {
        return comparableMin(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates a minimum of the values extracted from a set
     * of entries in a Map. All the extracted objects will ordered using the specified
     * {@link Comparator}.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any object that implements {@link Comparable}
     *                 interface
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        comparableMin(String sMethod, Comparator comparator)
        {
        return new ComparableMin(Extractors.extract(sMethod), comparator);
        }

    /**
     * Return an aggregator that calculates the count of the entries in a Map.
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator count()
        {
        return new Count();
        }

    /**
     * Return an aggregator that calculates the set of distinct values from the entries in a Map.
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     */
    public static  InvocableMap.StreamingAggregator> distinctValues()
        {
        return new DistinctValues(Extractors.identity());
        }

    /**
     * Return an aggregator that calculates the set of distinct values extracted from the entries in a Map.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any Java object
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static  InvocableMap.StreamingAggregator>
        distinctValues(ValueExtractor extractor)
        {
        return new DistinctValues(extractor);
        }

    /**
     * Return an aggregator that calculates the set of distinct values extracted from the entries in a Map.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any Java object
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the aggregation result
     */
    public static  InvocableMap.StreamingAggregator> distinctValues(String sMethod)
        {
        return distinctValues(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that calculates the the combined set of results from a number of aggregators.
     *
     * @param aAggregator  an array of EntryAggregator objects; may not be null
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     *
     * @throws NullPointerException  if the aggregator array is null
     */
    public static  InvocableMap.StreamingAggregator>
        composite(InvocableMap.EntryAggregator... aAggregator)
        {
        return new CompositeAggregator(aAggregator);
        }

    /**
     * Create an instance of group aggregator based on a specified property or method
     * name(s) and an {@link InvocableMap.EntryAggregator}.
     *
     * @param aggregator an underlying EntryAggregator
     * @param asNames    the property or method name(s) to extract values from. The resulting
     *                   {@link ValueExtractor} is used to split InvocableMap entries into distinct
     *                   groups.
     *
     * @param   the type of the Map entry keys
     * @param   the type of the Map entry values
     * @param   the type of the extracted value
     * @param   the type of the group aggregator result
     */
    public static  InvocableMap.StreamingAggregator, Map>
        grouping(InvocableMap.EntryAggregator aggregator, String... asNames)
        {
        return grouping(aggregator, null, asNames);
        }

    /**
     * Create an instance of group aggregator based on a specified property or method
     * name(s) and an {@link InvocableMap.EntryAggregator}.
     *
     * @param aggregator an underlying EntryAggregator
     * @param filter     an optional Filter object that will be used to evaluate
     *                   results of each individual group aggregation
     * @param asNames    the property or method name(s) to extract values from. The resulting
     *                   {@link ValueExtractor} is used to split InvocableMap entries into distinct
     *                   groups.
     *
     * @param   the type of the Map entry keys
     * @param   the type of the Map entry values
     * @param   the type of the extracted value
     * @param   the type of the group aggregator result
     */
    public static  InvocableMap.StreamingAggregator, Map>
    grouping(InvocableMap.EntryAggregator aggregator,
             Filter                                filter,
             String...                             asNames)
        {
        if (asNames == null || asNames.length == 0)
            {
            throw new IllegalArgumentException("Names parameter cannot be null or empty");
            }

        ValueExtractor extractor;
        if (asNames.length == 1)
            {
            extractor = Extractors.extract(asNames[0]);
            }
        else
            {
            extractor = (ValueExtractor) Extractors.multi(asNames);
            }

        return grouping(extractor, aggregator, filter);
        }

    /**
     * Create an instance of group aggregator based on a specified property or method
     * name(s) and an {@link InvocableMap.EntryAggregator}.
     *
     * @param extractor  a ValueExtractor that will be used to split a set of
     *                   InvocableMap entries into distinct groups
     * @param aggregator an underlying EntryAggregator
     *
     * @param   the type of the Map entry keys
     * @param   the type of the Map entry values
     * @param   the type of the value to extract from
     * @param   the type of the extracted value
     * @param   the type of the group aggregator result
     */
    public static  InvocableMap.StreamingAggregator, Map>
        grouping(ValueExtractor extractor, InvocableMap.EntryAggregator aggregator)
        {
        return grouping(extractor, aggregator, null);
        }

    /**
     * Create an instance of group aggregator based on a specified property or method
     * name(s) and an {@link InvocableMap.EntryAggregator}.
     *
     * @param extractor   a ValueExtractor that will be used to split a set of
     *                    InvocableMap entries into distinct groups
     * @param aggregator  an underlying EntryAggregator
     * @param filter      an optional Filter object used to filter out results
     *                    of individual group aggregation results
     *
     * @param   the type of the Map entry keys
     * @param   the type of the Map entry values
     * @param   the type of the value to extract from
     * @param   the type of the extracted value
     * @param   the type of the group aggregator result
     */
    public static  InvocableMap.StreamingAggregator, Map>
        grouping(ValueExtractor                     extractor,
                 InvocableMap.EntryAggregator aggregator,
                 Filter                                                filter)
        {
        return GroupAggregator.createInstance(extractor, aggregator, filter);
        }

    /**
     * Return an aggregator that calculates the top n of the {@link Comparable} values
     * extracted from a set of entries in a Map. All the extracted objects will be
     * treated as {@link Comparable} values.
     *
     * @param extractor  the extractor that provides a value in the form of
     *                   any object that implements {@link Comparable}
     *                   interface
     * @param cResults   the maximum number of results to return
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        topN(ValueExtractor extractor, int cResults)
        {
        return new TopNAggregator<>(extractor, null, cResults);
        }

    /**
     * Return an aggregator that calculates the top n of the values extracted from a set
     * of entries in a Map. All the extracted objects will ordered using the specified
     * {@link Comparator}.
     *
     * @param extractor  the extractor that provides an object to be compared
     * @param comparator the comparator used to compare the extracted object
     * @param cResults   the maximum number of results to return
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static  InvocableMap.StreamingAggregator
        topN(ValueExtractor extractor, Comparator comparator, int cResults)
        {
        return  new TopNAggregator<>(extractor, comparator, cResults);
        }

    /**
     * Return an aggregator that calculates the top n of the {@link Comparable} values
     * extracted from a set of entries in a Map. All the extracted objects will be
     * treated as {@link Comparable} values.
     *
     * @param sMethod  the name of the method that returns a value in the form
     *                 of any object that implements {@link Comparable}
     *                 interface
     * @param cResults the maximum number of results to return
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator
        topN(String sMethod, int cResults)
        {
        return new TopNAggregator(Extractors.extract(sMethod), null, cResults);
        }

    /**
     * Return an aggregator that calculates the top n of the values extracted from a set
     * of entries in a Map. All the extracted objects will ordered using the specified
     * {@link Comparator}.
     *
     * @param sMethod    the name of the method that returns the value to be compared
     * @param comparator the comparator used to compare the extracted object
     * @param cResults   the maximum number of results to return
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static  InvocableMap.StreamingAggregator
        topN(String sMethod, Comparator comparator, int cResults)
        {
        return new TopNAggregator(Extractors.extract(sMethod), comparator, cResults);
        }

    /**
     * Return an aggregator that will return the extracted value for each entry in the map.
     *
     * @param extractor  the extractor that provides an value(s) to be returned
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the value to extract from
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator>
        reduce(ValueExtractor extractor)
        {
        return new ReducerAggregator(extractor);
        }

    /**
     * Return an aggregator that will return the extracted value for each entry in the map.
     *
     * @param sMethod  the name of the method to use to obtain the value
     *
     * @param   the type of the entry's key
     * @param   the type of the entry's value
     * @param   the type of the aggregation result
     */
    public static > InvocableMap.StreamingAggregator>
        reduce(String sMethod)
        {
        return new ReducerAggregator(Extractors.extract(sMethod));
        }

    /**
     * Return an aggregator that is implemented in a script using the specified
     * language.
     *
     * @param sLanguage  the string specifying one of the supported languages
     * @param sName      the name of the {@link InvocableMap.StreamingAggregator}
     *                   that needs to be evaluated
     * @param aoArgs     the arguments to be passed to the
     *                   {@link InvocableMap.StreamingAggregator}
     * @param         the type of key that the
     *                   {@link InvocableMap.StreamingAggregator} will receive
     * @param         the type of value that the
     *                   {@link InvocableMap.StreamingAggregator} will receive
     * @param 
        the type of partial result this
     *                   {@link InvocableMap.StreamingAggregator} will return
     * @param         the type of final result this
     *                   {@link InvocableMap.StreamingAggregator} will return
     *
     * @return an instance of {@link InvocableMap.StreamingAggregator}
     *
     * @throws ScriptException           if the {@code script} cannot be loaded or
     *                                   any errors occur during its execution
     * @throws IllegalArgumentException  if the specified language is not supported
     */
    public static  InvocableMap.StreamingAggregator script(
            String sLanguage, String sName, Object... aoArgs)
        {
        return script(sLanguage, sName, 0, aoArgs);
        }

    /**
     * Return an aggregator that is implemented in a script using the specified
     * language.
     *
     * @param sLanguage        the string specifying one of the supported languages
     * @param sName            the name of the {@link InvocableMap.StreamingAggregator}
     *                         that needs to be evaluated
     * @param characteristics  a bit mask representing the set of characteristics
     *                         of this aggregator
     * @param aoArgs           the arguments to be passed to the
     *                         {@link InvocableMap.StreamingAggregator}
     * @param               the type of key that the
     *                         {@link InvocableMap.StreamingAggregator} will receive
     * @param               the type of value that the
     *                         {@link InvocableMap.StreamingAggregator} will receive
     * @param 
              the type of partial result this
     *                         {@link InvocableMap.StreamingAggregator} will return
     * @param               the type of final result this
     *                         {@link InvocableMap.StreamingAggregator} will return
     *
     * @return an instance of {@link InvocableMap.StreamingAggregator}
     *
     * @throws ScriptException           if the {@code script} cannot be loaded or
     *                                   any errors occur during its execution
     * @throws IllegalArgumentException  if the specified language is not supported
     *
     * @see InvocableMap.StreamingAggregator#characteristics()
     */
    public static  InvocableMap.StreamingAggregator script(
            String sLanguage, String sName, int characteristics, Object... aoArgs)
        {
        return new ScriptAggregator<>(sLanguage, sName, characteristics, aoArgs);
        }

    }