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