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.mapreduce;
020    
021    import java.io.IOException;
022    import java.net.URI;
023    
024    import org.apache.hadoop.classification.InterfaceAudience;
025    import org.apache.hadoop.classification.InterfaceStability;
026    import org.apache.hadoop.conf.Configuration;
027    import org.apache.hadoop.conf.Configuration.IntegerRanges;
028    import org.apache.hadoop.fs.Path;
029    import org.apache.hadoop.io.RawComparator;
030    import org.apache.hadoop.mapreduce.Mapper;
031    import 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
039    public 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       * @throws IOException
293       */
294      public String[] getArchiveTimestamps();
295    
296      /**
297       * Get the timestamps of the files.  Used by internal
298       * DistributedCache and MapReduce code.
299       * @return a string array of timestamps 
300       * @throws IOException
301       */
302      public String[] getFileTimestamps();
303    
304      /** 
305       * Get the configured number of maximum attempts that will be made to run a
306       * map task, as specified by the <code>mapred.map.max.attempts</code>
307       * property. If this property is not already set, the default is 4 attempts.
308       *  
309       * @return the max number of attempts per map task.
310       */
311      public int getMaxMapAttempts();
312    
313      /** 
314       * Get the configured number of maximum attempts  that will be made to run a
315       * reduce task, as specified by the <code>mapred.reduce.max.attempts</code>
316       * property. If this property is not already set, the default is 4 attempts.
317       * 
318       * @return the max number of attempts per reduce task.
319       */
320      public int getMaxReduceAttempts();
321    
322    }