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; 020 021 import java.io.IOException; 022 023 import org.apache.hadoop.classification.InterfaceAudience.Private; 024 import org.apache.hadoop.classification.InterfaceAudience.Public; 025 import org.apache.hadoop.classification.InterfaceStability.Stable; 026 import org.apache.hadoop.classification.InterfaceStability.Unstable; 027 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest; 028 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse; 029 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsRequest; 030 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsResponse; 031 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest; 032 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse; 033 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest; 034 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse; 035 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest; 036 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse; 037 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest; 038 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse; 039 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest; 040 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse; 041 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest; 042 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse; 043 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest; 044 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse; 045 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest; 046 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse; 047 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest; 048 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse; 049 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest; 050 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse; 051 import org.apache.hadoop.yarn.api.records.ApplicationId; 052 import org.apache.hadoop.yarn.api.records.ApplicationReport; 053 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 054 import org.apache.hadoop.yarn.api.records.NodeReport; 055 import org.apache.hadoop.yarn.api.records.Resource; 056 import org.apache.hadoop.yarn.api.records.ResourceRequest; 057 import org.apache.hadoop.yarn.api.records.Token; 058 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics; 059 import org.apache.hadoop.yarn.exceptions.YarnException; 060 061 /** 062 * <p>The protocol between clients and the <code>ResourceManager</code> 063 * to submit/abort jobs and to get information on applications, cluster metrics, 064 * nodes, queues and ACLs.</p> 065 */ 066 @Public 067 @Stable 068 public interface ApplicationClientProtocol { 069 /** 070 * <p>The interface used by clients to obtain a new {@link ApplicationId} for 071 * submitting new applications.</p> 072 * 073 * <p>The <code>ResourceManager</code> responds with a new, monotonically 074 * increasing, {@link ApplicationId} which is used by the client to submit 075 * a new application.</p> 076 * 077 * <p>The <code>ResourceManager</code> also responds with details such 078 * as maximum resource capabilities in the cluster as specified in 079 * {@link GetNewApplicationResponse}.</p> 080 * 081 * @param request request to get a new <code>ApplicationId</code> 082 * @return response containing the new <code>ApplicationId</code> to be used 083 * to submit an application 084 * @throws YarnException 085 * @throws IOException 086 * @see #submitApplication(SubmitApplicationRequest) 087 */ 088 @Public 089 @Stable 090 public GetNewApplicationResponse getNewApplication( 091 GetNewApplicationRequest request) 092 throws YarnException, IOException; 093 094 /** 095 * <p>The interface used by clients to submit a new application to the 096 * <code>ResourceManager.</code></p> 097 * 098 * <p>The client is required to provide details such as queue, 099 * {@link Resource} required to run the <code>ApplicationMaster</code>, 100 * the equivalent of {@link ContainerLaunchContext} for launching 101 * the <code>ApplicationMaster</code> etc. via the 102 * {@link SubmitApplicationRequest}.</p> 103 * 104 * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 105 * {@link SubmitApplicationResponse} on accepting the submission and throws 106 * an exception if it rejects the submission. However, this call needs to be 107 * followed by {@link #getApplicationReport(GetApplicationReportRequest)} 108 * to make sure that the application gets properly submitted.</p> 109 * 110 * <p> In secure mode,the <code>ResourceManager</code> verifies access to 111 * queues etc. before accepting the application submission.</p> 112 * 113 * @param request request to submit a new application 114 * @return (empty) response on accepting the submission 115 * @throws YarnException 116 * @throws IOException 117 * @throws InvalidResourceRequestException 118 * The exception is thrown when a {@link ResourceRequest} is out of 119 * the range of the configured lower and upper resource boundaries. 120 * @see #getNewApplication(GetNewApplicationRequest) 121 */ 122 @Public 123 @Stable 124 public SubmitApplicationResponse submitApplication( 125 SubmitApplicationRequest request) 126 throws YarnException, IOException; 127 128 /** 129 * <p>The interface used by clients to request the 130 * <code>ResourceManager</code> to abort submitted application.</p> 131 * 132 * <p>The client, via {@link KillApplicationRequest} provides the 133 * {@link ApplicationId} of the application to be aborted.</p> 134 * 135 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 136 * application, queue etc. before terminating the application.</p> 137 * 138 * <p>Currently, the <code>ResourceManager</code> returns an empty response 139 * on success and throws an exception on rejecting the request.</p> 140 * 141 * @param request request to abort a submitted application 142 * @return <code>ResourceManager</code> returns an empty response 143 * on success and throws an exception on rejecting the request 144 * @throws YarnException 145 * @throws IOException 146 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 147 */ 148 @Public 149 @Stable 150 public KillApplicationResponse forceKillApplication( 151 KillApplicationRequest request) 152 throws YarnException, IOException; 153 154 /** 155 * <p>The interface used by clients to get a report of an Application from 156 * the <code>ResourceManager</code>.</p> 157 * 158 * <p>The client, via {@link GetApplicationReportRequest} provides the 159 * {@link ApplicationId} of the application.</p> 160 * 161 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 162 * application, queue etc. before accepting the request.</p> 163 * 164 * <p>The <code>ResourceManager</code> responds with a 165 * {@link GetApplicationReportResponse} which includes the 166 * {@link ApplicationReport} for the application.</p> 167 * 168 * <p>If the user does not have <code>VIEW_APP</code> access then the 169 * following fields in the report will be set to stubbed values: 170 * <ul> 171 * <li>host - set to "N/A"</li> 172 * <li>RPC port - set to -1</li> 173 * <li>client token - set to "N/A"</li> 174 * <li>diagnostics - set to "N/A"</li> 175 * <li>tracking URL - set to "N/A"</li> 176 * <li>original tracking URL - set to "N/A"</li> 177 * <li>resource usage report - all values are -1</li> 178 * </ul></p> 179 * 180 * @param request request for an application report 181 * @return application report 182 * @throws YarnException 183 * @throws IOException 184 */ 185 @Public 186 @Stable 187 public GetApplicationReportResponse getApplicationReport( 188 GetApplicationReportRequest request) 189 throws YarnException, IOException; 190 191 /** 192 * <p>The interface used by clients to get metrics about the cluster from 193 * the <code>ResourceManager</code>.</p> 194 * 195 * <p>The <code>ResourceManager</code> responds with a 196 * {@link GetClusterMetricsResponse} which includes the 197 * {@link YarnClusterMetrics} with details such as number of current 198 * nodes in the cluster.</p> 199 * 200 * @param request request for cluster metrics 201 * @return cluster metrics 202 * @throws YarnException 203 * @throws IOException 204 */ 205 @Public 206 @Stable 207 public GetClusterMetricsResponse getClusterMetrics( 208 GetClusterMetricsRequest request) 209 throws YarnException, IOException; 210 211 /** 212 * <p>The interface used by clients to get a report of Applications 213 * matching the filters defined by {@link GetApplicationsRequest} 214 * in the cluster from the <code>ResourceManager</code>.</p> 215 * 216 * <p>The <code>ResourceManager</code> responds with a 217 * {@link GetApplicationsResponse} which includes the 218 * {@link ApplicationReport} for the applications.</p> 219 * 220 * <p>If the user does not have <code>VIEW_APP</code> access for an 221 * application then the corresponding report will be filtered as 222 * described in {@link #getApplicationReport(GetApplicationReportRequest)}. 223 * </p> 224 * 225 * @param request request for report on applications 226 * @return report on applications matching the given application types 227 * defined in the request 228 * @throws YarnException 229 * @throws IOException 230 * @see GetApplicationsRequest 231 */ 232 @Public 233 @Stable 234 public GetApplicationsResponse getApplications( 235 GetApplicationsRequest request) 236 throws YarnException, IOException; 237 238 /** 239 * <p>The interface used by clients to get a report of all nodes 240 * in the cluster from the <code>ResourceManager</code>.</p> 241 * 242 * <p>The <code>ResourceManager</code> responds with a 243 * {@link GetClusterNodesResponse} which includes the 244 * {@link NodeReport} for all the nodes in the cluster.</p> 245 * 246 * @param request request for report on all nodes 247 * @return report on all nodes 248 * @throws YarnException 249 * @throws IOException 250 */ 251 @Public 252 @Stable 253 public GetClusterNodesResponse getClusterNodes( 254 GetClusterNodesRequest request) 255 throws YarnException, IOException; 256 257 /** 258 * <p>The interface used by clients to get information about <em>queues</em> 259 * from the <code>ResourceManager</code>.</p> 260 * 261 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such 262 * as used/total resources, child queues, running applications etc.</p> 263 * 264 * <p> In secure mode,the <code>ResourceManager</code> verifies access before 265 * providing the information.</p> 266 * 267 * @param request request to get queue information 268 * @return queue information 269 * @throws YarnException 270 * @throws IOException 271 */ 272 @Public 273 @Stable 274 public GetQueueInfoResponse getQueueInfo( 275 GetQueueInfoRequest request) 276 throws YarnException, IOException; 277 278 /** 279 * <p>The interface used by clients to get information about <em>queue 280 * acls</em> for <em>current user</em> from the <code>ResourceManager</code>. 281 * </p> 282 * 283 * <p>The <code>ResourceManager</code> responds with queue acls for all 284 * existing queues.</p> 285 * 286 * @param request request to get queue acls for <em>current user</em> 287 * @return queue acls for <em>current user</em> 288 * @throws YarnException 289 * @throws IOException 290 */ 291 @Public 292 @Stable 293 public GetQueueUserAclsInfoResponse getQueueUserAcls( 294 GetQueueUserAclsInfoRequest request) 295 throws YarnException, IOException; 296 297 /** 298 * <p>The interface used by clients to get delegation token, enabling the 299 * containers to be able to talk to the service using those tokens. 300 * 301 * <p> The <code>ResourceManager</code> responds with the delegation 302 * {@link Token} that can be used by the client to speak to this 303 * service. 304 * @param request request to get a delegation token for the client. 305 * @return delegation token that can be used to talk to this service 306 * @throws YarnException 307 * @throws IOException 308 */ 309 @Public 310 @Stable 311 public GetDelegationTokenResponse getDelegationToken( 312 GetDelegationTokenRequest request) 313 throws YarnException, IOException; 314 315 /** 316 * Renew an existing delegation {@link Token}. 317 * 318 * @param request the delegation token to be renewed. 319 * @return the new expiry time for the delegation token. 320 * @throws YarnException 321 * @throws IOException 322 */ 323 @Private 324 @Unstable 325 public RenewDelegationTokenResponse renewDelegationToken( 326 RenewDelegationTokenRequest request) throws YarnException, 327 IOException; 328 329 /** 330 * Cancel an existing delegation {@link Token}. 331 * 332 * @param request the delegation token to be cancelled. 333 * @return an empty response. 334 * @throws YarnException 335 * @throws IOException 336 */ 337 @Private 338 @Unstable 339 public CancelDelegationTokenResponse cancelDelegationToken( 340 CancelDelegationTokenRequest request) throws YarnException, 341 IOException; 342 }