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    
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       * <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      }