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 * <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
068public 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}