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.client.api;
020
021import java.io.IOException;
022import java.util.EnumSet;
023import java.util.List;
024import java.util.Map;
025import java.util.Set;
026
027import org.apache.hadoop.classification.InterfaceAudience;
028import org.apache.hadoop.classification.InterfaceAudience.Private;
029import org.apache.hadoop.classification.InterfaceAudience.Public;
030import org.apache.hadoop.classification.InterfaceStability;
031import org.apache.hadoop.classification.InterfaceStability.Unstable;
032import org.apache.hadoop.io.Text;
033import org.apache.hadoop.service.AbstractService;
034import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
035import org.apache.hadoop.yarn.api.protocolrecords.GetNewReservationResponse;
036import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteRequest;
037import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteResponse;
038import org.apache.hadoop.yarn.api.protocolrecords.ReservationListRequest;
039import org.apache.hadoop.yarn.api.protocolrecords.ReservationListResponse;
040import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionRequest;
041import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionResponse;
042import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateRequest;
043import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateResponse;
044import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
045import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
046import org.apache.hadoop.yarn.api.records.ApplicationId;
047import org.apache.hadoop.yarn.api.records.ApplicationReport;
048import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
049import org.apache.hadoop.yarn.api.records.ContainerId;
050import org.apache.hadoop.yarn.api.records.ContainerReport;
051import org.apache.hadoop.yarn.api.records.NodeId;
052import org.apache.hadoop.yarn.api.records.NodeLabel;
053import org.apache.hadoop.yarn.api.records.NodeReport;
054import org.apache.hadoop.yarn.api.records.NodeState;
055import org.apache.hadoop.yarn.api.records.Priority;
056import org.apache.hadoop.yarn.api.records.QueueInfo;
057import org.apache.hadoop.yarn.api.records.QueueUserACLInfo;
058import org.apache.hadoop.yarn.api.records.ReservationDefinition;
059import org.apache.hadoop.yarn.api.records.ReservationId;
060import org.apache.hadoop.yarn.api.records.SignalContainerCommand;
061import org.apache.hadoop.yarn.api.records.Token;
062import org.apache.hadoop.yarn.api.records.YarnApplicationState;
063import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
064import org.apache.hadoop.yarn.client.api.impl.YarnClientImpl;
065import org.apache.hadoop.yarn.exceptions.ApplicationAttemptNotFoundException;
066import org.apache.hadoop.yarn.exceptions.ApplicationIdNotProvidedException;
067import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
068import org.apache.hadoop.yarn.exceptions.ContainerNotFoundException;
069import org.apache.hadoop.yarn.exceptions.YarnException;
070import org.apache.hadoop.yarn.security.AMRMTokenIdentifier;
071
072@InterfaceAudience.Public
073@InterfaceStability.Stable
074public abstract class YarnClient extends AbstractService {
075
076  /**
077   * Create a new instance of YarnClient.
078   */
079  @Public
080  public static YarnClient createYarnClient() {
081    YarnClient client = new YarnClientImpl();
082    return client;
083  }
084
085  @Private
086  protected YarnClient(String name) {
087    super(name);
088  }
089
090  /**
091   * <p>
092   * Obtain a {@link YarnClientApplication} for a new application,
093   * which in turn contains the {@link ApplicationSubmissionContext} and
094   * {@link org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse}
095   * objects.
096   * </p>
097   *
098   * @return {@link YarnClientApplication} built for a new application
099   * @throws YarnException
100   * @throws IOException
101   */
102  public abstract YarnClientApplication createApplication()
103      throws YarnException, IOException;
104
105  /**
106   * <p>
107   * Submit a new application to <code>YARN.</code> It is a blocking call - it
108   * will not return {@link ApplicationId} until the submitted application is
109   * submitted successfully and accepted by the ResourceManager.
110   * </p>
111   * 
112   * <p>
113   * Users should provide an {@link ApplicationId} as part of the parameter
114   * {@link ApplicationSubmissionContext} when submitting a new application,
115   * otherwise it will throw the {@link ApplicationIdNotProvidedException}.
116   * </p>
117   *
118   * <p>This internally calls {@link ApplicationClientProtocol#submitApplication
119   * (SubmitApplicationRequest)}, and after that, it internally invokes
120   * {@link ApplicationClientProtocol#getApplicationReport
121   * (GetApplicationReportRequest)} and waits till it can make sure that the
122   * application gets properly submitted. If RM fails over or RM restart
123   * happens before ResourceManager saves the application's state,
124   * {@link ApplicationClientProtocol
125   * #getApplicationReport(GetApplicationReportRequest)} will throw
126   * the {@link ApplicationNotFoundException}. This API automatically resubmits
127   * the application with the same {@link ApplicationSubmissionContext} when it
128   * catches the {@link ApplicationNotFoundException}</p>
129   *
130   * @param appContext
131   *          {@link ApplicationSubmissionContext} containing all the details
132   *          needed to submit a new application
133   * @return {@link ApplicationId} of the accepted application
134   * @throws YarnException
135   * @throws IOException
136   * @see #createApplication()
137   */
138  public abstract ApplicationId submitApplication(
139      ApplicationSubmissionContext appContext) throws YarnException,
140      IOException;
141
142  /**
143   * <p>
144   * Fail an application attempt identified by given ID.
145   * </p>
146   *
147   * @param applicationAttemptId
148   *          {@link ApplicationAttemptId} of the attempt to fail.
149   * @throws YarnException
150   *           in case of errors or if YARN rejects the request due to
151   *           access-control restrictions.
152   * @throws IOException
153   * @see #getQueueAclsInfo()
154   */
155  public abstract void failApplicationAttempt(
156      ApplicationAttemptId applicationAttemptId) throws YarnException,
157      IOException;
158
159  /**
160   * <p>
161   * Kill an application identified by given ID.
162   * </p>
163   * 
164   * @param applicationId
165   *          {@link ApplicationId} of the application that needs to be killed
166   * @throws YarnException
167   *           in case of errors or if YARN rejects the request due to
168   *           access-control restrictions.
169   * @throws IOException
170   * @see #getQueueAclsInfo()
171   */
172  public abstract void killApplication(ApplicationId applicationId) throws YarnException,
173      IOException;
174
175  /**
176   * <p>
177   * Get a report of the given Application.
178   * </p>
179   * 
180   * <p>
181   * In secure mode, <code>YARN</code> verifies access to the application, queue
182   * etc. before accepting the request.
183   * </p>
184   * 
185   * <p>
186   * If the user does not have <code>VIEW_APP</code> access then the following
187   * fields in the report will be set to stubbed values:
188   * <ul>
189   * <li>host - set to "N/A"</li>
190   * <li>RPC port - set to -1</li>
191   * <li>client token - set to "N/A"</li>
192   * <li>diagnostics - set to "N/A"</li>
193   * <li>tracking URL - set to "N/A"</li>
194   * <li>original tracking URL - set to "N/A"</li>
195   * <li>resource usage report - all values are -1</li>
196   * </ul>
197   * 
198   * @param appId
199   *          {@link ApplicationId} of the application that needs a report
200   * @return application report
201   * @throws YarnException
202   * @throws IOException
203   */
204  public abstract ApplicationReport getApplicationReport(ApplicationId appId)
205      throws YarnException, IOException;
206
207  /**
208   * Get the AMRM token of the application.
209   * <p>
210   * The AMRM token is required for AM to RM scheduling operations. For 
211   * managed Application Masters Yarn takes care of injecting it. For unmanaged
212   * Applications Masters, the token must be obtained via this method and set
213   * in the {@link org.apache.hadoop.security.UserGroupInformation} of the
214   * current user.
215   * <p>
216   * The AMRM token will be returned only if all the following conditions are
217   * met:
218   * <ul>
219   *   <li>the requester is the owner of the ApplicationMaster</li>
220   *   <li>the application master is an unmanaged ApplicationMaster</li>
221   *   <li>the application master is in ACCEPTED state</li>
222   * </ul>
223   * Else this method returns NULL.
224   *
225   * @param appId {@link ApplicationId} of the application to get the AMRM token
226   * @return the AMRM token if available
227   * @throws YarnException
228   * @throws IOException
229   */
230  public abstract org.apache.hadoop.security.token.Token<AMRMTokenIdentifier>
231      getAMRMToken(ApplicationId appId) throws YarnException, IOException;
232
233  /**
234   * <p>
235   * Get a report (ApplicationReport) of all Applications in the cluster.
236   * </p>
237   *
238   * <p>
239   * If the user does not have <code>VIEW_APP</code> access for an application
240   * then the corresponding report will be filtered as described in
241   * {@link #getApplicationReport(ApplicationId)}.
242   * </p>
243   *
244   * @return a list of reports of all running applications
245   * @throws YarnException
246   * @throws IOException
247   */
248  public abstract List<ApplicationReport> getApplications()
249      throws YarnException, IOException;
250
251  /**
252   * <p>
253   * Get a report (ApplicationReport) of Applications
254   * matching the given application types in the cluster.
255   * </p>
256   *
257   * <p>
258   * If the user does not have <code>VIEW_APP</code> access for an application
259   * then the corresponding report will be filtered as described in
260   * {@link #getApplicationReport(ApplicationId)}.
261   * </p>
262   *
263   * @param applicationTypes set of application types you are interested in
264   * @return a list of reports of applications
265   * @throws YarnException
266   * @throws IOException
267   */
268  public abstract List<ApplicationReport> getApplications(
269      Set<String> applicationTypes) throws YarnException, IOException;
270
271  /**
272   * <p>
273   * Get a report (ApplicationReport) of Applications matching the given
274   * application states in the cluster.
275   * </p>
276   *
277   * <p>
278   * If the user does not have <code>VIEW_APP</code> access for an application
279   * then the corresponding report will be filtered as described in
280   * {@link #getApplicationReport(ApplicationId)}.
281   * </p>
282   *
283   * @param applicationStates set of application states you are interested in
284   * @return a list of reports of applications
285   * @throws YarnException
286   * @throws IOException
287   */
288  public abstract List<ApplicationReport>
289      getApplications(EnumSet<YarnApplicationState> applicationStates)
290          throws YarnException, IOException;
291
292  /**
293   * <p>
294   * Get a report (ApplicationReport) of Applications matching the given
295   * application types and application states in the cluster.
296   * </p>
297   *
298   * <p>
299   * If the user does not have <code>VIEW_APP</code> access for an application
300   * then the corresponding report will be filtered as described in
301   * {@link #getApplicationReport(ApplicationId)}.
302   * </p>
303   *
304   * @param applicationTypes set of application types you are interested in
305   * @param applicationStates set of application states you are interested in
306   * @return a list of reports of applications
307   * @throws YarnException
308   * @throws IOException
309   */
310  public abstract List<ApplicationReport> getApplications(
311      Set<String> applicationTypes,
312      EnumSet<YarnApplicationState> applicationStates) throws YarnException,
313      IOException;
314
315  /**
316   * <p>
317   * Get a report (ApplicationReport) of Applications matching the given
318   * application types, application states and application tags in the cluster.
319   * </p>
320   *
321   * <p>
322   * If the user does not have <code>VIEW_APP</code> access for an application
323   * then the corresponding report will be filtered as described in
324   * {@link #getApplicationReport(ApplicationId)}.
325   * </p>
326   *
327   * @param applicationTypes set of application types you are interested in
328   * @param applicationStates set of application states you are interested in
329   * @param applicationTags set of application tags you are interested in
330   * @return a list of reports of applications
331   * @throws YarnException
332   * @throws IOException
333   */
334  public abstract List<ApplicationReport> getApplications(
335      Set<String> applicationTypes,
336      EnumSet<YarnApplicationState> applicationStates,
337      Set<String> applicationTags) throws YarnException,
338      IOException;
339
340  /**
341   * <p>
342   * Get a report (ApplicationReport) of Applications matching the given users,
343   * queues, application types and application states in the cluster. If any of
344   * the params is set to null, it is not used when filtering.
345   * </p>
346   *
347   * <p>
348   * If the user does not have <code>VIEW_APP</code> access for an application
349   * then the corresponding report will be filtered as described in
350   * {@link #getApplicationReport(ApplicationId)}.
351   * </p>
352   *
353   * @param queues set of queues you are interested in
354   * @param users set of users you are interested in
355   * @param applicationTypes set of application types you are interested in
356   * @param applicationStates set of application states you are interested in
357   * @return a list of reports of applications
358   * @throws YarnException
359   * @throws IOException
360   */
361  public abstract List<ApplicationReport> getApplications(Set<String> queues,
362      Set<String> users, Set<String> applicationTypes,
363      EnumSet<YarnApplicationState> applicationStates) throws YarnException,
364      IOException;
365
366  /**
367   * <p>
368   * Get metrics ({@link YarnClusterMetrics}) about the cluster.
369   * </p>
370   * 
371   * @return cluster metrics
372   * @throws YarnException
373   * @throws IOException
374   */
375  public abstract YarnClusterMetrics getYarnClusterMetrics() throws YarnException,
376      IOException;
377
378  /**
379   * <p>
380   * Get a report of nodes ({@link NodeReport}) in the cluster.
381   * </p>
382   * 
383   * @param states The {@link NodeState}s to filter on. If no filter states are
384   *          given, nodes in all states will be returned.
385   * @return A list of node reports
386   * @throws YarnException
387   * @throws IOException
388   */
389  public abstract List<NodeReport> getNodeReports(NodeState... states)
390      throws YarnException, IOException;
391
392  /**
393   * <p>
394   * Get a delegation token so as to be able to talk to YARN using those tokens.
395   * 
396   * @param renewer
397   *          Address of the renewer who can renew these tokens when needed by
398   *          securely talking to YARN.
399   * @return a delegation token ({@link Token}) that can be used to
400   *         talk to YARN
401   * @throws YarnException
402   * @throws IOException
403   */
404  public abstract Token getRMDelegationToken(Text renewer)
405      throws YarnException, IOException;
406
407  /**
408   * <p>
409   * Get information ({@link QueueInfo}) about a given <em>queue</em>.
410   * </p>
411   * 
412   * @param queueName
413   *          Name of the queue whose information is needed
414   * @return queue information
415   * @throws YarnException
416   *           in case of errors or if YARN rejects the request due to
417   *           access-control restrictions.
418   * @throws IOException
419   */
420  public abstract QueueInfo getQueueInfo(String queueName) throws YarnException,
421      IOException;
422
423  /**
424   * <p>
425   * Get information ({@link QueueInfo}) about all queues, recursively if there
426   * is a hierarchy
427   * </p>
428   * 
429   * @return a list of queue-information for all queues
430   * @throws YarnException
431   * @throws IOException
432   */
433  public abstract List<QueueInfo> getAllQueues() throws YarnException, IOException;
434
435  /**
436   * <p>
437   * Get information ({@link QueueInfo}) about top level queues.
438   * </p>
439   * 
440   * @return a list of queue-information for all the top-level queues
441   * @throws YarnException
442   * @throws IOException
443   */
444  public abstract List<QueueInfo> getRootQueueInfos() throws YarnException, IOException;
445
446  /**
447   * <p>
448   * Get information ({@link QueueInfo}) about all the immediate children queues
449   * of the given queue
450   * </p>
451   * 
452   * @param parent
453   *          Name of the queue whose child-queues' information is needed
454   * @return a list of queue-information for all queues who are direct children
455   *         of the given parent queue.
456   * @throws YarnException
457   * @throws IOException
458   */
459  public abstract List<QueueInfo> getChildQueueInfos(String parent) throws YarnException,
460      IOException;
461
462  /**
463   * <p>
464   * Get information about <em>acls</em> for <em>current user</em> on all the
465   * existing queues.
466   * </p>
467   * 
468   * @return a list of queue acls ({@link QueueUserACLInfo}) for
469   *         <em>current user</em>
470   * @throws YarnException
471   * @throws IOException
472   */
473  public abstract List<QueueUserACLInfo> getQueueAclsInfo() throws YarnException,
474      IOException;
475  
476  /**
477   * <p>
478   * Get a report of the given ApplicationAttempt.
479   * </p>
480   * 
481   * <p>
482   * In secure mode, <code>YARN</code> verifies access to the application, queue
483   * etc. before accepting the request.
484   * </p>
485   * 
486   * @param applicationAttemptId
487   *          {@link ApplicationAttemptId} of the application attempt that needs
488   *          a report
489   * @return application attempt report
490   * @throws YarnException
491   * @throws ApplicationAttemptNotFoundException if application attempt
492   *         not found
493   * @throws IOException
494   */
495  public abstract ApplicationAttemptReport getApplicationAttemptReport(
496      ApplicationAttemptId applicationAttemptId) throws YarnException, IOException;
497
498  /**
499   * <p>
500   * Get a report of all (ApplicationAttempts) of Application in the cluster.
501   * </p>
502   * 
503   * @param applicationId application id of the app
504   * @return a list of reports for all application attempts for specified
505   *         application.
506   * @throws YarnException
507   * @throws IOException
508   */
509  public abstract List<ApplicationAttemptReport> getApplicationAttempts(
510      ApplicationId applicationId) throws YarnException, IOException;
511
512  /**
513   * <p>
514   * Get a report of the given Container.
515   * </p>
516   * 
517   * <p>
518   * In secure mode, <code>YARN</code> verifies access to the application, queue
519   * etc. before accepting the request.
520   * </p>
521   * 
522   * @param containerId
523   *          {@link ContainerId} of the container that needs a report
524   * @return container report
525   * @throws YarnException
526   * @throws ContainerNotFoundException if container not found.
527   * @throws IOException
528   */
529  public abstract ContainerReport getContainerReport(ContainerId containerId)
530      throws YarnException, IOException;
531
532  /**
533   * <p>
534   * Get a report of all (Containers) of ApplicationAttempt in the cluster.
535   * </p>
536   * 
537   * @param applicationAttemptId application attempt id
538   * @return a list of reports of all containers for specified application
539   *         attempts
540   * @throws YarnException
541   * @throws IOException
542   */
543  public abstract List<ContainerReport> getContainers(
544      ApplicationAttemptId applicationAttemptId) throws YarnException,
545      IOException;
546  
547  /**
548   * <p>
549   * Attempts to move the given application to the given queue.
550   * </p>
551   * 
552   * @param appId
553   *    Application to move.
554   * @param queue
555   *    Queue to place it in to.
556   * @throws YarnException
557   * @throws IOException
558   */
559  public abstract void moveApplicationAcrossQueues(ApplicationId appId,
560      String queue) throws YarnException, IOException;
561
562  /**
563   * <p>
564   * Obtain a {@link GetNewReservationResponse} for a new reservation,
565   * which contains the {@link ReservationId} object.
566   * </p>
567   *
568   * @return The {@link GetNewReservationResponse} containing a new
569   *         {@link ReservationId} object.
570   * @throws YarnException if reservation cannot be created.
571   * @throws IOException if reservation cannot be created.
572   */
573  public abstract GetNewReservationResponse createReservation()
574    throws YarnException, IOException;
575
576  /**
577   * <p>
578   * The interface used by clients to submit a new reservation to the
579   * {@code ResourceManager}.
580   * </p>
581   * 
582   * <p>
583   * The client packages all details of its request in a
584   * {@link ReservationSubmissionRequest} object. This contains information
585   * about the amount of capacity, temporal constraints, and gang needs.
586   * Furthermore, the reservation might be composed of multiple stages, with
587   * ordering dependencies among them.
588   * </p>
589   * 
590   * <p>
591   * In order to respond, a new admission control component in the
592   * {@code ResourceManager} performs an analysis of the resources that have
593   * been committed over the period of time the user is requesting, verify that
594   * the user requests can be fulfilled, and that it respect a sharing policy
595   * (e.g., {@code CapacityOverTimePolicy}). Once it has positively determined
596   * that the ReservationRequest is satisfiable the {@code ResourceManager}
597   * answers with a {@link ReservationSubmissionResponse} that includes a
598   * {@link ReservationId}. Upon failure to find a valid allocation the response
599   * is an exception with the message detailing the reason of failure.
600   * </p>
601   * 
602   * <p>
603   * The semantics guarantees that the {@link ReservationId} returned,
604   * corresponds to a valid reservation existing in the time-range request by
605   * the user. The amount of capacity dedicated to such reservation can vary
606   * overtime, depending of the allocation that has been determined. But it is
607   * guaranteed to satisfy all the constraint expressed by the user in the
608   * {@link ReservationDefinition}
609   * </p>
610   * 
611   * @param request request to submit a new Reservation
612   * @return response contains the {@link ReservationId} on accepting the
613   *         submission
614   * @throws YarnException if the reservation cannot be created successfully
615   * @throws IOException
616   * 
617   */
618  @Public
619  @Unstable
620  public abstract ReservationSubmissionResponse submitReservation(
621      ReservationSubmissionRequest request) throws YarnException, IOException;
622
623  /**
624   * <p>
625   * The interface used by clients to update an existing Reservation. This is
626   * referred to as a re-negotiation process, in which a user that has
627   * previously submitted a Reservation.
628   * </p>
629   * 
630   * <p>
631   * The allocation is attempted by virtually substituting all previous
632   * allocations related to this Reservation with new ones, that satisfy the new
633   * {@link ReservationDefinition}. Upon success the previous allocation is
634   * atomically substituted by the new one, and on failure (i.e., if the system
635   * cannot find a valid allocation for the updated request), the previous
636   * allocation remains valid.
637   * </p>
638   * 
639   * @param request to update an existing Reservation (the
640   *          {@link ReservationUpdateRequest} should refer to an existing valid
641   *          {@link ReservationId})
642   * @return response empty on successfully updating the existing reservation
643   * @throws YarnException if the request is invalid or reservation cannot be
644   *           updated successfully
645   * @throws IOException
646   * 
647   */
648  @Public
649  @Unstable
650  public abstract ReservationUpdateResponse updateReservation(
651      ReservationUpdateRequest request) throws YarnException, IOException;
652
653  /**
654   * <p>
655   * The interface used by clients to remove an existing Reservation.
656   * </p>
657   * 
658   * @param request to remove an existing Reservation (the
659   *          {@link ReservationDeleteRequest} should refer to an existing valid
660   *          {@link ReservationId})
661   * @return response empty on successfully deleting the existing reservation
662   * @throws YarnException if the request is invalid or reservation cannot be
663   *           deleted successfully
664   * @throws IOException
665   * 
666   */
667  @Public
668  @Unstable
669  public abstract ReservationDeleteResponse deleteReservation(
670      ReservationDeleteRequest request) throws YarnException, IOException;
671
672  /**
673   * <p>
674   * The interface used by clients to get the list of reservations in a plan.
675   * The reservationId will be used to search for reservations to list if it is
676   * provided. Otherwise, it will select active reservations within the
677   * startTime and endTime (inclusive).
678   * </p>
679   *
680   * @param request to list reservations in a plan. Contains fields to select
681   *                String queue, ReservationId reservationId, long startTime,
682   *                long endTime, and a bool includeReservationAllocations.
683   *
684   *                queue: Required. Cannot be null or empty. Refers to the
685   *                reservable queue in the scheduler that was selected when
686   *                creating a reservation submission
687   *                {@link ReservationSubmissionRequest}.
688   *
689   *                reservationId: Optional. If provided, other fields will
690   *                be ignored.
691   *
692   *                startTime: Optional. If provided, only reservations that
693   *                end after the startTime will be selected. This defaults
694   *                to 0 if an invalid number is used.
695   *
696   *                endTime: Optional. If provided, only reservations that
697   *                start on or before endTime will be selected. This defaults
698   *                to Long.MAX_VALUE if an invalid number is used.
699   *
700   *                includeReservationAllocations: Optional. Flag that
701   *                determines whether the entire reservation allocations are
702   *                to be returned. Reservation allocations are subject to
703   *                change in the event of re-planning as described by
704   *                {@link ReservationDefinition}.
705   *
706   * @return response that contains information about reservations that are
707   *                being searched for.
708   * @throws YarnException if the request is invalid
709   * @throws IOException if the request failed otherwise
710   *
711   */
712  @Public
713  @Unstable
714  public abstract ReservationListResponse listReservations(
715          ReservationListRequest request) throws YarnException, IOException;
716
717  /**
718   * <p>
719   * The interface used by client to get node to labels mappings in existing cluster
720   * </p>
721   * 
722   * @return node to labels mappings
723   * @throws YarnException
724   * @throws IOException
725   */
726  @Public
727  @Unstable
728  public abstract Map<NodeId, Set<NodeLabel>> getNodeToLabels()
729      throws YarnException, IOException;
730
731  /**
732   * <p>
733   * The interface used by client to get labels to nodes mapping
734   * in existing cluster
735   * </p>
736   *
737   * @return node to labels mappings
738   * @throws YarnException
739   * @throws IOException
740   */
741  @Public
742  @Unstable
743  public abstract Map<NodeLabel, Set<NodeId>> getLabelsToNodes()
744      throws YarnException, IOException;
745
746  /**
747   * <p>
748   * The interface used by client to get labels to nodes mapping
749   * for specified labels in existing cluster
750   * </p>
751   *
752   * @param labels labels for which labels to nodes mapping has to be retrieved
753   * @return labels to nodes mappings for specific labels
754   * @throws YarnException
755   * @throws IOException
756   */
757  @Public
758  @Unstable
759  public abstract Map<NodeLabel, Set<NodeId>> getLabelsToNodes(
760      Set<String> labels) throws YarnException, IOException;
761
762  /**
763   * <p>
764   * The interface used by client to get node labels in the cluster
765   * </p>
766   *
767   * @return cluster node labels collection
768   * @throws YarnException when there is a failure in
769   *           {@link ApplicationClientProtocol}
770   * @throws IOException when there is a failure in
771   *           {@link ApplicationClientProtocol}
772   */
773  @Public
774  @Unstable
775  public abstract List<NodeLabel> getClusterNodeLabels()
776      throws YarnException, IOException;
777
778  /**
779   * <p>
780   * The interface used by client to set priority of an application
781   * </p>
782   * @param applicationId
783   * @param priority
784   * @return updated priority of an application.
785   * @throws YarnException
786   * @throws IOException
787   */
788  @Public
789  @Unstable
790  public abstract Priority updateApplicationPriority(
791      ApplicationId applicationId,
792      Priority priority) throws YarnException, IOException;
793
794  /**
795   * <p>
796   * Signal a container identified by given ID.
797   * </p>
798   *
799   * @param containerId
800   *          {@link ContainerId} of the container that needs to be signaled
801   * @param command the signal container command
802   * @throws YarnException
803   * @throws IOException
804   */
805  public abstract void signalToContainer(ContainerId containerId,
806      SignalContainerCommand command) throws YarnException, IOException;
807}