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
019package org.apache.hadoop.mapred;
020
021import org.apache.hadoop.classification.InterfaceAudience;
022import org.apache.hadoop.classification.InterfaceStability;
023import org.apache.hadoop.mapred.Counters.Counter;
024import 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
044public 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}