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 * 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 }