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 }