001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     bstefanescu
011 */
012package org.nuxeo.ecm.automation;
013
014import org.nuxeo.ecm.automation.core.annotations.OperationMethod;
015
016/**
017 * This interface is used to implement result collectors when an operation method is invoked over an iterable input.
018 * <p>
019 * The operation method usually declare a scalar type (e.g. data object) as argument. When the operation method is
020 * invoked on an iterator over elements of that type the execution of the chain may help you deal with this by
021 * automatically invoking your method over every element in the input iterator. For this to work you should set the
022 * collector that should be used by the automatic iteration {@link OperationMethod#collector()} in order to construct
023 * the method output.
024 * <p>
025 * So a collector is in fact collecting the result of each individual invocation over a collections of inputs. The
026 * collector will be asked by the chain execution to add an individual result by calling
027 * {@link #add(OperationContext, Object)}. This method is taking as argument the return value of the invocation - so it
028 * must accept the same type of object - see T generic type. When all partial results are collected the collector will
029 * be asked to return the operation result through the {@link #getOutput()} method.
030 * <p>
031 * So when writing a collector you <b>must</b> ensure that the collected type is compatible with the one returned by the
032 * operation method where the collector is used.
033 * <p>
034 * <b>IMPORTANT<> An implementation of this class must explicitly implements this interface (and not through its super
035 * classes). This is to ease generic type detections. If not doing so your collector class will be rejected and the
036 * operation using it invalid.
037 *
038 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
039 */
040public interface OutputCollector<T, R> {
041
042    /**
043     * Collects a new partial result (the result of the last iteration step).
044     */
045    void collect(OperationContext ctx, T obj) throws OperationException;
046
047    /**
048     * Gets the final output. This is usually a list or set of collected objects.
049     */
050    R getOutput();
051
052}