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 }