package org.mongodb.morphia.aggregation;


import com.mongodb.AggregationOptions;
import com.mongodb.ReadPreference;
import org.mongodb.morphia.query.Query;
import org.mongodb.morphia.query.Sort;

import java.util.Iterator;
import java.util.List;

This defines the pipeline used in aggregation operations
@mongodb.driver.manual
core/aggregation-pipeline/ Aggregation Pipeline/**
 * This defines the pipeline used in aggregation operations
 *
 * @mongodb.driver.manual core/aggregation-pipeline/ Aggregation Pipeline
 */
public interface AggregationPipeline {
    
Executes the pipeline and aggregates the output in to the type mapped by the target type using the default options as defined in AggregationOptions. 
Params:
target – The class to use when iterating over the results
Type parameters:
<U> –    type of the results
Returns:
an iterator of the computed results/**
     * Executes the pipeline and aggregates the output in to the type mapped by the target type using the default options as defined in
     * {@link AggregationOptions}.
     *
     * @param target The class to use when iterating over the results
     * @param <U>    type of the results
     * @return an iterator of the computed results
     */
    <U> Iterator<U> aggregate(Class<U> target);

    
Executes the pipeline and aggregates the output in to the type mapped by the target type.
Params:
target –  The class to use when iterating over the results
options – The options to apply to this aggregation
Type parameters:
<U> –     type of the results
Returns:
an iterator of the computed results/**
     * Executes the pipeline and aggregates the output in to the type mapped by the target type.
     *
     * @param target  The class to use when iterating over the results
     * @param options The options to apply to this aggregation
     * @param <U>     type of the results
     * @return an iterator of the computed results
     */
    <U> Iterator<U> aggregate(Class<U> target, AggregationOptions options);

    
Executes the pipeline and aggregates the output in to the type mapped by the target type.
Params:
target –         The class to use when iterating over the results
options –        The options to apply to this aggregation
readPreference – The read preference to apply to this pipeline
Type parameters:
<U> –            type of the results
Returns:
an iterator of the computed results/**
     * Executes the pipeline and aggregates the output in to the type mapped by the target type.
     *
     * @param target         The class to use when iterating over the results
     * @param options        The options to apply to this aggregation
     * @param readPreference The read preference to apply to this pipeline
     * @param <U>            type of the results
     * @return an iterator of the computed results
     */
    <U> Iterator<U> aggregate(Class<U> target, AggregationOptions options, ReadPreference readPreference);

    
Executes the pipeline and aggregates the output in to the type mapped by the target type.
Params:
collectionName – The collection in which to store the results of the aggregation overriding the mapped value in target
target –         The class to use when iterating over the results
options –        The options to apply to this aggregation
readPreference – The read preference to apply to this pipeline
Type parameters:
<U> –            type of the results
Returns:
an iterator of the computed results/**
     * Executes the pipeline and aggregates the output in to the type mapped by the target type.
     *
     * @param collectionName The collection in which to store the results of the aggregation overriding the mapped value in target
     * @param target         The class to use when iterating over the results
     * @param options        The options to apply to this aggregation
     * @param readPreference The read preference to apply to this pipeline
     * @param <U>            type of the results
     * @return an iterator of the computed results
     */
    <U> Iterator<U> aggregate(String collectionName, Class<U> target, AggregationOptions options, ReadPreference readPreference);

    
Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match,
$sort,
and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier
field.
Params:
geoNear – the geospatial parameters to apply to the pipeline
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/geoNear $geoNear/**
     * Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match,
     * $sort,
     * and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier
     * field.
     *
     * @param geoNear the geospatial parameters to apply to the pipeline
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/geoNear $geoNear
     */
    AggregationPipeline geoNear(GeoNear geoNear);

    
Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group .
Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier
field and, if specified, accumulated fields.  The ID for this group is null.
Params:
groupings – the group definitions
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/group $group/**
     * Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group .
     * Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier
     * field and, if specified, accumulated fields.  The ID for this group is null.
     *
     * @param groupings the group definitions
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/group $group
     */
    AggregationPipeline group(Group... groupings);

    
Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group .
Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier
field
and, if specified, accumulated fields.
Params:
id –        the ID of the group create
groupings – the group definitions
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/group $group/**
     * Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group .
     * Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier
     * field
     * and, if specified, accumulated fields.
     *
     * @param id        the ID of the group create
     * @param groupings the group definitions
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/group $group
     */
    AggregationPipeline group(String id, Group... groupings);

    
Params:
id –        the ID of the group create
groupings – the group definitions
See Also:
group(String, Group...)
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/group $group/**
     * @param id        the ID of the group create
     * @param groupings the group definitions
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/group $group
     * @see #group(String, Group...)
     */
    AggregationPipeline group(List<Group> id, Group... groupings);

    
Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one
document (for the first n documents) or zero documents (after the first n documents).
Params:
count – the maximum number of documents to return
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/limit $limit/**
     * Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one
     * document (for the first n documents) or zero documents (after the first n documents).
     *
     * @param count the maximum number of documents to return
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/limit $limit
     */
    AggregationPipeline limit(int count);

    
Performs a left outer join to an unsharded collection in the same database to filter in documents from the “joined” collection for
processing. The $lookup stage does an equality match between a field from the input documents with a field from the documents of the
“joined” collection.  To each input document, the $lookup stage adds a new array field whose elements are the matching documents
from the “joined” collection. The $lookup stage passes these reshaped documents to the next stage.
Params:
from –         the collection to join
localField –   the field from the input documents
foreignField – the field from the documents of the "from" collection
as –           the output array field
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/lookup $lookup
Since:
1.2/**
     * Performs a left outer join to an unsharded collection in the same database to filter in documents from the “joined” collection for
     * processing. The $lookup stage does an equality match between a field from the input documents with a field from the documents of the
     * “joined” collection.  To each input document, the $lookup stage adds a new array field whose elements are the matching documents
     * from the “joined” collection. The $lookup stage passes these reshaped documents to the next stage.
     *
     * @param from         the collection to join
     * @param localField   the field from the input documents
     * @param foreignField the field from the documents of the "from" collection
     * @param as           the output array field
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/lookup $lookup
     * @since 1.2
     */
    AggregationPipeline lookup(String from, String localField, String foreignField, String as);

    
Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard
MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).
Params:
query – the query to use when matching
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/match $match/**
     * Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard
     * MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).
     *
     * @param query the query to use when matching
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/match $match
     */
    AggregationPipeline match(Query query);

    
Places the output of the aggregation in the collection mapped by the target type using the default options as defined in AggregationOptions. 
Params:
target – The class to use when iterating over the results
Type parameters:
<U> –    type of the results
Returns:
an iterator of the computed results
@mongodb.driver.manual
reference/operator/aggregation/out $out/**
     * Places the output of the aggregation in the collection mapped by the target type using the default options as defined in {@link
     * AggregationOptions}.
     *
     * @param target The class to use when iterating over the results
     * @param <U>    type of the results
     * @return an iterator of the computed results
     * @mongodb.driver.manual reference/operator/aggregation/out $out
     */
    <U> Iterator<U> out(Class<U> target);

    
Places the output of the aggregation in the collection mapped by the target type.
Params:
target –  The class to use when iterating over the results
options – The options to apply to this aggregation
Type parameters:
<U> –     type of the results
Returns:
an iterator of the computed results
@mongodb.driver.manual
reference/operator/aggregation/out $out/**
     * Places the output of the aggregation in the collection mapped by the target type.
     *
     * @param target  The class to use when iterating over the results
     * @param options The options to apply to this aggregation
     * @param <U>     type of the results
     * @return an iterator of the computed results
     * @mongodb.driver.manual reference/operator/aggregation/out $out
     */
    <U> Iterator<U> out(Class<U> target, AggregationOptions options);

    
Places the output of the aggregation in the collection mapped by the target type using the default options as defined in AggregationOptions. 
Params:
collectionName – The collection in which to store the results of the aggregation overriding the mapped value in target
target –         The class to use when iterating over the results
Type parameters:
<U> –            type of the results
Returns:
an iterator of the computed results
@mongodb.driver.manual
reference/operator/aggregation/out $out/**
     * Places the output of the aggregation in the collection mapped by the target type using the default options as defined in {@link
     * AggregationOptions}.
     *
     * @param collectionName The collection in which to store the results of the aggregation overriding the mapped value in target
     * @param target         The class to use when iterating over the results
     * @param <U>            type of the results
     * @return an iterator of the computed results
     * @mongodb.driver.manual reference/operator/aggregation/out $out
     */
    <U> Iterator<U> out(String collectionName, Class<U> target);

    
Places the output of the aggregation in the collection mapped by the target type.
Params:
collectionName – The collection in which to store the results of the aggregation overriding the mapped value in target
target –         The class to use when iterating over the results
options –        The options to apply to this aggregation
Type parameters:
<U> –            type of the results
Returns:
an iterator of the computed results
@mongodb.driver.manual
reference/operator/aggregation/out $out/**
     * Places the output of the aggregation in the collection mapped by the target type.
     *
     * @param collectionName The collection in which to store the results of the aggregation overriding the mapped value in target
     * @param target         The class to use when iterating over the results
     * @param options        The options to apply to this aggregation
     * @param <U>            type of the results
     * @return an iterator of the computed results
     * @mongodb.driver.manual reference/operator/aggregation/out $out
     */
    <U> Iterator<U> out(String collectionName, Class<U> target, AggregationOptions options);

    
Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one
document.
Params:
projections – the projections to apply to this pipeline
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/project $project/**
     * Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one
     * document.
     *
     * @param projections the projections to apply to this pipeline
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/project $project
     */
    AggregationPipeline project(Projection... projections);

    
Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For
each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).
Params:
count – the number of documents to skip
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/skip $skip/**
     * Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For
     * each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).
     *
     * @param count the number of documents to skip
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/skip $skip
     */
    AggregationPipeline skip(int count);

    
Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input
document, outputs one document.
Params:
sorts – the sorts to apply to this pipeline
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/sort $sort/**
     * Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input
     * document, outputs one document.
     *
     * @param sorts the sorts to apply to this pipeline
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/sort $sort
     */
    AggregationPipeline sort(Sort... sorts);

    
Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array
with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an
empty array.
Params:
field – the field to unwind
Returns:
this
@mongodb.driver.manual
reference/operator/aggregation/unwind $unwind/**
     * Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array
     * with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an
     * empty array.
     *
     * @param field the field to unwind
     * @return this
     * @mongodb.driver.manual reference/operator/aggregation/unwind $unwind
     */
    AggregationPipeline unwind(String field);
}