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
019package org.apache.hadoop.yarn.api;
020
021import java.io.IOException;
022
023import org.apache.hadoop.classification.InterfaceAudience.Private;
024import org.apache.hadoop.classification.InterfaceAudience.Public;
025import org.apache.hadoop.classification.InterfaceStability.Unstable;
026import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest;
027import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse;
028import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportRequest;
029import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportResponse;
030import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsRequest;
031import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsResponse;
032import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
033import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
034import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsRequest;
035import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsResponse;
036import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportRequest;
037import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportResponse;
038import org.apache.hadoop.yarn.api.protocolrecords.GetContainersRequest;
039import org.apache.hadoop.yarn.api.protocolrecords.GetContainersResponse;
040import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
041import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
042import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest;
043import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse;
044import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
045import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
046import org.apache.hadoop.yarn.api.records.ApplicationId;
047import org.apache.hadoop.yarn.api.records.ApplicationReport;
048import org.apache.hadoop.yarn.api.records.ContainerId;
049import org.apache.hadoop.yarn.api.records.ContainerReport;
050import org.apache.hadoop.yarn.api.records.Token;
051import 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
061public 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}