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.Unstable; 026 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest; 027 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse; 028 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportRequest; 029 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportResponse; 030 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsRequest; 031 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsResponse; 032 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest; 033 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse; 034 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsRequest; 035 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsResponse; 036 import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportRequest; 037 import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportResponse; 038 import org.apache.hadoop.yarn.api.protocolrecords.GetContainersRequest; 039 import org.apache.hadoop.yarn.api.protocolrecords.GetContainersResponse; 040 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest; 041 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse; 042 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest; 043 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse; 044 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId; 045 import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport; 046 import org.apache.hadoop.yarn.api.records.ApplicationId; 047 import org.apache.hadoop.yarn.api.records.ApplicationReport; 048 import org.apache.hadoop.yarn.api.records.ContainerId; 049 import org.apache.hadoop.yarn.api.records.ContainerReport; 050 import org.apache.hadoop.yarn.api.records.Token; 051 import org.apache.hadoop.yarn.exceptions.YarnException; 052 053 /** 054 * <p> 055 * The protocol between clients and the <code>ApplicationHistoryServer</code> to 056 * get the information of completed applications etc. 057 * </p> 058 */ 059 @Public 060 @Unstable 061 public interface ApplicationHistoryProtocol { 062 063 /** 064 * <p> 065 * The interface used by clients to get a report of an Application from the 066 * <code>ResourceManager</code>. 067 * </p> 068 * 069 * <p> 070 * The client, via {@link GetApplicationReportRequest} provides the 071 * {@link ApplicationId} of the application. 072 * </p> 073 * 074 * <p> 075 * In secure mode,the <code>ApplicationHistoryServer</code> verifies access to 076 * the application, queue etc. before accepting the request. 077 * </p> 078 * 079 * <p> 080 * The <code>ApplicationHistoryServer</code> responds with a 081 * {@link GetApplicationReportResponse} which includes the 082 * {@link ApplicationReport} for the application. 083 * </p> 084 * 085 * <p> 086 * If the user does not have <code>VIEW_APP</code> access then the following 087 * fields in the report will be set to stubbed values: 088 * <ul> 089 * <li>host - set to "N/A"</li> 090 * <li>RPC port - set to -1</li> 091 * <li>client token - set to "N/A"</li> 092 * <li>diagnostics - set to "N/A"</li> 093 * <li>tracking URL - set to "N/A"</li> 094 * <li>original tracking URL - set to "N/A"</li> 095 * <li>resource usage report - all values are -1</li> 096 * </ul> 097 * </p> 098 * 099 * @param request 100 * request for an application report 101 * @return application report 102 * @throws YarnException 103 * @throws IOException 104 */ 105 @Public 106 @Unstable 107 public GetApplicationReportResponse getApplicationReport( 108 GetApplicationReportRequest request) throws YarnException, IOException; 109 110 /** 111 * <p> 112 * The interface used by clients to get a report of all Applications in the 113 * cluster from the <code>ApplicationHistoryServer</code>. 114 * </p> 115 * 116 * <p> 117 * The <code>ApplicationHistoryServer</code> responds with a 118 * {@link GetApplicationsResponse} which includes a list of 119 * {@link ApplicationReport} for all the applications. 120 * </p> 121 * 122 * <p> 123 * If the user does not have <code>VIEW_APP</code> access for an application 124 * then the corresponding report will be filtered as described in 125 * {@link #getApplicationReport(GetApplicationReportRequest)}. 126 * </p> 127 * 128 * @param request 129 * request for reports on all the applications 130 * @return report on applications matching the given application types defined 131 * in the request 132 * @throws YarnException 133 * @throws IOException 134 */ 135 @Public 136 @Unstable 137 public GetApplicationsResponse 138 getApplications(GetApplicationsRequest request) throws YarnException, 139 IOException; 140 141 /** 142 * <p> 143 * The interface used by clients to get a report of an Application Attempt 144 * from the <code>ApplicationHistoryServer</code>. 145 * </p> 146 * 147 * <p> 148 * The client, via {@link GetApplicationAttemptReportRequest} provides the 149 * {@link ApplicationAttemptId} of the application attempt. 150 * </p> 151 * 152 * <p> 153 * In secure mode,the <code>ApplicationHistoryServer</code> verifies access to 154 * the method before accepting the request. 155 * </p> 156 * 157 * <p> 158 * The <code>ApplicationHistoryServer</code> responds with a 159 * {@link GetApplicationAttemptReportResponse} which includes the 160 * {@link ApplicationAttemptReport} for the application attempt. 161 * </p> 162 * 163 * <p> 164 * If the user does not have <code>VIEW_APP</code> access then the following 165 * fields in the report will be set to stubbed values: 166 * <ul> 167 * <li>host</li> 168 * <li>RPC port</li> 169 * <li>client token</li> 170 * <li>diagnostics - set to "N/A"</li> 171 * <li>tracking URL</li> 172 * </ul> 173 * </p> 174 * 175 * @param request 176 * request for an application attempt report 177 * @return application attempt report 178 * @throws YarnException 179 * @throws IOException 180 */ 181 @Public 182 @Unstable 183 public GetApplicationAttemptReportResponse getApplicationAttemptReport( 184 GetApplicationAttemptReportRequest request) throws YarnException, 185 IOException; 186 187 /** 188 * <p> 189 * The interface used by clients to get a report of all Application attempts 190 * in the cluster from the <code>ApplicationHistoryServer</code>. 191 * </p> 192 * 193 * <p> 194 * The <code>ApplicationHistoryServer</code> responds with a 195 * {@link GetApplicationAttemptsRequest} which includes the 196 * {@link ApplicationAttemptReport} for all the applications attempts of a 197 * specified application attempt. 198 * </p> 199 * 200 * <p> 201 * If the user does not have <code>VIEW_APP</code> access for an application 202 * then the corresponding report will be filtered as described in 203 * {@link #getApplicationAttemptReport(GetApplicationAttemptReportRequest)}. 204 * </p> 205 * 206 * @param request 207 * request for reports on all application attempts of an application 208 * @return reports on all application attempts of an application 209 * @throws YarnException 210 * @throws IOException 211 */ 212 @Public 213 @Unstable 214 public GetApplicationAttemptsResponse getApplicationAttempts( 215 GetApplicationAttemptsRequest request) throws YarnException, IOException; 216 217 /** 218 * <p> 219 * The interface used by clients to get a report of an Container from the 220 * <code>ApplicationHistoryServer</code>. 221 * </p> 222 * 223 * <p> 224 * The client, via {@link GetContainerReportRequest} provides the 225 * {@link ContainerId} of the container. 226 * </p> 227 * 228 * <p> 229 * In secure mode,the <code>ApplicationHistoryServer</code> verifies access to 230 * the method before accepting the request. 231 * </p> 232 * 233 * <p> 234 * The <code>ApplicationHistoryServer</code> responds with a 235 * {@link GetContainerReportResponse} which includes the 236 * {@link ContainerReport} for the container. 237 * </p> 238 * 239 * @param request 240 * request for a container report 241 * @return container report 242 * @throws YarnException 243 * @throws IOException 244 */ 245 @Public 246 @Unstable 247 public GetContainerReportResponse getContainerReport( 248 GetContainerReportRequest request) throws YarnException, IOException; 249 250 /** 251 * <p> 252 * The interface used by clients to get a report of Containers for an 253 * application attempt from the <code>ApplciationHistoryServer</code>. 254 * </p> 255 * 256 * <p> 257 * The client, via {@link GetContainersRequest} provides the 258 * {@link ApplicationAttemptId} of the application attempt. 259 * </p> 260 * 261 * <p> 262 * In secure mode,the <code>ApplicationHistoryServer</code> verifies access to 263 * the method before accepting the request. 264 * </p> 265 * 266 * <p> 267 * The <code>ApplicationHistoryServer</code> responds with a 268 * {@link GetContainersResponse} which includes a list of 269 * {@link ContainerReport} for all the containers of a specific application 270 * attempt. 271 * </p> 272 * 273 * @param request 274 * request for a list of container reports of an application attempt. 275 * @return reports on all containers of an application attempt 276 * @throws YarnException 277 * @throws IOException 278 */ 279 @Public 280 @Unstable 281 public GetContainersResponse getContainers(GetContainersRequest request) 282 throws YarnException, IOException; 283 284 /** 285 * <p> 286 * The interface used by clients to get delegation token, enabling the 287 * containers to be able to talk to the service using those tokens. 288 * </p> 289 * 290 * <p> 291 * The <code>ApplicationHistoryServer</code> responds with the delegation 292 * token {@link Token} that can be used by the client to speak to this 293 * service. 294 * </p> 295 * 296 * @param request 297 * request to get a delegation token for the client. 298 * @return delegation token that can be used to talk to this service 299 * @throws YarnException 300 * @throws IOException 301 */ 302 @Public 303 @Unstable 304 public GetDelegationTokenResponse getDelegationToken( 305 GetDelegationTokenRequest request) throws YarnException, IOException; 306 307 /** 308 * Renew an existing delegation token. 309 * 310 * @param request 311 * the delegation token to be renewed. 312 * @return the new expiry time for the delegation token. 313 * @throws YarnException 314 * @throws IOException 315 */ 316 @Private 317 @Unstable 318 public RenewDelegationTokenResponse renewDelegationToken( 319 RenewDelegationTokenRequest request) throws YarnException, IOException; 320 321 /** 322 * Cancel an existing delegation token. 323 * 324 * @param request 325 * the delegation token to be cancelled. 326 * @return an empty response. 327 * @throws YarnException 328 * @throws IOException 329 */ 330 @Private 331 @Unstable 332 public CancelDelegationTokenResponse cancelDelegationToken( 333 CancelDelegationTokenRequest request) throws YarnException, IOException; 334 }