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