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 java.io.IOException;
022
023 import org.apache.hadoop.classification.InterfaceAudience.Private;
024 import org.apache.hadoop.classification.InterfaceAudience.Public;
025 import org.apache.hadoop.classification.InterfaceStability.Stable;
026 import org.apache.hadoop.classification.InterfaceStability.Unstable;
027 import org.apache.hadoop.io.retry.Idempotent;
028 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenRequest;
029 import org.apache.hadoop.yarn.api.protocolrecords.CancelDelegationTokenResponse;
030 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportRequest;
031 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptReportResponse;
032 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsRequest;
033 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationAttemptsResponse;
034 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
035 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
036 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsRequest;
037 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationsResponse;
038 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
039 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
040 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsRequest;
041 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsResponse;
042 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
043 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
044 import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportRequest;
045 import org.apache.hadoop.yarn.api.protocolrecords.GetContainerReportResponse;
046 import org.apache.hadoop.yarn.api.protocolrecords.GetContainersRequest;
047 import org.apache.hadoop.yarn.api.protocolrecords.GetContainersResponse;
048 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
049 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
050 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
051 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
052 import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest;
053 import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse;
054 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
055 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
056 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
057 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
058 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
059 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
060 import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesRequest;
061 import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesResponse;
062 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenRequest;
063 import org.apache.hadoop.yarn.api.protocolrecords.RenewDelegationTokenResponse;
064 import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteRequest;
065 import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteResponse;
066 import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionRequest;
067 import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionResponse;
068 import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateRequest;
069 import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateResponse;
070 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
071 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
072 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
073 import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
074 import org.apache.hadoop.yarn.api.records.ApplicationId;
075 import org.apache.hadoop.yarn.api.records.ApplicationReport;
076 import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
077 import org.apache.hadoop.yarn.api.records.ContainerId;
078 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
079 import org.apache.hadoop.yarn.api.records.ContainerReport;
080 import org.apache.hadoop.yarn.api.records.NodeReport;
081 import org.apache.hadoop.yarn.api.records.ReservationId;
082 import org.apache.hadoop.yarn.api.records.Resource;
083 import org.apache.hadoop.yarn.api.records.ResourceRequest;
084 import org.apache.hadoop.yarn.api.records.Token;
085 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
086 import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
087 import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException;
088 import 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
097 public 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 }