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.Set; 022 023import org.apache.hadoop.classification.InterfaceAudience.LimitedPrivate; 024import org.apache.hadoop.classification.InterfaceAudience.Private; 025import org.apache.hadoop.classification.InterfaceAudience.Public; 026import org.apache.hadoop.classification.InterfaceStability.Evolving; 027import org.apache.hadoop.classification.InterfaceStability.Stable; 028import org.apache.hadoop.classification.InterfaceStability.Unstable; 029import org.apache.hadoop.yarn.api.ApplicationClientProtocol; 030import org.apache.hadoop.yarn.api.ApplicationMasterProtocol; 031import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest; 032import org.apache.hadoop.yarn.conf.YarnConfiguration; 033import org.apache.hadoop.yarn.util.Records; 034 035/** 036 * {@code ApplicationSubmissionContext} represents all of the 037 * information needed by the {@code ResourceManager} to launch 038 * the {@code ApplicationMaster} for an application. 039 * <p> 040 * 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> 051 * maxAppAttempts. The maximum number of application attempts. 052 * It should be no larger than the global number of max attempts in the 053 * Yarn configuration. 054 * </li> 055 * <li> 056 * attemptFailuresValidityInterval. The default value is -1. 057 * when attemptFailuresValidityInterval in milliseconds is set to 058 * {@literal >} 0, the failure number will no take failures which happen 059 * out of the validityInterval into failure count. If failure count 060 * reaches to maxAppAttempts, the application will be failed. 061 * </li> 062 * <li>Optional, application-specific {@link LogAggregationContext}</li> 063 * </ul> 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.setAMContainerResourceRequest(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.setNodeLabelExpression(appLabelExpression); 161 context.setAMContainerResourceRequest(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 ResourceRequest of AM container, if this is not null, scheduler will 457 * use this to acquire resource for AM container. 458 * 459 * If this is null, scheduler will assemble a ResourceRequest by using 460 * <em>getResource</em> and <em>getPriority</em> of 461 * <em>ApplicationSubmissionContext</em>. 462 * 463 * Number of containers and Priority will be ignore. 464 * 465 * @return ResourceRequest of AM container 466 */ 467 @Public 468 @Evolving 469 public abstract ResourceRequest getAMContainerResourceRequest(); 470 471 /** 472 * Set ResourceRequest of AM container 473 * @param request of AM container 474 */ 475 @Public 476 @Evolving 477 public abstract void setAMContainerResourceRequest(ResourceRequest request); 478 479 /** 480 * Get the attemptFailuresValidityInterval in milliseconds for the application 481 * 482 * @return the attemptFailuresValidityInterval 483 */ 484 @Public 485 @Stable 486 public abstract long getAttemptFailuresValidityInterval(); 487 488 /** 489 * Set the attemptFailuresValidityInterval in milliseconds for the application 490 * @param attemptFailuresValidityInterval 491 */ 492 @Public 493 @Stable 494 public abstract void setAttemptFailuresValidityInterval( 495 long attemptFailuresValidityInterval); 496 497 /** 498 * Get <code>LogAggregationContext</code> of the application 499 * 500 * @return <code>LogAggregationContext</code> of the application 501 */ 502 @Public 503 @Stable 504 public abstract LogAggregationContext getLogAggregationContext(); 505 506 /** 507 * Set <code>LogAggregationContext</code> for the application 508 * 509 * @param logAggregationContext 510 * for the application 511 */ 512 @Public 513 @Stable 514 public abstract void setLogAggregationContext( 515 LogAggregationContext logAggregationContext); 516 517 /** 518 * Get the reservation id, that corresponds to a valid resource allocation in 519 * the scheduler (between start and end time of the corresponding reservation) 520 * 521 * @return the reservation id representing the unique id of the corresponding 522 * reserved resource allocation in the scheduler 523 */ 524 @Public 525 @Unstable 526 public abstract ReservationId getReservationID(); 527 528 /** 529 * Set the reservation id, that correspond to a valid resource allocation in 530 * the scheduler (between start and end time of the corresponding reservation) 531 * 532 * @param reservationID representing the unique id of the 533 * corresponding reserved resource allocation in the scheduler 534 */ 535 @Public 536 @Unstable 537 public abstract void setReservationID(ReservationId reservationID); 538}