    001    /*
    002     * Copyright (c) 2007-2014 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
    021    package cascading.operation;
    022
    023    import java.util.Iterator;
    024
    025    import cascading.pipe.joiner.JoinerClosure;
    026    import cascading.tuple.Fields;
    027    import cascading.tuple.TupleEntry;
    028    import cascading.tuple.TupleEntryCollector;
    029
    030    /** Interface BufferCall provides access to the current {@link cascading.operation.Buffer} invocation arguments. */
    031    public 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       *
    049       * @return Iterator<TupleEntry>
    050       */
    051      Iterator<TupleEntry> getArgumentsIterator();
    052
    053      /**
    054       * Return the resolved {@link cascading.tuple.Fields} declared by the current {@link Operation}.
    055       *
    056       * @return Fields
    057       */
    058      Fields getDeclaredFields();
    059
    060      /**
    061       * Returns the {@link cascading.tuple.TupleEntryCollector} used to emit result values. Zero or more entries may be emitted.
    062       *
    063       * @return TupleCollector
    064       */
    065      TupleEntryCollector getOutputCollector();
    066
    067      /**
    068       * Set to {@code false} if at the end of all values iterated over in the argumentsIterator, the last seen argument tuple
    069       * values should not be nulled out.
    070       * <p/>
    071       * By default, if a result is emitted from the Buffer before and after the argumentsIterator is started or completed,
    072       * the last seen non-grouping values are null. When false, the values are not nulled after completion.
    073       * <p/>
    074       * The default is {@code true}.
    075       *
    076       * @param retainValues of type boolean
    077       */
    078      void setRetainValues( boolean retainValues );
    079
    080      /**
    081       * Returns {@code true} if non-grouping fields will not be nulled after the argumentsIterator is completed.
    082       *
    083       * @return true
    084       */
    085      boolean isRetainValues();
    086
    087      /**
    088       * Returns the current instance of a {@link JoinerClosure}, if any. This allows a Buffer to implement its own join
    089       * strategy against the incoming tuple streams.
    090       * <p/>
    091       * The return value is always {@code null} unless the declared fields on the {@link cascading.pipe.CoGroup} are {@link Fields#NONE}.
    092       * <p/>
    093       * Note this method is provided as a means to bypass some of the Cascading internals in order to improve the
    094       * implementations (performance or maintainability) behind some algorithms.
    095       * <p/>
    096       * Consider it only if you are an advanced user. Or more robustly, consider implementing a custom
    097       * {@link cascading.pipe.joiner.Joiner}.
    098       *
    099       * @return JoinerClosure
    100       */
    101      public JoinerClosure getJoinerClosure();
    102      }