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       * @param request request for an application report
147       * @return application report 
148       * @throws YarnRemoteException
149       */
150      public GetApplicationReportResponse getApplicationReport(
151          GetApplicationReportRequest request) 
152      throws YarnRemoteException;
153      
154      /**
155       * <p>The interface used by clients to get metrics about the cluster from
156       * the <code>ResourceManager</code>.</p>
157       * 
158       * <p>The <code>ResourceManager</code> responds with a
159       * {@link GetClusterMetricsResponse} which includes the 
160       * {@link YarnClusterMetrics} with details such as number of current
161       * nodes in the cluster.</p>
162       * 
163       * @param request request for cluster metrics
164       * @return cluster metrics
165       * @throws YarnRemoteException
166       */
167      public GetClusterMetricsResponse getClusterMetrics(
168          GetClusterMetricsRequest request) 
169      throws YarnRemoteException;
170      
171      /**
172       * <p>The interface used by clients to get a report of all Applications
173       * in the cluster from the <code>ResourceManager</code>.</p>
174       * 
175       * <p>The <code>ResourceManager</code> responds with a 
176       * {@link GetAllApplicationsResponse} which includes the 
177       * {@link ApplicationReport} for all the applications.</p>
178       * 
179       * @param request request for report on all running applications
180       * @return report on all running applications
181       * @throws YarnRemoteException
182       */
183      public GetAllApplicationsResponse getAllApplications(
184          GetAllApplicationsRequest request) 
185      throws YarnRemoteException;
186      
187      /**
188       * <p>The interface used by clients to get a report of all nodes
189       * in the cluster from the <code>ResourceManager</code>.</p>
190       * 
191       * <p>The <code>ResourceManager</code> responds with a 
192       * {@link GetClusterNodesResponse} which includes the 
193       * {@link NodeReport} for all the nodes in the cluster.</p>
194       * 
195       * @param request request for report on all nodes
196       * @return report on all nodes
197       * @throws YarnRemoteException
198       */
199      public GetClusterNodesResponse getClusterNodes(
200          GetClusterNodesRequest request) 
201      throws YarnRemoteException;
202      
203      /**
204       * <p>The interface used by clients to get information about <em>queues</em>
205       * from the <code>ResourceManager</code>.</p>
206       * 
207       * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
208       * as used/total resources, child queues, running applications etc.</p>
209       *
210       * <p> In secure mode,the <code>ResourceManager</code> verifies access before
211       * providing the information.</p> 
212       * 
213       * @param request request to get queue information
214       * @return queue information
215       * @throws YarnRemoteException
216       */
217      public GetQueueInfoResponse getQueueInfo(
218          GetQueueInfoRequest request) 
219      throws YarnRemoteException;
220      
221      /**
222       * <p>The interface used by clients to get information about <em>queue 
223       * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
224       * </p>
225       * 
226       * <p>The <code>ResourceManager</code> responds with queue acls for all
227       * existing queues.</p>
228       * 
229       * @param request request to get queue acls for <em>current user</em>
230       * @return queue acls for <em>current user</em>
231       * @throws YarnRemoteException
232       */
233      public GetQueueUserAclsInfoResponse getQueueUserAcls(
234          GetQueueUserAclsInfoRequest request) 
235      throws YarnRemoteException;
236      
237      /**
238       * <p>The interface used by clients to get delegation token, enabling the 
239       * containers to be able to talk to the service using those tokens.
240       * 
241       *  <p> The <code>ResourceManager</code> responds with the delegation token
242       *  {@link DelegationToken} that can be used by the client to speak to this
243       *  service.
244       * @param request request to get a delegation token for the client.
245       * @return delegation token that can be used to talk to this service
246       * @throws YarnRemoteException
247       */
248      public GetDelegationTokenResponse getDelegationToken(
249          GetDelegationTokenRequest request) 
250      throws YarnRemoteException;
251    }