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 java.io.IOException;
022
023import org.apache.hadoop.classification.InterfaceAudience.Public;
024import org.apache.hadoop.classification.InterfaceStability.Stable;
025import org.apache.hadoop.classification.InterfaceStability.Unstable;
026import org.apache.hadoop.io.retry.Idempotent;
027import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
028import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
029import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
030import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsRequest;
031import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsResponse;
032import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
033import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
034import org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesRequest;
035import org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesResponse;
036import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
037import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
038import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest;
039import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse;
040import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
041import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
042import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
043import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
044import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
045import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
046import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesRequest;
047import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesResponse;
048import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteRequest;
049import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteResponse;
050import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionRequest;
051import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionResponse;
052import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateRequest;
053import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateResponse;
054import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
055import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
056import org.apache.hadoop.yarn.api.records.ApplicationId;
057import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
058import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
059import org.apache.hadoop.yarn.api.records.NodeReport;
060import org.apache.hadoop.yarn.api.records.ReservationId;
061import org.apache.hadoop.yarn.api.records.Resource;
062import org.apache.hadoop.yarn.api.records.ResourceRequest;
063import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
064import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
065import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException;
066import org.apache.hadoop.yarn.exceptions.YarnException;
067
068/**
069 * <p>The protocol between clients and the <code>ResourceManager</code>
070 * to submit/abort jobs and to get information on applications, cluster metrics,
071 * nodes, queues and ACLs.</p> 
072 */
073@Public
074@Stable
075public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
076  /**
077   * <p>The interface used by clients to obtain a new {@link ApplicationId} for 
078   * submitting new applications.</p>
079   * 
080   * <p>The <code>ResourceManager</code> responds with a new, monotonically
081   * increasing, {@link ApplicationId} which is used by the client to submit
082   * a new application.</p>
083   *
084   * <p>The <code>ResourceManager</code> also responds with details such 
085   * as maximum resource capabilities in the cluster as specified in
086   * {@link GetNewApplicationResponse}.</p>
087   *
088   * @param request request to get a new <code>ApplicationId</code>
089   * @return response containing the new <code>ApplicationId</code> to be used
090   * to submit an application
091   * @throws YarnException
092   * @throws IOException
093   * @see #submitApplication(SubmitApplicationRequest)
094   */
095  @Public
096  @Stable
097  @Idempotent
098  public GetNewApplicationResponse getNewApplication(
099      GetNewApplicationRequest request)
100  throws YarnException, IOException;
101  
102  /**
103   * <p>The interface used by clients to submit a new application to the
104   * <code>ResourceManager.</code></p>
105   * 
106   * <p>The client is required to provide details such as queue, 
107   * {@link Resource} required to run the <code>ApplicationMaster</code>, 
108   * the equivalent of {@link ContainerLaunchContext} for launching
109   * the <code>ApplicationMaster</code> etc. via the 
110   * {@link SubmitApplicationRequest}.</p>
111   * 
112   * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 
113   * {@link SubmitApplicationResponse} on accepting the submission and throws 
114   * an exception if it rejects the submission. However, this call needs to be
115   * followed by {@link #getApplicationReport(GetApplicationReportRequest)}
116   * to make sure that the application gets properly submitted - obtaining a
117   * {@link SubmitApplicationResponse} from ResourceManager doesn't guarantee
118   * that RM 'remembers' this application beyond failover or restart. If RM
119   * failover or RM restart happens before ResourceManager saves the
120   * application's state successfully, the subsequent
121   * {@link #getApplicationReport(GetApplicationReportRequest)} will throw
122   * a {@link ApplicationNotFoundException}. The Clients need to re-submit
123   * the application with the same {@link ApplicationSubmissionContext} when
124   * it encounters the {@link ApplicationNotFoundException} on the
125   * {@link #getApplicationReport(GetApplicationReportRequest)} call.</p>
126   * 
127   * <p>During the submission process, it checks whether the application
128   * already exists. If the application exists, it will simply return
129   * SubmitApplicationResponse</p>
130   *
131   * <p> In secure mode,the <code>ResourceManager</code> verifies access to
132   * queues etc. before accepting the application submission.</p>
133   * 
134   * @param request request to submit a new application
135   * @return (empty) response on accepting the submission
136   * @throws YarnException
137   * @throws IOException
138   * @see #getNewApplication(GetNewApplicationRequest)
139   */
140  @Public
141  @Stable
142  @Idempotent
143  public SubmitApplicationResponse submitApplication(
144      SubmitApplicationRequest request) 
145  throws YarnException, IOException;
146  
147  /**
148   * <p>The interface used by clients to request the 
149   * <code>ResourceManager</code> to abort submitted application.</p>
150   * 
151   * <p>The client, via {@link KillApplicationRequest} provides the
152   * {@link ApplicationId} of the application to be aborted.</p>
153   * 
154   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
155   * application, queue etc. before terminating the application.</p> 
156   * 
157   * <p>Currently, the <code>ResourceManager</code> returns an empty response
158   * on success and throws an exception on rejecting the request.</p>
159   * 
160   * @param request request to abort a submitted application
161   * @return <code>ResourceManager</code> returns an empty response
162   *         on success and throws an exception on rejecting the request
163   * @throws YarnException
164   * @throws IOException
165   * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 
166   */
167  @Public
168  @Stable
169  @Idempotent
170  public KillApplicationResponse forceKillApplication(
171      KillApplicationRequest request) 
172  throws YarnException, IOException;
173
174  /**
175   * <p>The interface used by clients to get metrics about the cluster from
176   * the <code>ResourceManager</code>.</p>
177   * 
178   * <p>The <code>ResourceManager</code> responds with a
179   * {@link GetClusterMetricsResponse} which includes the 
180   * {@link YarnClusterMetrics} with details such as number of current
181   * nodes in the cluster.</p>
182   * 
183   * @param request request for cluster metrics
184   * @return cluster metrics
185   * @throws YarnException
186   * @throws IOException
187   */
188  @Public
189  @Stable
190  @Idempotent
191  public GetClusterMetricsResponse getClusterMetrics(
192      GetClusterMetricsRequest request) 
193  throws YarnException, IOException;
194
195  /**
196   * <p>The interface used by clients to get a report of all nodes
197   * in the cluster from the <code>ResourceManager</code>.</p>
198   * 
199   * <p>The <code>ResourceManager</code> responds with a 
200   * {@link GetClusterNodesResponse} which includes the 
201   * {@link NodeReport} for all the nodes in the cluster.</p>
202   * 
203   * @param request request for report on all nodes
204   * @return report on all nodes
205   * @throws YarnException
206   * @throws IOException
207   */
208  @Public
209  @Stable
210  @Idempotent
211  public GetClusterNodesResponse getClusterNodes(
212      GetClusterNodesRequest request) 
213  throws YarnException, IOException;
214  
215  /**
216   * <p>The interface used by clients to get information about <em>queues</em>
217   * from the <code>ResourceManager</code>.</p>
218   * 
219   * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
220   * as used/total resources, child queues, running applications etc.</p>
221   *
222   * <p> In secure mode,the <code>ResourceManager</code> verifies access before
223   * providing the information.</p> 
224   * 
225   * @param request request to get queue information
226   * @return queue information
227   * @throws YarnException
228   * @throws IOException
229   */
230  @Public
231  @Stable
232  @Idempotent
233  public GetQueueInfoResponse getQueueInfo(
234      GetQueueInfoRequest request) 
235  throws YarnException, IOException;
236  
237  /**
238   * <p>The interface used by clients to get information about <em>queue 
239   * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
240   * </p>
241   * 
242   * <p>The <code>ResourceManager</code> responds with queue acls for all
243   * existing queues.</p>
244   * 
245   * @param request request to get queue acls for <em>current user</em>
246   * @return queue acls for <em>current user</em>
247   * @throws YarnException
248   * @throws IOException
249   */
250  @Public
251  @Stable
252 @Idempotent
253  public GetQueueUserAclsInfoResponse getQueueUserAcls(
254      GetQueueUserAclsInfoRequest request) 
255  throws YarnException, IOException;
256
257  /**
258   * Move an application to a new queue.
259   * 
260   * @param request the application ID and the target queue
261   * @return an empty response
262   * @throws YarnException
263   * @throws IOException
264   */
265  @Public
266  @Unstable
267  @Idempotent
268  public MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues(
269      MoveApplicationAcrossQueuesRequest request) throws YarnException, IOException;
270
271  /**
272   * <p>
273   * The interface used by clients to submit a new reservation to the
274   * {@code ResourceManager}.
275   * </p>
276   * 
277   * <p>
278   * The client packages all details of its request in a
279   * {@link ReservationSubmissionRequest} object. This contains information
280   * about the amount of capacity, temporal constraints, and concurrency needs.
281   * Furthermore, the reservation might be composed of multiple stages, with
282   * ordering dependencies among them.
283   * </p>
284   * 
285   * <p>
286   * In order to respond, a new admission control component in the
287   * {@code ResourceManager} performs an analysis of the resources that have
288   * been committed over the period of time the user is requesting, verify that
289   * the user requests can be fulfilled, and that it respect a sharing policy
290   * (e.g., {@code CapacityOverTimePolicy}). Once it has positively determined
291   * that the ReservationSubmissionRequest is satisfiable the
292   * {@code ResourceManager} answers with a
293   * {@link ReservationSubmissionResponse} that include a non-null
294   * {@link ReservationId}. Upon failure to find a valid allocation the response
295   * is an exception with the reason.
296   * 
297   * On application submission the client can use this {@link ReservationId} to
298   * obtain access to the reserved resources.
299   * </p>
300   * 
301   * <p>
302   * The system guarantees that during the time-range specified by the user, the
303   * reservationID will be corresponding to a valid reservation. The amount of
304   * capacity dedicated to such queue can vary overtime, depending of the
305   * allocation that has been determined. But it is guaranteed to satisfy all
306   * the constraint expressed by the user in the
307   * {@link ReservationSubmissionRequest}.
308   * </p>
309   * 
310   * @param request the request to submit a new Reservation
311   * @return response the {@link ReservationId} on accepting the submission
312   * @throws YarnException if the request is invalid or reservation cannot be
313   *           created successfully
314   * @throws IOException
315   * 
316   */
317  @Public
318  @Unstable
319  public ReservationSubmissionResponse submitReservation(
320      ReservationSubmissionRequest request) throws YarnException, IOException;
321
322  /**
323   * <p>
324   * The interface used by clients to update an existing Reservation. This is
325   * referred to as a re-negotiation process, in which a user that has
326   * previously submitted a Reservation.
327   * </p>
328   * 
329   * <p>
330   * The allocation is attempted by virtually substituting all previous
331   * allocations related to this Reservation with new ones, that satisfy the new
332   * {@link ReservationUpdateRequest}. Upon success the previous allocation is
333   * substituted by the new one, and on failure (i.e., if the system cannot find
334   * a valid allocation for the updated request), the previous allocation
335   * remains valid.
336   * 
337   * The {@link ReservationId} is not changed, and applications currently
338   * running within this reservation will automatically receive the resources
339   * based on the new allocation.
340   * </p>
341   * 
342   * @param request to update an existing Reservation (the ReservationRequest
343   *          should refer to an existing valid {@link ReservationId})
344   * @return response empty on successfully updating the existing reservation
345   * @throws YarnException if the request is invalid or reservation cannot be
346   *           updated successfully
347   * @throws IOException
348   * 
349   */
350  @Public
351  @Unstable
352  public ReservationUpdateResponse updateReservation(
353      ReservationUpdateRequest request) throws YarnException, IOException;
354
355  /**
356   * <p>
357   * The interface used by clients to remove an existing Reservation.
358   * 
359   * Upon deletion of a reservation applications running with this reservation,
360   * are automatically downgraded to normal jobs running without any dedicated
361   * reservation.
362   * </p>
363   * 
364   * @param request to remove an existing Reservation (the ReservationRequest
365   *          should refer to an existing valid {@link ReservationId})
366   * @return response empty on successfully deleting the existing reservation
367   * @throws YarnException if the request is invalid or reservation cannot be
368   *           deleted successfully
369   * @throws IOException
370   * 
371   */
372  @Public
373  @Unstable
374  public ReservationDeleteResponse deleteReservation(
375      ReservationDeleteRequest request) throws YarnException, IOException;
376
377  /**
378   * <p>
379   * The interface used by client to get node to labels mappings in existing cluster
380   * </p>
381   *
382   * @param request
383   * @return node to labels mappings
384   * @throws YarnException
385   * @throws IOException
386   */
387  @Public
388  @Unstable
389  public GetNodesToLabelsResponse getNodeToLabels(
390      GetNodesToLabelsRequest request) throws YarnException, IOException;
391
392  /**
393   * <p>
394   * The interface used by client to get labels to nodes mappings
395   * in existing cluster
396   * </p>
397   *
398   * @param request
399   * @return labels to nodes mappings
400   * @throws YarnException
401   * @throws IOException
402   */
403  @Public
404  @Unstable
405  public GetLabelsToNodesResponse getLabelsToNodes(
406      GetLabelsToNodesRequest request) throws YarnException, IOException;
407
408  /**
409   * <p>
410   * The interface used by client to get node labels in the cluster
411   * </p>
412   *
413   * @param request to get node labels collection of this cluster
414   * @return node labels collection of this cluster
415   * @throws YarnException
416   * @throws IOException
417   */
418  @Public
419  @Unstable
420  public GetClusterNodeLabelsResponse getClusterNodeLabels(
421      GetClusterNodeLabelsRequest request) throws YarnException, IOException;
422}