001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package org.apache.hadoop.mapred;
020
021 import org.apache.hadoop.classification.InterfaceAudience;
022 import org.apache.hadoop.classification.InterfaceStability;
023 import org.apache.hadoop.mapred.Counters.Counter;
024 import org.apache.hadoop.util.Progressable;
025
026 /**
027 * A facility for Map-Reduce applications to report progress and update
028 * counters, status information etc.
029 *
030 * <p>{@link Mapper} and {@link Reducer} can use the <code>Reporter</code>
031 * provided to report progress or just indicate that they are alive. In
032 * scenarios where the application takes significant amount of time to
033 * process individual key/value pairs, this is crucial since the framework
034 * might assume that the task has timed-out and kill that task.
035 *
036 * <p>Applications can also update {@link Counters} via the provided
037 * <code>Reporter</code> .</p>
038 *
039 * @see Progressable
040 * @see Counters
041 */
042 @InterfaceAudience.Public
043 @InterfaceStability.Stable
044 public interface Reporter extends Progressable {
045
046 /**
047 * A constant of Reporter type that does nothing.
048 */
049 public static final Reporter NULL = new Reporter() {
050 public void setStatus(String s) {
051 }
052 public void progress() {
053 }
054 public Counter getCounter(Enum<?> name) {
055 return null;
056 }
057 public Counter getCounter(String group, String name) {
058 return null;
059 }
060 public void incrCounter(Enum<?> key, long amount) {
061 }
062 public void incrCounter(String group, String counter, long amount) {
063 }
064 public InputSplit getInputSplit() throws UnsupportedOperationException {
065 throw new UnsupportedOperationException("NULL reporter has no input");
066 }
067 @Override
068 public float getProgress() {
069 return 0;
070 }
071 };
072
073 /**
074 * Set the status description for the task.
075 *
076 * @param status brief description of the current status.
077 */
078 public abstract void setStatus(String status);
079
080 /**
081 * Get the {@link Counter} of the given group with the given name.
082 *
083 * @param name counter name
084 * @return the <code>Counter</code> of the given group/name.
085 */
086 public abstract Counter getCounter(Enum<?> name);
087
088 /**
089 * Get the {@link Counter} of the given group with the given name.
090 *
091 * @param group counter group
092 * @param name counter name
093 * @return the <code>Counter</code> of the given group/name.
094 */
095 public abstract Counter getCounter(String group, String name);
096
097 /**
098 * Increments the counter identified by the key, which can be of
099 * any {@link Enum} type, by the specified amount.
100 *
101 * @param key key to identify the counter to be incremented. The key can be
102 * be any <code>Enum</code>.
103 * @param amount A non-negative amount by which the counter is to
104 * be incremented.
105 */
106 public abstract void incrCounter(Enum<?> key, long amount);
107
108 /**
109 * Increments the counter identified by the group and counter name
110 * by the specified amount.
111 *
112 * @param group name to identify the group of the counter to be incremented.
113 * @param counter name to identify the counter within the group.
114 * @param amount A non-negative amount by which the counter is to
115 * be incremented.
116 */
117 public abstract void incrCounter(String group, String counter, long amount);
118
119 /**
120 * Get the {@link InputSplit} object for a map.
121 *
122 * @return the <code>InputSplit</code> that the map is reading from.
123 * @throws UnsupportedOperationException if called outside a mapper
124 */
125 public abstract InputSplit getInputSplit()
126 throws UnsupportedOperationException;
127
128 /**
129 * Get the progress of the task. Progress is represented as a number between
130 * 0 and 1 (inclusive).
131 */
132 public float getProgress();
133 }