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}