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    
019    package org.apache.hadoop.yarn.api.records;
020    
021    import org.apache.hadoop.classification.InterfaceAudience.LimitedPrivate;
022    import org.apache.hadoop.classification.InterfaceAudience.Private;
023    import org.apache.hadoop.classification.InterfaceAudience.Public;
024    import org.apache.hadoop.classification.InterfaceStability.Stable;
025    import org.apache.hadoop.classification.InterfaceStability.Unstable;
026    import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
027    import org.apache.hadoop.yarn.util.Records;
028    
029    /**
030     * <p><code>ApplicationSubmissionContext</code> represents all of the
031     * information needed by the <code>ResourceManager</code> to launch 
032     * the <code>ApplicationMaster</code> for an application.</p>
033     * 
034     * <p>It includes details such as:
035     *   <ul>
036     *     <li>{@link ApplicationId} of the application.</li>
037     *     <li>Application user.</li>
038     *     <li>Application name.</li>
039     *     <li>{@link Priority} of the application.</li>
040     *     <li>
041     *       {@link ContainerLaunchContext} of the container in which the 
042     *       <code>ApplicationMaster</code> is executed.
043     *     </li>
044     *   </ul>
045     * </p>
046     * 
047     * @see ContainerLaunchContext
048     * @see ApplicationClientProtocol#submitApplication(org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest)
049     */
050    @Public
051    @Stable
052    public abstract class ApplicationSubmissionContext {
053    
054      @Public
055      @Stable
056      public static ApplicationSubmissionContext newInstance(
057          ApplicationId applicationId, String applicationName, String queue,
058          Priority priority, ContainerLaunchContext amContainer,
059          boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
060          int maxAppAttempts, Resource resource, String applicationType) {
061        ApplicationSubmissionContext context =
062            Records.newRecord(ApplicationSubmissionContext.class);
063        context.setApplicationId(applicationId);
064        context.setApplicationName(applicationName);
065        context.setQueue(queue);
066        context.setPriority(priority);
067        context.setAMContainerSpec(amContainer);
068        context.setUnmanagedAM(isUnmanagedAM);
069        context.setCancelTokensWhenComplete(cancelTokensWhenComplete);
070        context.setMaxAppAttempts(maxAppAttempts);
071        context.setResource(resource);
072        context.setApplicationType(applicationType);
073        return context;
074      }
075    
076      @Public
077      @Stable
078      public static ApplicationSubmissionContext newInstance(
079          ApplicationId applicationId, String applicationName, String queue,
080          Priority priority, ContainerLaunchContext amContainer,
081          boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
082          int maxAppAttempts, Resource resource) {
083        return newInstance(applicationId, applicationName, queue, priority,
084          amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
085          resource, null);
086      }
087    
088      /**
089       * Get the <code>ApplicationId</code> of the submitted application.
090       * @return <code>ApplicationId</code> of the submitted application
091       */
092      @Public
093      @Stable
094      public abstract ApplicationId getApplicationId();
095      
096      /**
097       * Set the <code>ApplicationId</code> of the submitted application.
098       * @param applicationId <code>ApplicationId</code> of the submitted
099       *                      application
100       */
101      @Public
102      @Stable
103      public abstract void setApplicationId(ApplicationId applicationId);
104    
105      /**
106       * Get the application <em>name</em>.
107       * @return application name
108       */
109      @Public
110      @Stable
111      public abstract String getApplicationName();
112      
113      /**
114       * Set the application <em>name</em>.
115       * @param applicationName application name
116       */
117      @Public
118      @Stable
119      public abstract void setApplicationName(String applicationName);
120      
121      /**
122       * Get the <em>queue</em> to which the application is being submitted.
123       * @return <em>queue</em> to which the application is being submitted
124       */
125      @Public
126      @Stable
127      public abstract String getQueue();
128      
129      /**
130       * Set the <em>queue</em> to which the application is being submitted
131       * @param queue <em>queue</em> to which the application is being submitted
132       */
133      @Public
134      @Stable
135      public abstract void setQueue(String queue);
136      
137      /**
138       * Get the <code>Priority</code> of the application.
139       * @return <code>Priority</code> of the application
140       */
141      @Public
142      @Stable
143      public abstract Priority getPriority();
144    
145      /**
146       * Set the <code>Priority</code> of the application.
147       * @param priority <code>Priority</code> of the application
148       */
149      @Private
150      @Unstable
151      public abstract void setPriority(Priority priority);
152    
153      /**
154       * Get the <code>ContainerLaunchContext</code> to describe the 
155       * <code>Container</code> with which the <code>ApplicationMaster</code> is
156       * launched.
157       * @return <code>ContainerLaunchContext</code> for the 
158       *         <code>ApplicationMaster</code> container
159       */
160      @Public
161      @Stable
162      public abstract ContainerLaunchContext getAMContainerSpec();
163      
164      /**
165       * Set the <code>ContainerLaunchContext</code> to describe the 
166       * <code>Container</code> with which the <code>ApplicationMaster</code> is
167       * launched.
168       * @param amContainer <code>ContainerLaunchContext</code> for the 
169       *                    <code>ApplicationMaster</code> container
170       */
171      @Public
172      @Stable
173      public abstract void setAMContainerSpec(ContainerLaunchContext amContainer);
174      
175      /**
176       * Get if the RM should manage the execution of the AM. 
177       * If true, then the RM 
178       * will not allocate a container for the AM and start it. It will expect the 
179       * AM to be launched and connect to the RM within the AM liveliness period and 
180       * fail the app otherwise. The client should launch the AM only after the RM 
181       * has ACCEPTED the application and changed the <code>YarnApplicationState</code>.
182       * Such apps will not be retried by the RM on app attempt failure.
183       * The default value is false.
184       * @return true if the AM is not managed by the RM
185       */
186      @Public
187      @Stable
188      public abstract boolean getUnmanagedAM();
189      
190      /**
191       * @param value true if RM should not manage the AM
192       */
193      @Public
194      @Stable
195      public abstract void setUnmanagedAM(boolean value);
196    
197      /**
198       * @return true if tokens should be canceled when the app completes.
199       */
200      @LimitedPrivate("mapreduce")
201      @Unstable
202      public abstract boolean getCancelTokensWhenComplete();
203      
204      /**
205       * Set to false if tokens should not be canceled when the app finished else
206       * false.  WARNING: this is not recommended unless you want your single job
207       * tokens to be reused by others jobs.
208       * @param cancel true if tokens should be canceled when the app finishes. 
209       */
210      @LimitedPrivate("mapreduce")
211      @Unstable
212      public abstract void setCancelTokensWhenComplete(boolean cancel);
213    
214      /**
215       * @return the number of max attempts of the application to be submitted
216       */
217      @Public
218      @Stable
219      public abstract int getMaxAppAttempts();
220    
221      /**
222       * Set the number of max attempts of the application to be submitted. WARNING:
223       * it should be no larger than the global number of max attempts in the Yarn
224       * configuration.
225       * @param maxAppAttempts the number of max attempts of the application
226       * to be submitted.
227       */
228      @Public
229      @Stable
230      public abstract void setMaxAppAttempts(int maxAppAttempts);
231    
232      /**
233       * Get the resource required by the <code>ApplicationMaster</code> for this
234       * application.
235       * 
236       * @return the resource required by the <code>ApplicationMaster</code> for
237       *         this application.
238       */
239      @Public
240      @Stable
241      public abstract Resource getResource();
242    
243      /**
244       * Set the resource required by the <code>ApplicationMaster</code> for this
245       * application.
246       *
247       * @param resource the resource required by the <code>ApplicationMaster</code>
248       * for this application.
249       */
250      @Public
251      @Stable
252      public abstract void setResource(Resource resource);
253      
254      /**
255       * Get the application type
256       * 
257       * @return the application type
258       */
259      @Public
260      @Stable
261      public abstract String getApplicationType();
262    
263      /**
264       * Set the application type
265       * 
266       * @param applicationType the application type
267       */
268      @Public
269      @Stable
270      public abstract void setApplicationType(String applicationType);
271    }