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}