/*
* Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* bstefanescu
*/
package org.eclipse.ecr.automation;
import org.eclipse.ecr.automation.core.annotations.OperationMethod;
/**
* This interface is used to implement result collectors when an operation
* method is invoked over an iterable input.
* <p>
* The operation method usually declare a scalar type (e.g. data object) as
* argument. When the operation method is invoked on an iterator over elements
* of that type the execution of the chain may help you deal with this by
* automatically invoking your method over every element in the input iterator.
* For this to work you should set the collector that should be used by the
* automatic iteration {@link OperationMethod#collector()} in order to construct
* the method output.
* <p>
* So a collector is in fact collecting the result of each individual invocation
* over a collections of inputs. The collector will be asked by the chain
* execution to add an individual result by calling
* {@link #add(OperationContext, Object)}. This method is taking as argument the
* return value of the invocation - so it must accept the same type of object -
* see T generic type. When all partial results are collected the collector will
* be asked to return the operation result through the {@link #getOutput()}
* method.
* <p>
* So when writing a collector you <b>must</b> ensure that the collected type is
* compatible with the one returned by the operation method where the collector
* is used.
* <p>
* <b>IMPORTANT<> An implementation of this class must explicitly implements
* this interface (and not through its super classes). This is to ease generic
* type detections. If not doing so your collector class will be rejected and
* the operation using it invalid.
*
* @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
*/
public interface OutputCollector<T, R> {
/**
* Collects a new partial result (the result of the last iteration step).
*/
void collect(OperationContext ctx, T obj) throws OperationException;
/**
* Gets the final output. This is usually a list or set of collected objects.
*/
R getOutput();
}