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 org.apache.hadoop.classification.InterfaceAudience.Private;
022import org.apache.hadoop.classification.InterfaceAudience.Public;
023import org.apache.hadoop.classification.InterfaceStability.Stable;
024import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest;
025import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse;
026import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest;
027import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsResponse;
028import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
029import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
030import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
031import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
032import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
033import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
034import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
035import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
036import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
037import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
038import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
039import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
040import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
041import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
042import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
043import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
044import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest;
045import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse;
046import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
047import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
048import org.apache.hadoop.yarn.api.records.ApplicationId;
049import org.apache.hadoop.yarn.api.records.ApplicationReport;
050import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
051import org.apache.hadoop.yarn.api.records.DelegationToken;
052import org.apache.hadoop.yarn.api.records.NodeReport;
053import org.apache.hadoop.yarn.api.records.Resource;
054import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
055import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
056
057/**
058 * <p>The protocol between clients and the <code>ResourceManager</code>
059 * to submit/abort jobs and to get information on applications, cluster metrics,
060 * nodes, queues and ACLs.</p> 
061 */
062@Public
063@Stable
064public interface ClientRMProtocol {
065  /**
066   * <p>The interface used by clients to obtain a new {@link ApplicationId} for 
067   * submitting new applications.</p>
068   * 
069   * <p>The <code>ResourceManager</code> responds with a new, monotonically
070   * increasing, {@link ApplicationId} which is used by the client to submit
071   * a new application.</p>
072   *
073   * <p>The <code>ResourceManager</code> also responds with details such 
074   * as minimum and maximum resource capabilities in the cluster as specified in
075   * {@link GetNewApplicationResponse}.</p>
076   *
077   * @param request request to get a new <code>ApplicationId</code>
078   * @return response containing the new <code>ApplicationId</code> to be used
079   * to submit an application
080   * @throws YarnRemoteException
081   * @see #submitApplication(SubmitApplicationRequest)
082   */
083  public GetNewApplicationResponse getNewApplication(
084      GetNewApplicationRequest request)
085  throws YarnRemoteException;
086  
087  /**
088   * <p>The interface used by clients to submit a new application to the
089   * <code>ResourceManager.</code></p>
090   * 
091   * <p>The client is required to provide details such as queue, 
092   * {@link Resource} required to run the <code>ApplicationMaster</code>, 
093   * the equivalent of {@link ContainerLaunchContext} for launching
094   * the <code>ApplicationMaster</code> etc. via the 
095   * {@link SubmitApplicationRequest}.</p>
096   * 
097   * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 
098   * {@link SubmitApplicationResponse} on accepting the submission and throws 
099   * an exception if it rejects the submission.</p>
100   * 
101   * <p> In secure mode,the <code>ResourceManager</code> verifies access to
102   * queues etc. before accepting the application submission.</p>
103   * 
104   * @param request request to submit a new application
105   * @return (empty) response on accepting the submission
106   * @throws YarnRemoteException
107   * @see #getNewApplication(GetNewApplicationRequest)
108   */
109  public SubmitApplicationResponse submitApplication(
110      SubmitApplicationRequest request) 
111  throws YarnRemoteException;
112  
113  /**
114   * <p>The interface used by clients to request the 
115   * <code>ResourceManager</code> to abort submitted application.</p>
116   * 
117   * <p>The client, via {@link KillApplicationRequest} provides the
118   * {@link ApplicationId} of the application to be aborted.</p>
119   * 
120   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
121   * application, queue etc. before terminating the application.</p> 
122   * 
123   * <p>Currently, the <code>ResourceManager</code> returns an empty response
124   * on success and throws an exception on rejecting the request.</p>
125   * 
126   * @param request request to abort a submited application
127   * @return <code>ResourceManager</code> returns an empty response
128   *         on success and throws an exception on rejecting the request
129   * @throws YarnRemoteException
130   * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 
131   */
132  public KillApplicationResponse forceKillApplication(
133      KillApplicationRequest request) 
134  throws YarnRemoteException;
135
136  /**
137   * <p>The interface used by clients to get a report of an Application from
138   * the <code>ResourceManager</code>.</p>
139   * 
140   * <p>The client, via {@link GetApplicationReportRequest} provides the
141   * {@link ApplicationId} of the application.</p>
142   *
143   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
144   * application, queue etc. before accepting the request.</p> 
145   * 
146   * <p>The <code>ResourceManager</code> responds with a 
147   * {@link GetApplicationReportResponse} which includes the 
148   * {@link ApplicationReport} for the application.</p>
149   * 
150   * <p>If the user does not have <code>VIEW_APP</code> access then the
151   * following fields in the report will be set to stubbed values:
152   * <ul>
153   *   <li>host - set to "N/A"</li>
154   *   <li>RPC port - set to -1</li>
155   *   <li>client token - set to "N/A"</li>
156   *   <li>diagnostics - set to "N/A"</li>
157   *   <li>tracking URL - set to "N/A"</li>
158   *   <li>original tracking URL - set to "N/A"</li>
159   *   <li>resource usage report - all values are -1</li>
160   * </ul></p>
161   *
162   * @param request request for an application report
163   * @return application report 
164   * @throws YarnRemoteException
165   */
166  public GetApplicationReportResponse getApplicationReport(
167      GetApplicationReportRequest request) 
168  throws YarnRemoteException;
169  
170  /**
171   * <p>The interface used by clients to get metrics about the cluster from
172   * the <code>ResourceManager</code>.</p>
173   * 
174   * <p>The <code>ResourceManager</code> responds with a
175   * {@link GetClusterMetricsResponse} which includes the 
176   * {@link YarnClusterMetrics} with details such as number of current
177   * nodes in the cluster.</p>
178   * 
179   * @param request request for cluster metrics
180   * @return cluster metrics
181   * @throws YarnRemoteException
182   */
183  public GetClusterMetricsResponse getClusterMetrics(
184      GetClusterMetricsRequest request) 
185  throws YarnRemoteException;
186  
187  /**
188   * <p>The interface used by clients to get a report of all Applications
189   * in the cluster from the <code>ResourceManager</code>.</p>
190   * 
191   * <p>The <code>ResourceManager</code> responds with a 
192   * {@link GetAllApplicationsResponse} which includes the 
193   * {@link ApplicationReport} for all the applications.</p>
194   * 
195   * <p>If the user does not have <code>VIEW_APP</code> access for an
196   * application then the corresponding report will be filtered as
197   * described in {@link #getApplicationReport(GetApplicationReportRequest)}.
198   * </p>
199   *
200   * @param request request for report on all running applications
201   * @return report on all running applications
202   * @throws YarnRemoteException
203   */
204  public GetAllApplicationsResponse getAllApplications(
205      GetAllApplicationsRequest request) 
206  throws YarnRemoteException;
207  
208  /**
209   * <p>The interface used by clients to get a report of all nodes
210   * in the cluster from the <code>ResourceManager</code>.</p>
211   * 
212   * <p>The <code>ResourceManager</code> responds with a 
213   * {@link GetClusterNodesResponse} which includes the 
214   * {@link NodeReport} for all the nodes in the cluster.</p>
215   * 
216   * @param request request for report on all nodes
217   * @return report on all nodes
218   * @throws YarnRemoteException
219   */
220  public GetClusterNodesResponse getClusterNodes(
221      GetClusterNodesRequest request) 
222  throws YarnRemoteException;
223  
224  /**
225   * <p>The interface used by clients to get information about <em>queues</em>
226   * from the <code>ResourceManager</code>.</p>
227   * 
228   * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
229   * as used/total resources, child queues, running applications etc.</p>
230   *
231   * <p> In secure mode,the <code>ResourceManager</code> verifies access before
232   * providing the information.</p> 
233   * 
234   * @param request request to get queue information
235   * @return queue information
236   * @throws YarnRemoteException
237   */
238  public GetQueueInfoResponse getQueueInfo(
239      GetQueueInfoRequest request) 
240  throws YarnRemoteException;
241  
242  /**
243   * <p>The interface used by clients to get information about <em>queue 
244   * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
245   * </p>
246   * 
247   * <p>The <code>ResourceManager</code> responds with queue acls for all
248   * existing queues.</p>
249   * 
250   * @param request request to get queue acls for <em>current user</em>
251   * @return queue acls for <em>current user</em>
252   * @throws YarnRemoteException
253   */
254  public GetQueueUserAclsInfoResponse getQueueUserAcls(
255      GetQueueUserAclsInfoRequest request) 
256  throws YarnRemoteException;
257  
258  /**
259   * <p>The interface used by clients to get delegation token, enabling the 
260   * containers to be able to talk to the service using those tokens.
261   * 
262   *  <p> The <code>ResourceManager</code> responds with the delegation token
263   *  {@link DelegationToken} that can be used by the client to speak to this
264   *  service.
265   * @param request request to get a delegation token for the client.
266   * @return delegation token that can be used to talk to this service
267   * @throws YarnRemoteException
268   */
269  public GetDelegationTokenResponse getDelegationToken(
270      GetDelegationTokenRequest request) 
271  throws YarnRemoteException;
272  
273  /**
274   * Renew an existing delegation token.
275   * 
276   * @param request the delegation token to be renewed.
277   * @return the new expiry time for the delegation token.
278   * @throws YarnRemoteException
279   */
280  @Private
281  public RenewDelegationTokenResponse renewDelegationToken(
282      RenewDelegationTokenRequest request) throws YarnRemoteException;
283
284  /**
285   * Cancel an existing delegation token.
286   * 
287   * @param request the delegation token to be renewed.
288   * @return
289   * @throws YarnRemoteException
290   */
291  @Private
292  public CancelDelegationTokenResponse cancelDelegationToken(
293      CancelDelegationTokenRequest request) throws YarnRemoteException;
294}