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.Private;
022    import org.apache.hadoop.classification.InterfaceAudience.Public;
023    import org.apache.hadoop.classification.InterfaceStability.Stable;
024    import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest;
025    import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse;
026    import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest;
027    import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsResponse;
028    import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
029    import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
030    import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
031    import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
032    import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
033    import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
034    import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
035    import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
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.KillApplicationRequest;
043    import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
044    import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest;
045    import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse;
046    import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
047    import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
048    import org.apache.hadoop.yarn.api.records.ApplicationId;
049    import org.apache.hadoop.yarn.api.records.ApplicationReport;
050    import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
051    import org.apache.hadoop.yarn.api.records.DelegationToken;
052    import org.apache.hadoop.yarn.api.records.NodeReport;
053    import org.apache.hadoop.yarn.api.records.Resource;
054    import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
055    import 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
064    public 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    }