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