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 }