    001/*
    002 * Copyright (c) 2007-2017 Xplenty, 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  }