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.yarn.api.records;
020
021 import java.util.Set;
022
023 import org.apache.hadoop.classification.InterfaceAudience.LimitedPrivate;
024 import org.apache.hadoop.classification.InterfaceAudience.Private;
025 import org.apache.hadoop.classification.InterfaceAudience.Public;
026 import org.apache.hadoop.classification.InterfaceStability.Evolving;
027 import org.apache.hadoop.classification.InterfaceStability.Stable;
028 import org.apache.hadoop.classification.InterfaceStability.Unstable;
029 import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
030 import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
031 import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest;
032 import org.apache.hadoop.yarn.conf.YarnConfiguration;
033 import org.apache.hadoop.yarn.util.Records;
034
035 /**
036 * <p><code>ApplicationSubmissionContext</code> represents all of the
037 * information needed by the <code>ResourceManager</code> to launch
038 * the <code>ApplicationMaster</code> for an application.</p>
039 *
040 * <p>It includes details such as:
041 * <ul>
042 * <li>{@link ApplicationId} of the application.</li>
043 * <li>Application user.</li>
044 * <li>Application name.</li>
045 * <li>{@link Priority} of the application.</li>
046 * <li>
047 * {@link ContainerLaunchContext} of the container in which the
048 * <code>ApplicationMaster</code> is executed.
049 * </li>
050 * <li>maxAppAttempts. The maximum number of application attempts.
051 * It should be no larger than the global number of max attempts in the
052 * Yarn configuration.</li>
053 * <li>attemptFailuresValidityInterval. The default value is -1.
054 * when attemptFailuresValidityInterval in milliseconds is set to > 0,
055 * the failure number will no take failures which happen out of the
056 * validityInterval into failure count. If failure count reaches to
057 * maxAppAttempts, the application will be failed.
058 * </li>
059 * <li>Optional, application-specific {@link LogAggregationContext}</li>
060 * </ul>
061 * </p>
062 *
063 * @see ContainerLaunchContext
064 * @see ApplicationClientProtocol#submitApplication(org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest)
065 */
066 @Public
067 @Stable
068 public abstract class ApplicationSubmissionContext {
069
070 @Public
071 @Stable
072 public static ApplicationSubmissionContext newInstance(
073 ApplicationId applicationId, String applicationName, String queue,
074 Priority priority, ContainerLaunchContext amContainer,
075 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
076 int maxAppAttempts, Resource resource, String applicationType,
077 boolean keepContainers, String appLabelExpression,
078 String amContainerLabelExpression) {
079 ApplicationSubmissionContext context =
080 Records.newRecord(ApplicationSubmissionContext.class);
081 context.setApplicationId(applicationId);
082 context.setApplicationName(applicationName);
083 context.setQueue(queue);
084 context.setPriority(priority);
085 context.setAMContainerSpec(amContainer);
086 context.setUnmanagedAM(isUnmanagedAM);
087 context.setCancelTokensWhenComplete(cancelTokensWhenComplete);
088 context.setMaxAppAttempts(maxAppAttempts);
089 context.setApplicationType(applicationType);
090 context.setKeepContainersAcrossApplicationAttempts(keepContainers);
091 context.setNodeLabelExpression(appLabelExpression);
092 context.setResource(resource);
093
094 ResourceRequest amReq = Records.newRecord(ResourceRequest.class);
095 amReq.setResourceName(ResourceRequest.ANY);
096 amReq.setCapability(resource);
097 amReq.setNumContainers(1);
098 amReq.setRelaxLocality(true);
099 amReq.setNodeLabelExpression(amContainerLabelExpression);
100 context.setAMContainerResourceRequest(amReq);
101 return context;
102 }
103
104 public static ApplicationSubmissionContext newInstance(
105 ApplicationId applicationId, String applicationName, String queue,
106 Priority priority, ContainerLaunchContext amContainer,
107 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
108 int maxAppAttempts, Resource resource, String applicationType,
109 boolean keepContainers) {
110 return newInstance(applicationId, applicationName, queue, priority,
111 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
112 resource, applicationType, keepContainers, null, null);
113 }
114
115 @Public
116 @Stable
117 public static ApplicationSubmissionContext newInstance(
118 ApplicationId applicationId, String applicationName, String queue,
119 Priority priority, ContainerLaunchContext amContainer,
120 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
121 int maxAppAttempts, Resource resource, String applicationType) {
122 return newInstance(applicationId, applicationName, queue, priority,
123 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
124 resource, applicationType, false, null, null);
125 }
126
127 @Public
128 @Stable
129 public static ApplicationSubmissionContext newInstance(
130 ApplicationId applicationId, String applicationName, String queue,
131 Priority priority, ContainerLaunchContext amContainer,
132 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
133 int maxAppAttempts, Resource resource) {
134 return newInstance(applicationId, applicationName, queue, priority,
135 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
136 resource, null);
137 }
138
139 @Public
140 @Stable
141 public static ApplicationSubmissionContext newInstance(
142 ApplicationId applicationId, String applicationName, String queue,
143 ContainerLaunchContext amContainer, boolean isUnmanagedAM,
144 boolean cancelTokensWhenComplete, int maxAppAttempts,
145 String applicationType, boolean keepContainers,
146 String appLabelExpression, ResourceRequest resourceRequest) {
147 ApplicationSubmissionContext context =
148 Records.newRecord(ApplicationSubmissionContext.class);
149 context.setApplicationId(applicationId);
150 context.setApplicationName(applicationName);
151 context.setQueue(queue);
152 context.setAMContainerSpec(amContainer);
153 context.setUnmanagedAM(isUnmanagedAM);
154 context.setCancelTokensWhenComplete(cancelTokensWhenComplete);
155 context.setMaxAppAttempts(maxAppAttempts);
156 context.setApplicationType(applicationType);
157 context.setKeepContainersAcrossApplicationAttempts(keepContainers);
158 context.setAMContainerResourceRequest(resourceRequest);
159 return context;
160 }
161
162 @Public
163 @Stable
164 public static ApplicationSubmissionContext newInstance(
165 ApplicationId applicationId, String applicationName, String queue,
166 Priority priority, ContainerLaunchContext amContainer,
167 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
168 int maxAppAttempts, Resource resource, String applicationType,
169 boolean keepContainers, long attemptFailuresValidityInterval) {
170 ApplicationSubmissionContext context =
171 newInstance(applicationId, applicationName, queue, priority,
172 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
173 resource, applicationType, keepContainers);
174 context.setAttemptFailuresValidityInterval(attemptFailuresValidityInterval);
175 return context;
176 }
177
178 @Public
179 @Stable
180 public static ApplicationSubmissionContext newInstance(
181 ApplicationId applicationId, String applicationName, String queue,
182 Priority priority, ContainerLaunchContext amContainer,
183 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
184 int maxAppAttempts, Resource resource, String applicationType,
185 boolean keepContainers, LogAggregationContext logAggregationContext) {
186 ApplicationSubmissionContext context =
187 newInstance(applicationId, applicationName, queue, priority,
188 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
189 resource, applicationType, keepContainers);
190 context.setLogAggregationContext(logAggregationContext);
191 return context;
192 }
193 /**
194 * Get the <code>ApplicationId</code> of the submitted application.
195 * @return <code>ApplicationId</code> of the submitted application
196 */
197 @Public
198 @Stable
199 public abstract ApplicationId getApplicationId();
200
201 /**
202 * Set the <code>ApplicationId</code> of the submitted application.
203 * @param applicationId <code>ApplicationId</code> of the submitted
204 * application
205 */
206 @Public
207 @Stable
208 public abstract void setApplicationId(ApplicationId applicationId);
209
210 /**
211 * Get the application <em>name</em>.
212 * @return application name
213 */
214 @Public
215 @Stable
216 public abstract String getApplicationName();
217
218 /**
219 * Set the application <em>name</em>.
220 * @param applicationName application name
221 */
222 @Public
223 @Stable
224 public abstract void setApplicationName(String applicationName);
225
226 /**
227 * Get the <em>queue</em> to which the application is being submitted.
228 * @return <em>queue</em> to which the application is being submitted
229 */
230 @Public
231 @Stable
232 public abstract String getQueue();
233
234 /**
235 * Set the <em>queue</em> to which the application is being submitted
236 * @param queue <em>queue</em> to which the application is being submitted
237 */
238 @Public
239 @Stable
240 public abstract void setQueue(String queue);
241
242 /**
243 * Get the <code>Priority</code> of the application.
244 * @return <code>Priority</code> of the application
245 */
246 @Public
247 @Stable
248 public abstract Priority getPriority();
249
250 /**
251 * Set the <code>Priority</code> of the application.
252 * @param priority <code>Priority</code> of the application
253 */
254 @Private
255 @Unstable
256 public abstract void setPriority(Priority priority);
257
258 /**
259 * Get the <code>ContainerLaunchContext</code> to describe the
260 * <code>Container</code> with which the <code>ApplicationMaster</code> is
261 * launched.
262 * @return <code>ContainerLaunchContext</code> for the
263 * <code>ApplicationMaster</code> container
264 */
265 @Public
266 @Stable
267 public abstract ContainerLaunchContext getAMContainerSpec();
268
269 /**
270 * Set the <code>ContainerLaunchContext</code> to describe the
271 * <code>Container</code> with which the <code>ApplicationMaster</code> is
272 * launched.
273 * @param amContainer <code>ContainerLaunchContext</code> for the
274 * <code>ApplicationMaster</code> container
275 */
276 @Public
277 @Stable
278 public abstract void setAMContainerSpec(ContainerLaunchContext amContainer);
279
280 /**
281 * Get if the RM should manage the execution of the AM.
282 * If true, then the RM
283 * will not allocate a container for the AM and start it. It will expect the
284 * AM to be launched and connect to the RM within the AM liveliness period and
285 * fail the app otherwise. The client should launch the AM only after the RM
286 * has ACCEPTED the application and changed the <code>YarnApplicationState</code>.
287 * Such apps will not be retried by the RM on app attempt failure.
288 * The default value is false.
289 * @return true if the AM is not managed by the RM
290 */
291 @Public
292 @Stable
293 public abstract boolean getUnmanagedAM();
294
295 /**
296 * @param value true if RM should not manage the AM
297 */
298 @Public
299 @Stable
300 public abstract void setUnmanagedAM(boolean value);
301
302 /**
303 * @return true if tokens should be canceled when the app completes.
304 */
305 @LimitedPrivate("mapreduce")
306 @Unstable
307 public abstract boolean getCancelTokensWhenComplete();
308
309 /**
310 * Set to false if tokens should not be canceled when the app finished else
311 * false. WARNING: this is not recommended unless you want your single job
312 * tokens to be reused by others jobs.
313 * @param cancel true if tokens should be canceled when the app finishes.
314 */
315 @LimitedPrivate("mapreduce")
316 @Unstable
317 public abstract void setCancelTokensWhenComplete(boolean cancel);
318
319 /**
320 * @return the number of max attempts of the application to be submitted
321 */
322 @Public
323 @Stable
324 public abstract int getMaxAppAttempts();
325
326 /**
327 * Set the number of max attempts of the application to be submitted. WARNING:
328 * it should be no larger than the global number of max attempts in the Yarn
329 * configuration.
330 * @param maxAppAttempts the number of max attempts of the application
331 * to be submitted.
332 */
333 @Public
334 @Stable
335 public abstract void setMaxAppAttempts(int maxAppAttempts);
336
337 /**
338 * Get the resource required by the <code>ApplicationMaster</code> for this
339 * application. Please note this will be DEPRECATED, use <em>getResource</em>
340 * in <em>getAMContainerResourceRequest</em> instead.
341 *
342 * @return the resource required by the <code>ApplicationMaster</code> for
343 * this application.
344 */
345 @Public
346 public abstract Resource getResource();
347
348 /**
349 * Set the resource required by the <code>ApplicationMaster</code> for this
350 * application.
351 *
352 * @param resource the resource required by the <code>ApplicationMaster</code>
353 * for this application.
354 */
355 @Public
356 public abstract void setResource(Resource resource);
357
358 /**
359 * Get the application type
360 *
361 * @return the application type
362 */
363 @Public
364 @Stable
365 public abstract String getApplicationType();
366
367 /**
368 * Set the application type
369 *
370 * @param applicationType the application type
371 */
372 @Public
373 @Stable
374 public abstract void setApplicationType(String applicationType);
375
376 /**
377 * Get the flag which indicates whether to keep containers across application
378 * attempts or not.
379 *
380 * @return the flag which indicates whether to keep containers across
381 * application attempts or not.
382 */
383 @Public
384 @Stable
385 public abstract boolean getKeepContainersAcrossApplicationAttempts();
386
387 /**
388 * Set the flag which indicates whether to keep containers across application
389 * attempts.
390 * <p>
391 * If the flag is true, running containers will not be killed when application
392 * attempt fails and these containers will be retrieved by the new application
393 * attempt on registration via
394 * {@link ApplicationMasterProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)}.
395 * </p>
396 *
397 * @param keepContainers
398 * the flag which indicates whether to keep containers across
399 * application attempts.
400 */
401 @Public
402 @Stable
403 public abstract void setKeepContainersAcrossApplicationAttempts(
404 boolean keepContainers);
405
406 /**
407 * Get tags for the application
408 *
409 * @return the application tags
410 */
411 @Public
412 @Stable
413 public abstract Set<String> getApplicationTags();
414
415 /**
416 * Set tags for the application. A maximum of
417 * {@link YarnConfiguration#APPLICATION_MAX_TAGS} are allowed
418 * per application. Each tag can be at most
419 * {@link YarnConfiguration#APPLICATION_MAX_TAG_LENGTH}
420 * characters, and can contain only ASCII characters.
421 *
422 * @param tags tags to set
423 */
424 @Public
425 @Stable
426 public abstract void setApplicationTags(Set<String> tags);
427
428 /**
429 * Get node-label-expression for this app. If this is set, all containers of
430 * this application without setting node-label-expression in ResurceRequest
431 * will get allocated resources on only those nodes that satisfy this
432 * node-label-expression.
433 *
434 * If different node-label-expression of this app and ResourceRequest are set
435 * at the same time, the one set in ResourceRequest will be used when
436 * allocating container
437 *
438 * @return node-label-expression for this app
439 */
440 @Public
441 @Evolving
442 public abstract String getNodeLabelExpression();
443
444 /**
445 * Set node-label-expression for this app
446 * @param nodeLabelExpression node-label-expression of this app
447 */
448 @Public
449 @Evolving
450 public abstract void setNodeLabelExpression(String nodeLabelExpression);
451
452 /**
453 * Get ResourceRequest of AM container, if this is not null, scheduler will
454 * use this to acquire resource for AM container.
455 *
456 * If this is null, scheduler will assemble a ResourceRequest by using
457 * <em>getResource</em> and <em>getPriority</em> of
458 * <em>ApplicationSubmissionContext</em>.
459 *
460 * Number of containers and Priority will be ignore.
461 *
462 * @return ResourceRequest of AM container
463 */
464 @Public
465 @Evolving
466 public abstract ResourceRequest getAMContainerResourceRequest();
467
468 /**
469 * Set ResourceRequest of AM container
470 * @param request of AM container
471 */
472 @Public
473 @Evolving
474 public abstract void setAMContainerResourceRequest(ResourceRequest request);
475
476 /**
477 * Get the attemptFailuresValidityInterval in milliseconds for the application
478 *
479 * @return the attemptFailuresValidityInterval
480 */
481 @Public
482 @Stable
483 public abstract long getAttemptFailuresValidityInterval();
484
485 /**
486 * Set the attemptFailuresValidityInterval in milliseconds for the application
487 * @param attemptFailuresValidityInterval
488 */
489 @Public
490 @Stable
491 public abstract void setAttemptFailuresValidityInterval(
492 long attemptFailuresValidityInterval);
493
494 /**
495 * Get <code>LogAggregationContext</code> of the application
496 *
497 * @return <code>LogAggregationContext</code> of the application
498 */
499 @Public
500 @Stable
501 public abstract LogAggregationContext getLogAggregationContext();
502
503 /**
504 * Set <code>LogAggregationContext</code> for the application
505 *
506 * @param logAggregationContext
507 * for the application
508 */
509 @Public
510 @Stable
511 public abstract void setLogAggregationContext(
512 LogAggregationContext logAggregationContext);
513
514 /**
515 * Get the reservation id, that corresponds to a valid resource allocation in
516 * the scheduler (between start and end time of the corresponding reservation)
517 *
518 * @return the reservation id representing the unique id of the corresponding
519 * reserved resource allocation in the scheduler
520 */
521 @Public
522 @Unstable
523 public abstract ReservationId getReservationID();
524
525 /**
526 * Set the reservation id, that correspond to a valid resource allocation in
527 * the scheduler (between start and end time of the corresponding reservation)
528 *
529 * @param reservationID representing the unique id of the
530 * corresponding reserved resource allocation in the scheduler
531 */
532 @Public
533 @Unstable
534 public abstract void setReservationID(ReservationId reservationID);
535 }