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       * Kill the running job.  Blocks until all job tasks have been
153       * killed as well.  If the job is no longer running, it simply returns.
154       * 
155       * @throws IOException
156       */
157      public void killJob() throws IOException;
158      
159      /**
160       * Set the priority of a running job.
161       * @param priority the new priority for the job.
162       * @throws IOException
163       */
164      public void setJobPriority(String priority) throws IOException;
165      
166      /**
167       * Get events indicating completion (success/failure) of component tasks.
168       *  
169       * @param startFrom index to start fetching events from
170       * @return an array of {@link TaskCompletionEvent}s
171       * @throws IOException
172       */
173      public TaskCompletionEvent[] getTaskCompletionEvents(int startFrom) 
174      throws IOException;
175      
176      /**
177       * Kill indicated task attempt.
178       * 
179       * @param taskId the id of the task to be terminated.
180       * @param shouldFail if true the task is failed and added to failed tasks 
181       *                   list, otherwise it is just killed, w/o affecting 
182       *                   job failure status.  
183       * @throws IOException
184       */
185      public void killTask(TaskAttemptID taskId, boolean shouldFail) throws IOException;
186      
187      /** @deprecated Applications should rather use {@link #killTask(TaskAttemptID, boolean)}*/
188      @Deprecated
189      public void killTask(String taskId, boolean shouldFail) throws IOException;
190      
191      /**
192       * Gets the counters for this job.
193       * 
194       * @return the counters for this job or null if the job has been retired.
195       * @throws IOException
196       */
197      public Counters getCounters() throws IOException;
198      
199      /**
200       * Gets the diagnostic messages for a given task attempt.
201       * @param taskid
202       * @return the list of diagnostic messages for the task
203       * @throws IOException
204       */
205      public String[] getTaskDiagnostics(TaskAttemptID taskid) throws IOException;
206    
207      /**
208       * Get the url where history file is archived. Returns empty string if 
209       * history file is not available yet. 
210       * 
211       * @return the url where history file is archived
212       * @throws IOException
213       */
214      public String getHistoryUrl() throws IOException;
215    
216      /**
217       * Check whether the job has been removed from JobTracker memory and retired.
218       * On retire, the job history file is copied to a location known by 
219       * {@link #getHistoryUrl()}
220       * @return <code>true</code> if the job retired, else <code>false</code>.
221       * @throws IOException
222       */
223      public boolean isRetired() throws IOException;
224      
225      /**
226       * Get failure info for the job.
227       * @return the failure info for the job.
228       * @throws IOException
229       */
230      public String getFailureInfo() throws IOException;
231    }