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 }