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 java.io.IOException;
022
023import org.apache.hadoop.classification.InterfaceAudience;
024import org.apache.hadoop.classification.InterfaceStability;
025import org.apache.hadoop.conf.Configuration;
026
027
028/** 
029 * <code>RunningJob</code> is the user-interface to query for details on a 
030 * running Map-Reduce job.
031 * 
032 * <p>Clients can get hold of <code>RunningJob</code> via the {@link JobClient}
033 * and then query the running-job for details such as name, configuration, 
034 * progress etc.</p> 
035 * 
036 * @see JobClient
037 */
038@InterfaceAudience.Public
039@InterfaceStability.Stable
040public interface RunningJob {
041
042  /**
043   * Get the underlying job configuration
044   *
045   * @return the configuration of the job.
046   */
047  public Configuration getConfiguration();
048
049  /**
050   * Get the job identifier.
051   * 
052   * @return the job identifier.
053   */
054  public JobID getID();
055  
056  /** @deprecated This method is deprecated and will be removed. Applications should 
057   * rather use {@link #getID()}.
058   */
059  @Deprecated
060  public String getJobID();
061  
062  /**
063   * Get the name of the job.
064   * 
065   * @return the name of the job.
066   */
067  public String getJobName();
068
069  /**
070   * Get the path of the submitted job configuration.
071   * 
072   * @return the path of the submitted job configuration.
073   */
074  public String getJobFile();
075
076  /**
077   * Get the URL where some job progress information will be displayed.
078   * 
079   * @return the URL where some job progress information will be displayed.
080   */
081  public String getTrackingURL();
082
083  /**
084   * Get the <i>progress</i> of the job's map-tasks, as a float between 0.0 
085   * and 1.0.  When all map tasks have completed, the function returns 1.0.
086   * 
087   * @return the progress of the job's map-tasks.
088   * @throws IOException
089   */
090  public float mapProgress() throws IOException;
091
092  /**
093   * Get the <i>progress</i> of the job's reduce-tasks, as a float between 0.0 
094   * and 1.0.  When all reduce tasks have completed, the function returns 1.0.
095   * 
096   * @return the progress of the job's reduce-tasks.
097   * @throws IOException
098   */
099  public float reduceProgress() throws IOException;
100
101  /**
102   * Get the <i>progress</i> of the job's cleanup-tasks, as a float between 0.0 
103   * and 1.0.  When all cleanup tasks have completed, the function returns 1.0.
104   * 
105   * @return the progress of the job's cleanup-tasks.
106   * @throws IOException
107   */
108  public float cleanupProgress() throws IOException;
109
110  /**
111   * Get the <i>progress</i> of the job's setup-tasks, as a float between 0.0 
112   * and 1.0.  When all setup tasks have completed, the function returns 1.0.
113   * 
114   * @return the progress of the job's setup-tasks.
115   * @throws IOException
116   */
117  public float setupProgress() throws IOException;
118
119  /**
120   * Check if the job is finished or not. 
121   * This is a non-blocking call.
122   * 
123   * @return <code>true</code> if the job is complete, else <code>false</code>.
124   * @throws IOException
125   */
126  public boolean isComplete() throws IOException;
127
128  /**
129   * Check if the job completed successfully. 
130   * 
131   * @return <code>true</code> if the job succeeded, else <code>false</code>.
132   * @throws IOException
133   */
134  public boolean isSuccessful() throws IOException;
135  
136  /**
137   * Blocks until the job is complete.
138   * 
139   * @throws IOException
140   */
141  public void waitForCompletion() throws IOException;
142
143  /**
144   * Returns the current state of the Job.
145   * {@link JobStatus}
146   * 
147   * @throws IOException
148   */
149  public int getJobState() throws IOException;
150  
151  /**
152   * Returns a snapshot of the current status, {@link JobStatus}, of the Job.
153   * Need to call again for latest information.
154   * 
155   * @throws IOException
156   */
157  public JobStatus getJobStatus() throws IOException;
158
159  /**
160   * Kill the running job. Blocks until all job tasks have been killed as well.
161   * If the job is no longer running, it simply returns.
162   * 
163   * @throws IOException
164   */
165  public void killJob() throws IOException;
166  
167  /**
168   * Set the priority of a running job.
169   * @param priority the new priority for the job.
170   * @throws IOException
171   */
172  public void setJobPriority(String priority) throws IOException;
173  
174  /**
175   * Get events indicating completion (success/failure) of component tasks.
176   *  
177   * @param startFrom index to start fetching events from
178   * @return an array of {@link TaskCompletionEvent}s
179   * @throws IOException
180   */
181  public TaskCompletionEvent[] getTaskCompletionEvents(int startFrom) 
182  throws IOException;
183  
184  /**
185   * Kill indicated task attempt.
186   * 
187   * @param taskId the id of the task to be terminated.
188   * @param shouldFail if true the task is failed and added to failed tasks 
189   *                   list, otherwise it is just killed, w/o affecting 
190   *                   job failure status.  
191   * @throws IOException
192   */
193  public void killTask(TaskAttemptID taskId, boolean shouldFail) throws IOException;
194  
195  /** @deprecated Applications should rather use {@link #killTask(TaskAttemptID, boolean)}*/
196  @Deprecated
197  public void killTask(String taskId, boolean shouldFail) throws IOException;
198  
199  /**
200   * Gets the counters for this job.
201   * 
202   * @return the counters for this job or null if the job has been retired.
203   * @throws IOException
204   */
205  public Counters getCounters() throws IOException;
206  
207  /**
208   * Gets the diagnostic messages for a given task attempt.
209   * @param taskid
210   * @return the list of diagnostic messages for the task
211   * @throws IOException
212   */
213  public String[] getTaskDiagnostics(TaskAttemptID taskid) throws IOException;
214
215  /**
216   * Get the url where history file is archived. Returns empty string if 
217   * history file is not available yet. 
218   * 
219   * @return the url where history file is archived
220   * @throws IOException
221   */
222  public String getHistoryUrl() throws IOException;
223
224  /**
225   * Check whether the job has been removed from JobTracker memory and retired.
226   * On retire, the job history file is copied to a location known by 
227   * {@link #getHistoryUrl()}
228   * @return <code>true</code> if the job retired, else <code>false</code>.
229   * @throws IOException
230   */
231  public boolean isRetired() throws IOException;
232  
233  /**
234   * Get failure info for the job.
235   * @return the failure info for the job.
236   * @throws IOException
237   */
238  public String getFailureInfo() throws IOException;
239}