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 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       * This method checks to see if symlinks are to be create for the 
225       * localized cache files in the current working directory 
226       * @return true if symlinks are to be created- else return false
227       */
228      public boolean getSymlink();
229      
230      /**
231       * Get the archive entries in classpath as an array of Path
232       */
233      public Path[] getArchiveClassPaths();
234    
235      /**
236       * Get cache archives set in the Configuration
237       * @return A URI array of the caches set in the Configuration
238       * @throws IOException
239       */
240      public URI[] getCacheArchives() throws IOException;
241    
242      /**
243       * Get cache files set in the Configuration
244       * @return A URI array of the files set in the Configuration
245       * @throws IOException
246       */
247    
248      public URI[] getCacheFiles() throws IOException;
249    
250      /**
251       * Return the path array of the localized caches
252       * @return A path array of localized caches
253       * @throws IOException
254       */
255      public Path[] getLocalCacheArchives() throws IOException;
256    
257      /**
258       * Return the path array of the localized files
259       * @return A path array of localized files
260       * @throws IOException
261       */
262      public Path[] getLocalCacheFiles() throws IOException;
263    
264      /**
265       * Get the file entries in classpath as an array of Path
266       */
267      public Path[] getFileClassPaths();
268      
269      /**
270       * Get the timestamps of the archives.  Used by internal
271       * DistributedCache and MapReduce code.
272       * @return a string array of timestamps 
273       * @throws IOException
274       */
275      public String[] getArchiveTimestamps();
276    
277      /**
278       * Get the timestamps of the files.  Used by internal
279       * DistributedCache and MapReduce code.
280       * @return a string array of timestamps 
281       * @throws IOException
282       */
283      public String[] getFileTimestamps();
284    
285      /** 
286       * Get the configured number of maximum attempts that will be made to run a
287       * map task, as specified by the <code>mapred.map.max.attempts</code>
288       * property. If this property is not already set, the default is 4 attempts.
289       *  
290       * @return the max number of attempts per map task.
291       */
292      public int getMaxMapAttempts();
293    
294      /** 
295       * Get the configured number of maximum attempts  that will be made to run a
296       * reduce task, as specified by the <code>mapred.reduce.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 reduce task.
300       */
301      public int getMaxReduceAttempts();
302    
303    }