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 java.io.IOException;
022
023 import org.apache.hadoop.classification.InterfaceAudience;
024 import org.apache.hadoop.classification.InterfaceStability;
025 import 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
040 public 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 }