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 }