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.Private;
024import org.apache.hadoop.classification.InterfaceAudience.Public;
025import org.apache.hadoop.classification.InterfaceStability.Stable;
026import org.apache.hadoop.classification.InterfaceStability.Unstable;
027import org.apache.hadoop.io.retry.Idempotent;
028import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest;
029import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse;
030import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportRequest;
031import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportResponse;
032import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsRequest;
033import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsResponse;
034import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
035import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
036import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsRequest;
037import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsResponse;
038import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
039import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
040import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsRequest;
041import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsResponse;
042import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
043import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
044import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportRequest;
045import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportResponse;
046import org.apache.hadoop.yarn.api.protocolrecords.GetContainersRequest;
047import org.apache.hadoop.yarn.api.protocolrecords.GetContainersResponse;
048import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
049import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
050import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
051import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
052import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest;
053import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse;
054import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
055import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
056import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
057import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
058import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
059import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
060import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesRequest;
061import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesResponse;
062import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest;
063import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse;
064import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteRequest;
065import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteResponse;
066import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionRequest;
067import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionResponse;
068import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateRequest;
069import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateResponse;
070import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
071import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
072import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
073import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
074import org.apache.hadoop.yarn.api.records.ApplicationId;
075import org.apache.hadoop.yarn.api.records.ApplicationReport;
076import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
077import org.apache.hadoop.yarn.api.records.ContainerId;
078import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
079import org.apache.hadoop.yarn.api.records.ContainerReport;
080import org.apache.hadoop.yarn.api.records.NodeReport;
081import org.apache.hadoop.yarn.api.records.ReservationId;
082import org.apache.hadoop.yarn.api.records.Resource;
083import org.apache.hadoop.yarn.api.records.ResourceRequest;
084import org.apache.hadoop.yarn.api.records.Token;
085import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
086import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
087import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException;
088import org.apache.hadoop.yarn.exceptions.YarnException;
089
090/**
091 * <p>The protocol between clients and the <code>ResourceManager</code>
092 * to submit/abort jobs and to get information on applications, cluster metrics,
093 * nodes, queues and ACLs.</p> 
094 */
095@Public
096@Stable
097public interface ApplicationClientProtocol {
098  /**
099   * <p>The interface used by clients to obtain a new {@link ApplicationId} for 
100   * submitting new applications.</p>
101   * 
102   * <p>The <code>ResourceManager</code> responds with a new, monotonically
103   * increasing, {@link ApplicationId} which is used by the client to submit
104   * a new application.</p>
105   *
106   * <p>The <code>ResourceManager</code> also responds with details such 
107   * as maximum resource capabilities in the cluster as specified in
108   * {@link GetNewApplicationResponse}.</p>
109   *
110   * @param request request to get a new <code>ApplicationId</code>
111   * @return response containing the new <code>ApplicationId</code> to be used
112   * to submit an application
113   * @throws YarnException
114   * @throws IOException
115   * @see #submitApplication(SubmitApplicationRequest)
116   */
117  @Public
118  @Stable
119  @Idempotent
120  public GetNewApplicationResponse getNewApplication(
121      GetNewApplicationRequest request)
122  throws YarnException, IOException;
123  
124  /**
125   * <p>The interface used by clients to submit a new application to the
126   * <code>ResourceManager.</code></p>
127   * 
128   * <p>The client is required to provide details such as queue, 
129   * {@link Resource} required to run the <code>ApplicationMaster</code>, 
130   * the equivalent of {@link ContainerLaunchContext} for launching
131   * the <code>ApplicationMaster</code> etc. via the 
132   * {@link SubmitApplicationRequest}.</p>
133   * 
134   * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 
135   * {@link SubmitApplicationResponse} on accepting the submission and throws 
136   * an exception if it rejects the submission. However, this call needs to be
137   * followed by {@link #getApplicationReport(GetApplicationReportRequest)}
138   * to make sure that the application gets properly submitted - obtaining a
139   * {@link SubmitApplicationResponse} from ResourceManager doesn't guarantee
140   * that RM 'remembers' this application beyond failover or restart. If RM
141   * failover or RM restart happens before ResourceManager saves the
142   * application's state successfully, the subsequent
143   * {@link #getApplicationReport(GetApplicationReportRequest)} will throw
144   * a {@link ApplicationNotFoundException}. The Clients need to re-submit
145   * the application with the same {@link ApplicationSubmissionContext} when
146   * it encounters the {@link ApplicationNotFoundException} on the
147   * {@link #getApplicationReport(GetApplicationReportRequest)} call.</p>
148   * 
149   * <p>During the submission process, it checks whether the application
150   * already exists. If the application exists, it will simply return
151   * SubmitApplicationResponse</p>
152   *
153   * <p> In secure mode,the <code>ResourceManager</code> verifies access to
154   * queues etc. before accepting the application submission.</p>
155   * 
156   * @param request request to submit a new application
157   * @return (empty) response on accepting the submission
158   * @throws YarnException
159   * @throws IOException
160   * @throws InvalidResourceRequestException
161   *           The exception is thrown when a {@link ResourceRequest} is out of
162   *           the range of the configured lower and upper resource boundaries.
163   * @see #getNewApplication(GetNewApplicationRequest)
164   */
165  @Public
166  @Stable
167  @Idempotent
168  public SubmitApplicationResponse submitApplication(
169      SubmitApplicationRequest request) 
170  throws YarnException, IOException;
171  
172  /**
173   * <p>The interface used by clients to request the 
174   * <code>ResourceManager</code> to abort submitted application.</p>
175   * 
176   * <p>The client, via {@link KillApplicationRequest} provides the
177   * {@link ApplicationId} of the application to be aborted.</p>
178   * 
179   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
180   * application, queue etc. before terminating the application.</p> 
181   * 
182   * <p>Currently, the <code>ResourceManager</code> returns an empty response
183   * on success and throws an exception on rejecting the request.</p>
184   * 
185   * @param request request to abort a submitted application
186   * @return <code>ResourceManager</code> returns an empty response
187   *         on success and throws an exception on rejecting the request
188   * @throws YarnException
189   * @throws IOException
190   * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 
191   */
192  @Public
193  @Stable
194  @Idempotent
195  public KillApplicationResponse forceKillApplication(
196      KillApplicationRequest request) 
197  throws YarnException, IOException;
198
199  /**
200   * <p>The interface used by clients to get a report of an Application from
201   * the <code>ResourceManager</code>.</p>
202   * 
203   * <p>The client, via {@link GetApplicationReportRequest} provides the
204   * {@link ApplicationId} of the application.</p>
205   *
206   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
207   * application, queue etc. before accepting the request.</p> 
208   * 
209   * <p>The <code>ResourceManager</code> responds with a 
210   * {@link GetApplicationReportResponse} which includes the 
211   * {@link ApplicationReport} for the application.</p>
212   * 
213   * <p>If the user does not have <code>VIEW_APP</code> access then the
214   * following fields in the report will be set to stubbed values:
215   * <ul>
216   *   <li>host - set to "N/A"</li>
217   *   <li>RPC port - set to -1</li>
218   *   <li>client token - set to "N/A"</li>
219   *   <li>diagnostics - set to "N/A"</li>
220   *   <li>tracking URL - set to "N/A"</li>
221   *   <li>original tracking URL - set to "N/A"</li>
222   *   <li>resource usage report - all values are -1</li>
223   * </ul></p>
224   *
225   * @param request request for an application report
226   * @return application report 
227   * @throws YarnException
228   * @throws IOException
229   */
230  @Public
231  @Stable
232  @Idempotent
233  public GetApplicationReportResponse getApplicationReport(
234      GetApplicationReportRequest request) 
235  throws YarnException, IOException;
236  
237  /**
238   * <p>The interface used by clients to get metrics about the cluster from
239   * the <code>ResourceManager</code>.</p>
240   * 
241   * <p>The <code>ResourceManager</code> responds with a
242   * {@link GetClusterMetricsResponse} which includes the 
243   * {@link YarnClusterMetrics} with details such as number of current
244   * nodes in the cluster.</p>
245   * 
246   * @param request request for cluster metrics
247   * @return cluster metrics
248   * @throws YarnException
249   * @throws IOException
250   */
251  @Public
252  @Stable
253  @Idempotent
254  public GetClusterMetricsResponse getClusterMetrics(
255      GetClusterMetricsRequest request) 
256  throws YarnException, IOException;
257  
258  /**
259   * <p>The interface used by clients to get a report of Applications
260   * matching the filters defined by {@link GetApplicationsRequest}
261   * in the cluster from the <code>ResourceManager</code>.</p>
262   * 
263   * <p>The <code>ResourceManager</code> responds with a 
264   * {@link GetApplicationsResponse} which includes the
265   * {@link ApplicationReport} for the applications.</p>
266   * 
267   * <p>If the user does not have <code>VIEW_APP</code> access for an
268   * application then the corresponding report will be filtered as
269   * described in {@link #getApplicationReport(GetApplicationReportRequest)}.
270   * </p>
271   *
272   * @param request request for report on applications
273   * @return report on applications matching the given application types
274   *           defined in the request
275   * @throws YarnException
276   * @throws IOException
277   * @see GetApplicationsRequest
278   */
279  @Public
280  @Stable
281  @Idempotent
282  public GetApplicationsResponse getApplications(
283      GetApplicationsRequest request)
284  throws YarnException, IOException;
285  
286  /**
287   * <p>The interface used by clients to get a report of all nodes
288   * in the cluster from the <code>ResourceManager</code>.</p>
289   * 
290   * <p>The <code>ResourceManager</code> responds with a 
291   * {@link GetClusterNodesResponse} which includes the 
292   * {@link NodeReport} for all the nodes in the cluster.</p>
293   * 
294   * @param request request for report on all nodes
295   * @return report on all nodes
296   * @throws YarnException
297   * @throws IOException
298   */
299  @Public
300  @Stable
301  @Idempotent
302  public GetClusterNodesResponse getClusterNodes(
303      GetClusterNodesRequest request) 
304  throws YarnException, IOException;
305  
306  /**
307   * <p>The interface used by clients to get information about <em>queues</em>
308   * from the <code>ResourceManager</code>.</p>
309   * 
310   * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
311   * as used/total resources, child queues, running applications etc.</p>
312   *
313   * <p> In secure mode,the <code>ResourceManager</code> verifies access before
314   * providing the information.</p> 
315   * 
316   * @param request request to get queue information
317   * @return queue information
318   * @throws YarnException
319   * @throws IOException
320   */
321  @Public
322  @Stable
323  @Idempotent
324  public GetQueueInfoResponse getQueueInfo(
325      GetQueueInfoRequest request) 
326  throws YarnException, IOException;
327  
328  /**
329   * <p>The interface used by clients to get information about <em>queue 
330   * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
331   * </p>
332   * 
333   * <p>The <code>ResourceManager</code> responds with queue acls for all
334   * existing queues.</p>
335   * 
336   * @param request request to get queue acls for <em>current user</em>
337   * @return queue acls for <em>current user</em>
338   * @throws YarnException
339   * @throws IOException
340   */
341  @Public
342  @Stable
343 @Idempotent
344  public GetQueueUserAclsInfoResponse getQueueUserAcls(
345      GetQueueUserAclsInfoRequest request) 
346  throws YarnException, IOException;
347  
348  /**
349   * <p>The interface used by clients to get delegation token, enabling the 
350   * containers to be able to talk to the service using those tokens.
351   * 
352   *  <p> The <code>ResourceManager</code> responds with the delegation
353   *  {@link Token} that can be used by the client to speak to this
354   *  service.
355   * @param request request to get a delegation token for the client.
356   * @return delegation token that can be used to talk to this service
357   * @throws YarnException
358   * @throws IOException
359   */
360  @Public
361  @Stable
362  @Idempotent
363  public GetDelegationTokenResponse getDelegationToken(
364      GetDelegationTokenRequest request) 
365  throws YarnException, IOException;
366  
367  /**
368   * Renew an existing delegation {@link Token}.
369   * 
370   * @param request the delegation token to be renewed.
371   * @return the new expiry time for the delegation token.
372   * @throws YarnException
373   * @throws IOException
374   */
375  @Private
376  @Unstable
377  @Idempotent
378  public RenewDelegationTokenResponse renewDelegationToken(
379      RenewDelegationTokenRequest request) throws YarnException,
380      IOException;
381
382  /**
383   * Cancel an existing delegation {@link Token}.
384   * 
385   * @param request the delegation token to be cancelled.
386   * @return an empty response.
387   * @throws YarnException
388   * @throws IOException
389   */
390  @Private
391  @Unstable
392  @Idempotent
393  public CancelDelegationTokenResponse cancelDelegationToken(
394      CancelDelegationTokenRequest request) throws YarnException,
395      IOException;
396  
397  /**
398   * Move an application to a new queue.
399   * 
400   * @param request the application ID and the target queue
401   * @return an empty response
402   * @throws YarnException
403   * @throws IOException
404   */
405  @Public
406  @Unstable
407  @Idempotent
408  public MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues(
409      MoveApplicationAcrossQueuesRequest request) throws YarnException, IOException;
410
411  /**
412   * <p>
413   * The interface used by clients to get a report of an Application Attempt
414   * from the <code>ResourceManager</code> 
415   * </p>
416   * 
417   * <p>
418   * The client, via {@link GetApplicationAttemptReportRequest} provides the
419   * {@link ApplicationAttemptId} of the application attempt.
420   * </p>
421   * 
422   * <p>
423   * In secure mode,the <code>ResourceManager</code> verifies access to
424   * the method before accepting the request.
425   * </p>
426   * 
427   * <p>
428   * The <code>ResourceManager</code> responds with a
429   * {@link GetApplicationAttemptReportResponse} which includes the
430   * {@link ApplicationAttemptReport} for the application attempt.
431   * </p>
432   * 
433   * <p>
434   * If the user does not have <code>VIEW_APP</code> access then the following
435   * fields in the report will be set to stubbed values:
436   * <ul>
437   * <li>host</li>
438   * <li>RPC port</li>
439   * <li>client token</li>
440   * <li>diagnostics - set to "N/A"</li>
441   * <li>tracking URL</li>
442   * </ul>
443   * </p>
444   * 
445   * @param request
446   *          request for an application attempt report
447   * @return application attempt report
448   * @throws YarnException
449   * @throws IOException
450   */
451  @Public
452  @Unstable
453  @Idempotent
454  public GetApplicationAttemptReportResponse getApplicationAttemptReport(
455      GetApplicationAttemptReportRequest request) throws YarnException,
456      IOException;
457
458  /**
459   * <p>
460   * The interface used by clients to get a report of all Application attempts
461   * in the cluster from the <code>ResourceManager</code>
462   * </p>
463   * 
464   * <p>
465   * The <code>ResourceManager</code> responds with a
466   * {@link GetApplicationAttemptsRequest} which includes the
467   * {@link ApplicationAttemptReport} for all the applications attempts of a
468   * specified application attempt.
469   * </p>
470   * 
471   * <p>
472   * If the user does not have <code>VIEW_APP</code> access for an application
473   * then the corresponding report will be filtered as described in
474   * {@link #getApplicationAttemptReport(GetApplicationAttemptReportRequest)}.
475   * </p>
476   * 
477   * @param request
478   *          request for reports on all application attempts of an application
479   * @return reports on all application attempts of an application
480   * @throws YarnException
481   * @throws IOException
482   */
483  @Public
484  @Unstable
485  @Idempotent
486  public GetApplicationAttemptsResponse getApplicationAttempts(
487      GetApplicationAttemptsRequest request) throws YarnException, IOException;
488
489  /**
490   * <p>
491   * The interface used by clients to get a report of an Container from the
492   * <code>ResourceManager</code>
493   * </p>
494   * 
495   * <p>
496   * The client, via {@link GetContainerReportRequest} provides the
497   * {@link ContainerId} of the container.
498   * </p>
499   * 
500   * <p>
501   * In secure mode,the <code>ResourceManager</code> verifies access to the
502   * method before accepting the request.
503   * </p>
504   * 
505   * <p>
506   * The <code>ResourceManager</code> responds with a
507   * {@link GetContainerReportResponse} which includes the
508   * {@link ContainerReport} for the container.
509   * </p>
510   * 
511   * @param request
512   *          request for a container report
513   * @return container report
514   * @throws YarnException
515   * @throws IOException
516   */
517  @Public
518  @Unstable
519  @Idempotent
520  public GetContainerReportResponse getContainerReport(
521      GetContainerReportRequest request) throws YarnException, IOException;
522
523  /**
524   * <p>
525   * The interface used by clients to get a report of Containers for an
526   * application attempt from the <code>ResourceManager</code>
527   * </p>
528   * 
529   * <p>
530   * The client, via {@link GetContainersRequest} provides the
531   * {@link ApplicationAttemptId} of the application attempt.
532   * </p>
533   * 
534   * <p>
535   * In secure mode,the <code>ResourceManager</code> verifies access to the
536   * method before accepting the request.
537   * </p>
538   * 
539   * <p>
540   * The <code>ResourceManager</code> responds with a
541   * {@link GetContainersResponse} which includes a list of
542   * {@link ContainerReport} for all the containers of a specific application
543   * attempt.
544   * </p>
545   * 
546   * @param request
547   *          request for a list of container reports of an application attempt.
548   * @return reports on all containers of an application attempt
549   * @throws YarnException
550   * @throws IOException
551   */
552  @Public
553  @Unstable
554  @Idempotent
555  public GetContainersResponse getContainers(GetContainersRequest request)
556      throws YarnException, IOException;
557
558  /**
559   * <p>
560   * The interface used by clients to submit a new reservation to the
561   * {@code ResourceManager}.
562   * </p>
563   * 
564   * <p>
565   * The client packages all details of its request in a
566   * {@link ReservationSubmissionRequest} object. This contains information
567   * about the amount of capacity, temporal constraints, and concurrency needs.
568   * Furthermore, the reservation might be composed of multiple stages, with
569   * ordering dependencies among them.
570   * </p>
571   * 
572   * <p>
573   * In order to respond, a new admission control component in the
574   * {@code ResourceManager} performs an analysis of the resources that have
575   * been committed over the period of time the user is requesting, verify that
576   * the user requests can be fulfilled, and that it respect a sharing policy
577   * (e.g., {@code CapacityOverTimePolicy}). Once it has positively determined
578   * that the ReservationSubmissionRequest is satisfiable the
579   * {@code ResourceManager} answers with a
580   * {@link ReservationSubmissionResponse} that include a non-null
581   * {@link ReservationId}. Upon failure to find a valid allocation the response
582   * is an exception with the reason.
583   * 
584   * On application submission the client can use this {@link ReservationId} to
585   * obtain access to the reserved resources.
586   * </p>
587   * 
588   * <p>
589   * The system guarantees that during the time-range specified by the user, the
590   * reservationID will be corresponding to a valid reservation. The amount of
591   * capacity dedicated to such queue can vary overtime, depending of the
592   * allocation that has been determined. But it is guaranteed to satisfy all
593   * the constraint expressed by the user in the
594   * {@link ReservationSubmissionRequest}.
595   * </p>
596   * 
597   * @param request the request to submit a new Reservation
598   * @return response the {@link ReservationId} on accepting the submission
599   * @throws YarnException if the request is invalid or reservation cannot be
600   *           created successfully
601   * @throws IOException
602   * 
603   */
604  @Public
605  @Unstable
606  public ReservationSubmissionResponse submitReservation(
607      ReservationSubmissionRequest request) throws YarnException, IOException;
608
609  /**
610   * <p>
611   * The interface used by clients to update an existing Reservation. This is
612   * referred to as a re-negotiation process, in which a user that has
613   * previously submitted a Reservation.
614   * </p>
615   * 
616   * <p>
617   * The allocation is attempted by virtually substituting all previous
618   * allocations related to this Reservation with new ones, that satisfy the new
619   * {@link ReservationUpdateRequest}. Upon success the previous allocation is
620   * substituted by the new one, and on failure (i.e., if the system cannot find
621   * a valid allocation for the updated request), the previous allocation
622   * remains valid.
623   * 
624   * The {@link ReservationId} is not changed, and applications currently
625   * running within this reservation will automatically receive the resources
626   * based on the new allocation.
627   * </p>
628   * 
629   * @param request to update an existing Reservation (the ReservationRequest
630   *          should refer to an existing valid {@link ReservationId})
631   * @return response empty on successfully updating the existing reservation
632   * @throws YarnException if the request is invalid or reservation cannot be
633   *           updated successfully
634   * @throws IOException
635   * 
636   */
637  @Public
638  @Unstable
639  public ReservationUpdateResponse updateReservation(
640      ReservationUpdateRequest request) throws YarnException, IOException;
641
642  /**
643   * <p>
644   * The interface used by clients to remove an existing Reservation.
645   * 
646   * Upon deletion of a reservation applications running with this reservation,
647   * are automatically downgraded to normal jobs running without any dedicated
648   * reservation.
649   * </p>
650   * 
651   * @param request to remove an existing Reservation (the ReservationRequest
652   *          should refer to an existing valid {@link ReservationId})
653   * @return response empty on successfully deleting the existing reservation
654   * @throws YarnException if the request is invalid or reservation cannot be
655   *           deleted successfully
656   * @throws IOException
657   * 
658   */
659  @Public
660  @Unstable
661  public ReservationDeleteResponse deleteReservation(
662      ReservationDeleteRequest request) throws YarnException, IOException;
663
664  /**
665   * <p>
666   * The interface used by client to get node to labels mappings in existing cluster
667   * </p>
668   *
669   * @param request
670   * @return node to labels mappings
671   * @throws YarnException
672   * @throws IOException
673   */
674  @Public
675  @Unstable
676  public GetNodesToLabelsResponse getNodeToLabels(
677      GetNodesToLabelsRequest request) throws YarnException, IOException;
678
679  /**
680   * <p>
681   * The interface used by client to get node labels in the cluster
682   * </p>
683   *
684   * @param request to get node labels collection of this cluster
685   * @return node labels collection of this cluster
686   * @throws YarnException
687   * @throws IOException
688   */
689  @Public
690  @Unstable
691  public GetClusterNodeLabelsResponse getClusterNodeLabels(
692      GetClusterNodeLabelsRequest request) throws YarnException, IOException;
693}