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, applicationType, 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 }