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}