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 combiner.
173   *
174   * @return comparator set by the user for grouping values.
175   * @see Job#setCombinerKeyGroupingComparatorClass(Class)
176   */
177  public RawComparator<?> getCombinerKeyGroupingComparator();
178
179    /**
180     * Get the user defined {@link RawComparator} comparator for
181     * grouping keys of inputs to the reduce.
182     *
183     * @return comparator set by the user for grouping values.
184     * @see Job#setGroupingComparatorClass(Class)
185     * @see #getCombinerKeyGroupingComparator()
186     */
187  public RawComparator<?> getGroupingComparator();
188  
189  /**
190   * Get whether job-setup and job-cleanup is needed for the job 
191   * 
192   * @return boolean 
193   */
194  public boolean getJobSetupCleanupNeeded();
195  
196  /**
197   * Get whether task-cleanup is needed for the job 
198   * 
199   * @return boolean 
200   */
201  public boolean getTaskCleanupNeeded();
202
203  /**
204   * Get whether the task profiling is enabled.
205   * @return true if some tasks will be profiled
206   */
207  public boolean getProfileEnabled();
208
209  /**
210   * Get the profiler configuration arguments.
211   *
212   * The default value for this property is
213   * "-agentlib:hprof=cpu=samples,heap=sites,force=n,thread=y,verbose=n,file=%s"
214   * 
215   * @return the parameters to pass to the task child to configure profiling
216   */
217  public String getProfileParams();
218
219  /**
220   * Get the range of maps or reduces to profile.
221   * @param isMap is the task a map?
222   * @return the task ranges
223   */
224  public IntegerRanges getProfileTaskRange(boolean isMap);
225
226  /**
227   * Get the reported username for this job.
228   * 
229   * @return the username
230   */
231  public String getUser();
232  
233  /**
234   * Originally intended to check if symlinks should be used, but currently
235   * symlinks cannot be disabled.
236   * @return true
237   */
238  @Deprecated
239  public boolean getSymlink();
240  
241  /**
242   * Get the archive entries in classpath as an array of Path
243   */
244  public Path[] getArchiveClassPaths();
245
246  /**
247   * Get cache archives set in the Configuration
248   * @return A URI array of the caches set in the Configuration
249   * @throws IOException
250   */
251  public URI[] getCacheArchives() throws IOException;
252
253  /**
254   * Get cache files set in the Configuration
255   * @return A URI array of the files set in the Configuration
256   * @throws IOException
257   */
258
259  public URI[] getCacheFiles() throws IOException;
260
261  /**
262   * Return the path array of the localized caches
263   * @return A path array of localized caches
264   * @throws IOException
265   * @deprecated the array returned only includes the items the were 
266   * downloaded. There is no way to map this to what is returned by
267   * {@link #getCacheArchives()}.
268   */
269  @Deprecated
270  public Path[] getLocalCacheArchives() throws IOException;
271
272  /**
273   * Return the path array of the localized files
274   * @return A path array of localized files
275   * @throws IOException
276   * @deprecated the array returned only includes the items the were 
277   * downloaded. There is no way to map this to what is returned by
278   * {@link #getCacheFiles()}.
279   */
280  @Deprecated
281  public Path[] getLocalCacheFiles() throws IOException;
282
283  /**
284   * Get the file entries in classpath as an array of Path
285   */
286  public Path[] getFileClassPaths();
287  
288  /**
289   * Get the timestamps of the archives.  Used by internal
290   * DistributedCache and MapReduce code.
291   * @return a string array of timestamps 
292   */
293  public String[] getArchiveTimestamps();
294
295  /**
296   * Get the timestamps of the files.  Used by internal
297   * DistributedCache and MapReduce code.
298   * @return a string array of timestamps 
299   */
300  public String[] getFileTimestamps();
301
302  /** 
303   * Get the configured number of maximum attempts that will be made to run a
304   * map task, as specified by the <code>mapred.map.max.attempts</code>
305   * property. If this property is not already set, the default is 4 attempts.
306   *  
307   * @return the max number of attempts per map task.
308   */
309  public int getMaxMapAttempts();
310
311  /** 
312   * Get the configured number of maximum attempts  that will be made to run a
313   * reduce task, as specified by the <code>mapred.reduce.max.attempts</code>
314   * property. If this property is not already set, the default is 4 attempts.
315   * 
316   * @return the max number of attempts per reduce task.
317   */
318  public int getMaxReduceAttempts();
319
320}