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    }