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