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.mapreduce;
020
021import java.io.IOException;
022import java.net.URI;
023
024import org.apache.hadoop.classification.InterfaceAudience;
025import org.apache.hadoop.classification.InterfaceStability;
026import org.apache.hadoop.conf.Configuration;
027import org.apache.hadoop.conf.Configuration.IntegerRanges;
028import org.apache.hadoop.fs.Path;
029import org.apache.hadoop.io.RawComparator;
030import org.apache.hadoop.mapreduce.Mapper;
031import org.apache.hadoop.security.Credentials;
032
033/**
034 * A read-only view of the job that is provided to the tasks while they
035 * are running.
036 */
037@InterfaceAudience.Public
038@InterfaceStability.Evolving
039public interface JobContext extends MRJobConfig {
040  /**
041   * Return the configuration for the job.
042   * @return the shared configuration object
043   */
044  public Configuration getConfiguration();
045
046  /**
047   * Get credentials for the job.
048   * @return credentials for the job
049   */
050  public Credentials getCredentials();
051
052  /**
053   * Get the unique ID for the job.
054   * @return the object with the job id
055   */
056  public JobID getJobID();
057  
058  /**
059   * Get configured the number of reduce tasks for this job. Defaults to 
060   * <code>1</code>.
061   * @return the number of reduce tasks for this job.
062   */
063  public int getNumReduceTasks();
064  
065  /**
066   * Get the current working directory for the default file system.
067   * 
068   * @return the directory name.
069   */
070  public Path getWorkingDirectory() throws IOException;
071
072  /**
073   * Get the key class for the job output data.
074   * @return the key class for the job output data.
075   */
076  public Class<?> getOutputKeyClass();
077  
078  /**
079   * Get the value class for job outputs.
080   * @return the value class for job outputs.
081   */
082  public Class<?> getOutputValueClass();
083
084  /**
085   * Get the key class for the map output data. If it is not set, use the
086   * (final) output key class. This allows the map output key class to be
087   * different than the final output key class.
088   * @return the map output key class.
089   */
090  public Class<?> getMapOutputKeyClass();
091
092  /**
093   * Get the value class for the map output data. If it is not set, use the
094   * (final) output value class This allows the map output value class to be
095   * different than the final output value class.
096   *  
097   * @return the map output value class.
098   */
099  public Class<?> getMapOutputValueClass();
100
101  /**
102   * Get the user-specified job name. This is only used to identify the 
103   * job to the user.
104   * 
105   * @return the job's name, defaulting to "".
106   */
107  public String getJobName();
108
109  /**
110   * Get the {@link InputFormat} class for the job.
111   * 
112   * @return the {@link InputFormat} class for the job.
113   */
114  public Class<? extends InputFormat<?,?>> getInputFormatClass() 
115     throws ClassNotFoundException;
116
117  /**
118   * Get the {@link Mapper} class for the job.
119   * 
120   * @return the {@link Mapper} class for the job.
121   */
122  public Class<? extends Mapper<?,?,?,?>> getMapperClass() 
123     throws ClassNotFoundException;
124
125  /**
126   * Get the combiner class for the job.
127   * 
128   * @return the combiner class for the job.
129   */
130  public Class<? extends Reducer<?,?,?,?>> getCombinerClass() 
131     throws ClassNotFoundException;
132
133  /**
134   * Get the {@link Reducer} class for the job.
135   * 
136   * @return the {@link Reducer} class for the job.
137   */
138  public Class<? extends Reducer<?,?,?,?>> getReducerClass() 
139     throws ClassNotFoundException;
140
141  /**
142   * Get the {@link OutputFormat} class for the job.
143   * 
144   * @return the {@link OutputFormat} class for the job.
145   */
146  public Class<? extends OutputFormat<?,?>> getOutputFormatClass() 
147     throws ClassNotFoundException;
148
149  /**
150   * Get the {@link Partitioner} class for the job.
151   * 
152   * @return the {@link Partitioner} class for the job.
153   */
154  public Class<? extends Partitioner<?,?>> getPartitionerClass() 
155     throws ClassNotFoundException;
156
157  /**
158   * Get the {@link RawComparator} comparator used to compare keys.
159   * 
160   * @return the {@link RawComparator} comparator used to compare keys.
161   */
162  public RawComparator<?> getSortComparator();
163
164  /**
165   * Get the pathname of the job's jar.
166   * @return the pathname
167   */
168  public String getJar();
169
170  /** 
171   * Get the user defined {@link RawComparator} comparator for 
172   * grouping keys of inputs to the reduce.
173   * 
174   * @return comparator set by the user for grouping values.
175   * @see Job#setGroupingComparatorClass(Class) for details.  
176   */
177  public RawComparator<?> getGroupingComparator();
178  
179  /**
180   * Get whether job-setup and job-cleanup is needed for the job 
181   * 
182   * @return boolean 
183   */
184  public boolean getJobSetupCleanupNeeded();
185  
186  /**
187   * Get whether task-cleanup is needed for the job 
188   * 
189   * @return boolean 
190   */
191  public boolean getTaskCleanupNeeded();
192
193  /**
194   * Get whether the task profiling is enabled.
195   * @return true if some tasks will be profiled
196   */
197  public boolean getProfileEnabled();
198
199  /**
200   * Get the profiler configuration arguments.
201   *
202   * The default value for this property is
203   * "-agentlib:hprof=cpu=samples,heap=sites,force=n,thread=y,verbose=n,file=%s"
204   * 
205   * @return the parameters to pass to the task child to configure profiling
206   */
207  public String getProfileParams();
208
209  /**
210   * Get the range of maps or reduces to profile.
211   * @param isMap is the task a map?
212   * @return the task ranges
213   */
214  public IntegerRanges getProfileTaskRange(boolean isMap);
215
216  /**
217   * Get the reported username for this job.
218   * 
219   * @return the username
220   */
221  public String getUser();
222  
223  /**
224   * Originally intended to check if symlinks should be used, but currently
225   * symlinks cannot be disabled.
226   * @return true
227   */
228  @Deprecated
229  public boolean getSymlink();
230  
231  /**
232   * Get the archive entries in classpath as an array of Path
233   */
234  public Path[] getArchiveClassPaths();
235
236  /**
237   * Get cache archives set in the Configuration
238   * @return A URI array of the caches set in the Configuration
239   * @throws IOException
240   */
241  public URI[] getCacheArchives() throws IOException;
242
243  /**
244   * Get cache files set in the Configuration
245   * @return A URI array of the files set in the Configuration
246   * @throws IOException
247   */
248
249  public URI[] getCacheFiles() throws IOException;
250
251  /**
252   * Return the path array of the localized caches
253   * @return A path array of localized caches
254   * @throws IOException
255   * @deprecated the array returned only includes the items the were 
256   * downloaded. There is no way to map this to what is returned by
257   * {@link #getCacheArchives()}.
258   */
259  @Deprecated
260  public Path[] getLocalCacheArchives() throws IOException;
261
262  /**
263   * Return the path array of the localized files
264   * @return A path array of localized files
265   * @throws IOException
266   * @deprecated the array returned only includes the items the were 
267   * downloaded. There is no way to map this to what is returned by
268   * {@link #getCacheFiles()}.
269   */
270  @Deprecated
271  public Path[] getLocalCacheFiles() throws IOException;
272
273  /**
274   * Get the file entries in classpath as an array of Path
275   */
276  public Path[] getFileClassPaths();
277  
278  /**
279   * Get the timestamps of the archives.  Used by internal
280   * DistributedCache and MapReduce code.
281   * @return a string array of timestamps 
282   * @throws IOException
283   */
284  public String[] getArchiveTimestamps();
285
286  /**
287   * Get the timestamps of the files.  Used by internal
288   * DistributedCache and MapReduce code.
289   * @return a string array of timestamps 
290   * @throws IOException
291   */
292  public String[] getFileTimestamps();
293
294  /** 
295   * Get the configured number of maximum attempts that will be made to run a
296   * map task, as specified by the <code>mapred.map.max.attempts</code>
297   * property. If this property is not already set, the default is 4 attempts.
298   *  
299   * @return the max number of attempts per map task.
300   */
301  public int getMaxMapAttempts();
302
303  /** 
304   * Get the configured number of maximum attempts  that will be made to run a
305   * reduce task, as specified by the <code>mapred.reduce.max.attempts</code>
306   * property. If this property is not already set, the default is 4 attempts.
307   * 
308   * @return the max number of attempts per reduce task.
309   */
310  public int getMaxReduceAttempts();
311
312}