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.api.ApplicationMasterProtocol;
028 import org.apache.hadoop.yarn.conf.YarnConfiguration;
029 import org.apache.hadoop.yarn.util.Records;
030
031 import java.util.Set;
032
033 /**
034 * <p><code>ApplicationSubmissionContext</code> represents all of the
035 * information needed by the <code>ResourceManager</code> to launch
036 * the <code>ApplicationMaster</code> for an application.</p>
037 *
038 * <p>It includes details such as:
039 * <ul>
040 * <li>{@link ApplicationId} of the application.</li>
041 * <li>Application user.</li>
042 * <li>Application name.</li>
043 * <li>{@link Priority} of the application.</li>
044 * <li>
045 * {@link ContainerLaunchContext} of the container in which the
046 * <code>ApplicationMaster</code> is executed.
047 * </li>
048 * </ul>
049 * </p>
050 *
051 * @see ContainerLaunchContext
052 * @see ApplicationClientProtocol#submitApplication(org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest)
053 */
054 @Public
055 @Stable
056 public abstract class ApplicationSubmissionContext {
057
058 @Public
059 @Stable
060 public static ApplicationSubmissionContext newInstance(
061 ApplicationId applicationId, String applicationName, String queue,
062 Priority priority, ContainerLaunchContext amContainer,
063 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
064 int maxAppAttempts, Resource resource, String applicationType,
065 boolean keepContainers) {
066 ApplicationSubmissionContext context =
067 Records.newRecord(ApplicationSubmissionContext.class);
068 context.setApplicationId(applicationId);
069 context.setApplicationName(applicationName);
070 context.setQueue(queue);
071 context.setPriority(priority);
072 context.setAMContainerSpec(amContainer);
073 context.setUnmanagedAM(isUnmanagedAM);
074 context.setCancelTokensWhenComplete(cancelTokensWhenComplete);
075 context.setMaxAppAttempts(maxAppAttempts);
076 context.setResource(resource);
077 context.setApplicationType(applicationType);
078 context.setKeepContainersAcrossApplicationAttempts(keepContainers);
079 return context;
080 }
081
082 @Public
083 @Stable
084 public static ApplicationSubmissionContext newInstance(
085 ApplicationId applicationId, String applicationName, String queue,
086 Priority priority, ContainerLaunchContext amContainer,
087 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
088 int maxAppAttempts, Resource resource, String applicationType) {
089 return newInstance(applicationId, applicationName, queue, priority,
090 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
091 resource, null, false);
092 }
093
094 @Public
095 @Stable
096 public static ApplicationSubmissionContext newInstance(
097 ApplicationId applicationId, String applicationName, String queue,
098 Priority priority, ContainerLaunchContext amContainer,
099 boolean isUnmanagedAM, boolean cancelTokensWhenComplete,
100 int maxAppAttempts, Resource resource) {
101 return newInstance(applicationId, applicationName, queue, priority,
102 amContainer, isUnmanagedAM, cancelTokensWhenComplete, maxAppAttempts,
103 resource, null);
104 }
105
106 /**
107 * Get the <code>ApplicationId</code> of the submitted application.
108 * @return <code>ApplicationId</code> of the submitted application
109 */
110 @Public
111 @Stable
112 public abstract ApplicationId getApplicationId();
113
114 /**
115 * Set the <code>ApplicationId</code> of the submitted application.
116 * @param applicationId <code>ApplicationId</code> of the submitted
117 * application
118 */
119 @Public
120 @Stable
121 public abstract void setApplicationId(ApplicationId applicationId);
122
123 /**
124 * Get the application <em>name</em>.
125 * @return application name
126 */
127 @Public
128 @Stable
129 public abstract String getApplicationName();
130
131 /**
132 * Set the application <em>name</em>.
133 * @param applicationName application name
134 */
135 @Public
136 @Stable
137 public abstract void setApplicationName(String applicationName);
138
139 /**
140 * Get the <em>queue</em> to which the application is being submitted.
141 * @return <em>queue</em> to which the application is being submitted
142 */
143 @Public
144 @Stable
145 public abstract String getQueue();
146
147 /**
148 * Set the <em>queue</em> to which the application is being submitted
149 * @param queue <em>queue</em> to which the application is being submitted
150 */
151 @Public
152 @Stable
153 public abstract void setQueue(String queue);
154
155 /**
156 * Get the <code>Priority</code> of the application.
157 * @return <code>Priority</code> of the application
158 */
159 @Public
160 @Stable
161 public abstract Priority getPriority();
162
163 /**
164 * Set the <code>Priority</code> of the application.
165 * @param priority <code>Priority</code> of the application
166 */
167 @Private
168 @Unstable
169 public abstract void setPriority(Priority priority);
170
171 /**
172 * Get the <code>ContainerLaunchContext</code> to describe the
173 * <code>Container</code> with which the <code>ApplicationMaster</code> is
174 * launched.
175 * @return <code>ContainerLaunchContext</code> for the
176 * <code>ApplicationMaster</code> container
177 */
178 @Public
179 @Stable
180 public abstract ContainerLaunchContext getAMContainerSpec();
181
182 /**
183 * Set the <code>ContainerLaunchContext</code> to describe the
184 * <code>Container</code> with which the <code>ApplicationMaster</code> is
185 * launched.
186 * @param amContainer <code>ContainerLaunchContext</code> for the
187 * <code>ApplicationMaster</code> container
188 */
189 @Public
190 @Stable
191 public abstract void setAMContainerSpec(ContainerLaunchContext amContainer);
192
193 /**
194 * Get if the RM should manage the execution of the AM.
195 * If true, then the RM
196 * will not allocate a container for the AM and start it. It will expect the
197 * AM to be launched and connect to the RM within the AM liveliness period and
198 * fail the app otherwise. The client should launch the AM only after the RM
199 * has ACCEPTED the application and changed the <code>YarnApplicationState</code>.
200 * Such apps will not be retried by the RM on app attempt failure.
201 * The default value is false.
202 * @return true if the AM is not managed by the RM
203 */
204 @Public
205 @Stable
206 public abstract boolean getUnmanagedAM();
207
208 /**
209 * @param value true if RM should not manage the AM
210 */
211 @Public
212 @Stable
213 public abstract void setUnmanagedAM(boolean value);
214
215 /**
216 * @return true if tokens should be canceled when the app completes.
217 */
218 @LimitedPrivate("mapreduce")
219 @Unstable
220 public abstract boolean getCancelTokensWhenComplete();
221
222 /**
223 * Set to false if tokens should not be canceled when the app finished else
224 * false. WARNING: this is not recommended unless you want your single job
225 * tokens to be reused by others jobs.
226 * @param cancel true if tokens should be canceled when the app finishes.
227 */
228 @LimitedPrivate("mapreduce")
229 @Unstable
230 public abstract void setCancelTokensWhenComplete(boolean cancel);
231
232 /**
233 * @return the number of max attempts of the application to be submitted
234 */
235 @Public
236 @Stable
237 public abstract int getMaxAppAttempts();
238
239 /**
240 * Set the number of max attempts of the application to be submitted. WARNING:
241 * it should be no larger than the global number of max attempts in the Yarn
242 * configuration.
243 * @param maxAppAttempts the number of max attempts of the application
244 * to be submitted.
245 */
246 @Public
247 @Stable
248 public abstract void setMaxAppAttempts(int maxAppAttempts);
249
250 /**
251 * Get the resource required by the <code>ApplicationMaster</code> for this
252 * application.
253 *
254 * @return the resource required by the <code>ApplicationMaster</code> for
255 * this application.
256 */
257 @Public
258 @Stable
259 public abstract Resource getResource();
260
261 /**
262 * Set the resource required by the <code>ApplicationMaster</code> for this
263 * application.
264 *
265 * @param resource the resource required by the <code>ApplicationMaster</code>
266 * for this application.
267 */
268 @Public
269 @Stable
270 public abstract void setResource(Resource resource);
271
272 /**
273 * Get the application type
274 *
275 * @return the application type
276 */
277 @Public
278 @Stable
279 public abstract String getApplicationType();
280
281 /**
282 * Set the application type
283 *
284 * @param applicationType the application type
285 */
286 @Public
287 @Stable
288 public abstract void setApplicationType(String applicationType);
289
290 /**
291 * Get the flag which indicates whether to keep containers across application
292 * attempts or not.
293 *
294 * @return the flag which indicates whether to keep containers across
295 * application attempts or not.
296 */
297 @Public
298 @Stable
299 public abstract boolean getKeepContainersAcrossApplicationAttempts();
300
301 /**
302 * Set the flag which indicates whether to keep containers across application
303 * attempts.
304 * <p>
305 * If the flag is true, running containers will not be killed when application
306 * attempt fails and these containers will be retrieved by the new application
307 * attempt on registration via
308 * {@link ApplicationMasterProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)}.
309 * </p>
310 *
311 * @param keepContainers
312 * the flag which indicates whether to keep containers across
313 * application attempts.
314 */
315 @Public
316 @Stable
317 public abstract void setKeepContainersAcrossApplicationAttempts(
318 boolean keepContainers);
319
320 /**
321 * Get tags for the application
322 *
323 * @return the application tags
324 */
325 @Public
326 @Stable
327 public abstract Set<String> getApplicationTags();
328
329 /**
330 * Set tags for the application. A maximum of
331 * {@link YarnConfiguration#APPLICATION_MAX_TAGS} are allowed
332 * per application. Each tag can be at most
333 * {@link YarnConfiguration#APPLICATION_MAX_TAG_LENGTH}
334 * characters, and can contain only ASCII characters.
335 *
336 * @param tags tags to set
337 */
338 @Public
339 @Stable
340 public abstract void setApplicationTags(Set<String> tags);
341 }