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 }