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    }