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    }