001/*
002 * (C) Copyright 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     bstefanescu
018 */
019package org.nuxeo.ecm.automation;
020
021import org.nuxeo.ecm.automation.core.annotations.OperationMethod;
022
023/**
024 * This interface is used to implement result collectors when an operation method is invoked over an iterable input.
025 * <p>
026 * The operation method usually declare a scalar type (e.g. data object) as argument. When the operation method is
027 * invoked on an iterator over elements of that type the execution of the chain may help you deal with this by
028 * automatically invoking your method over every element in the input iterator. For this to work you should set the
029 * collector that should be used by the automatic iteration {@link OperationMethod#collector()} in order to construct
030 * the method output.
031 * <p>
032 * So a collector is in fact collecting the result of each individual invocation over a collections of inputs. The
033 * collector will be asked by the chain execution to add an individual result by calling
034 * {@link #add(OperationContext, Object)}. This method is taking as argument the return value of the invocation - so it
035 * must accept the same type of object - see T generic type. When all partial results are collected the collector will
036 * be asked to return the operation result through the {@link #getOutput()} method.
037 * <p>
038 * So when writing a collector you <b>must</b> ensure that the collected type is compatible with the one returned by the
039 * operation method where the collector is used.
040 * <p>
041 * <b>IMPORTANT<> An implementation of this class must explicitly implements this interface (and not through its super
042 * classes). This is to ease generic type detections. If not doing so your collector class will be rejected and the
043 * operation using it invalid.
044 *
045 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
046 */
047public interface OutputCollector<T, R> {
048
049    /**
050     * Collects a new partial result (the result of the last iteration step).
051     */
052    void collect(OperationContext ctx, T obj) throws OperationException;
053
054    /**
055     * Gets the final output. This is usually a list or set of collected objects.
056     */
057    R getOutput();
058
059}