001/*
002 * Copyright (c) 2007-2015 Concurrent, Inc. All Rights Reserved.
003 *
004 * Project and contact information: http://www.cascading.org/
005 *
006 * This file is part of the Cascading project.
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *     http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020
021package cascading.operation;
022
023import java.util.Iterator;
024
025import cascading.pipe.joiner.JoinerClosure;
026import cascading.tuple.Fields;
027import cascading.tuple.TupleEntry;
028import cascading.tuple.TupleEntryCollector;
029
030/** Interface BufferCall provides access to the current {@link cascading.operation.Buffer} invocation arguments. */
031public interface BufferCall<C> extends OperationCall<C>
032  {
033  /**
034   * Returns the current grouping {@link cascading.tuple.TupleEntry}.
035   *
036   * @return TupleEntry
037   */
038  TupleEntry getGroup();
039
040  /**
041   * Returns an {@link Iterator} of {@link TupleEntry} instances representing the arguments for the called
042   * {@link Buffer#operate(cascading.flow.FlowProcess, BufferCall)} method.
043   * <p/>
044   * The return value may be {@code null} if the previous {@link cascading.pipe.CoGroup} declares
045   * {@link cascading.pipe.joiner.BufferJoin} as the {@link cascading.pipe.joiner.Joiner}.
046   * <p/>
047   * See {@link #getJoinerClosure()}.
048   * <p/>
049   * Note that the returned TupleEntry should not be cached (stored in a Collection), nor should the underlying Tuple
050   * instance. Where possible Cascading will re-use both TupleEntry and Tuple instances.
051   * <p/>
052   * To get a safe copy that can be cached, use {@link TupleEntry#getTupleCopy()}.
053   *
054   * @return Iterator<TupleEntry>
055   */
056  Iterator<TupleEntry> getArgumentsIterator();
057
058  /**
059   * Return the resolved {@link cascading.tuple.Fields} declared by the current {@link Operation}.
060   *
061   * @return Fields
062   */
063  Fields getDeclaredFields();
064
065  /**
066   * Returns the {@link cascading.tuple.TupleEntryCollector} used to emit result values. Zero or more entries may be emitted.
067   *
068   * @return TupleCollector
069   */
070  TupleEntryCollector getOutputCollector();
071
072  /**
073   * Set to {@code false} if at the end of all values iterated over in the argumentsIterator, the last seen argument tuple
074   * values should not be nulled out.
075   * <p/>
076   * By default, if a result is emitted from the Buffer before and after the argumentsIterator is started or completed,
077   * the last seen non-grouping values are null. When false, the values are not nulled after completion.
078   * <p/>
079   * The default is {@code true}.
080   *
081   * @param retainValues of type boolean
082   */
083  void setRetainValues( boolean retainValues );
084
085  /**
086   * Returns {@code true} if non-grouping fields will not be nulled after the argumentsIterator is completed.
087   *
088   * @return true
089   */
090  boolean isRetainValues();
091
092  /**
093   * Returns the current instance of a {@link JoinerClosure}, if any. This allows a Buffer to implement its own join
094   * strategy against the incoming tuple streams.
095   * <p/>
096   * The return value is always {@code null} unless the declared fields on the {@link cascading.pipe.CoGroup} are
097   * {@link Fields#NONE}.
098   * <p/>
099   * Note this method is provided as a means to bypass some of the Cascading internals in order to improve the
100   * implementations (performance or maintainability) behind some algorithms.
101   * <p/>
102   * Consider it only if you are an advanced user. Or more robustly, consider implementing a custom
103   * {@link cascading.pipe.joiner.Joiner}.
104   *
105   * @return JoinerClosure
106   */
107  JoinerClosure getJoinerClosure();
108  }