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 }