org.apache.hadoop.yarn.api

## Interface ApplicationClientProtocol

- All Superinterfaces:
    org.apache.hadoop.yarn.api.ApplicationBaseProtocol

      @InterfaceAudience.Public
       @InterfaceStability.Stable
      public interface ApplicationClientProtocol
      extends org.apache.hadoop.yarn.api.ApplicationBaseProtocol

  The protocol between clients and the `ResourceManager` to submit/abort jobs and to get information on applications, cluster metrics, nodes, queues and ACLs.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ReservationDeleteResponse` | `deleteReservation(ReservationDeleteRequest request)` The interface used by clients to remove an existing Reservation.
    `FailApplicationAttemptResponse` | `failApplicationAttempt(FailApplicationAttemptRequest request)` The interface used by clients to request the `ResourceManager` to fail an application attempt.
    `KillApplicationResponse` | `forceKillApplication(KillApplicationRequest request)` The interface used by clients to request the `ResourceManager` to abort submitted application.
    `GetAttributesToNodesResponse` | `getAttributesToNodes(GetAttributesToNodesRequest request)` The interface used by client to get attributes to nodes mappings available in ResourceManager.
    `GetClusterMetricsResponse` | `getClusterMetrics(GetClusterMetricsRequest request)` The interface used by clients to get metrics about the cluster from the `ResourceManager`.
    `GetClusterNodeAttributesResponse` | `getClusterNodeAttributes(GetClusterNodeAttributesRequest request)` The interface used by client to get node attributes available in ResourceManager.
    `GetClusterNodeLabelsResponse` | `getClusterNodeLabels(GetClusterNodeLabelsRequest request)` The interface used by client to get node labels in the cluster
    `GetClusterNodesResponse` | `getClusterNodes(GetClusterNodesRequest request)` The interface used by clients to get a report of all nodes in the cluster from the `ResourceManager`.
    `org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesResponse` | `getLabelsToNodes(org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesRequest request)` The interface used by client to get labels to nodes mappings in existing cluster
    `GetNewApplicationResponse` | `getNewApplication(GetNewApplicationRequest request)` The interface used by clients to obtain a new `ApplicationId` for submitting new applications.
    `GetNewReservationResponse` | `getNewReservation(GetNewReservationRequest request)` The interface used by clients to obtain a new `ReservationId` for submitting new reservations.
    `GetNodesToAttributesResponse` | `getNodesToAttributes(GetNodesToAttributesRequest request)` The interface used by client to get node to attributes mappings.
    `org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse` | `getNodeToLabels(org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest request)` The interface used by client to get node to labels mappings in existing cluster
    `GetQueueInfoResponse` | `getQueueInfo(GetQueueInfoRequest request)` The interface used by clients to get information about queues from the `ResourceManager`.
    `GetQueueUserAclsInfoResponse` | `getQueueUserAcls(GetQueueUserAclsInfoRequest request)` The interface used by clients to get information about queue acls for current user from the `ResourceManager`.
    `GetResourceProfileResponse` | `getResourceProfile(GetResourceProfileRequest request)` The interface to get the details for a specific resource profile.
    `GetAllResourceProfilesResponse` | `getResourceProfiles(GetAllResourceProfilesRequest request)` The interface used by clients to get all the resource profiles that are available on the ResourceManager.
    `GetAllResourceTypeInfoResponse` | `getResourceTypeInfo(GetAllResourceTypeInfoRequest request)` The interface to get the details for a specific resource profile.
    `ReservationListResponse` | `listReservations(ReservationListRequest request)` The interface used by clients to get the list of reservations in a plan.
    `MoveApplicationAcrossQueuesResponse` | `moveApplicationAcrossQueues(MoveApplicationAcrossQueuesRequest request)` Move an application to a new queue.
    `SignalContainerResponse` | `signalToContainer(SignalContainerRequest request)` The interface used by clients to request the `ResourceManager` to signal a container.
    `SubmitApplicationResponse` | `submitApplication(SubmitApplicationRequest request)` The interface used by clients to submit a new application to the `ResourceManager.`
    `ReservationSubmissionResponse` | `submitReservation(ReservationSubmissionRequest request)` The interface used by clients to submit a new reservation to the `ResourceManager`.
    `UpdateApplicationPriorityResponse` | `updateApplicationPriority(UpdateApplicationPriorityRequest request)` The interface used by client to set priority of an application.
    `UpdateApplicationTimeoutsResponse` | `updateApplicationTimeouts(UpdateApplicationTimeoutsRequest request)` The interface used by client to set ApplicationTimeouts of an application.
    `ReservationUpdateResponse` | `updateReservation(ReservationUpdateRequest request)` The interface used by clients to update an existing Reservation.

    - ### Methods inherited from interface org.apache.hadoop.yarn.api.ApplicationBaseProtocol

      `getApplicationAttemptReport, getApplicationAttempts, getApplicationReport, getApplications, getContainerReport, getContainers, getDelegationToken`

- - ### Method Detail

    - #### getNewApplication

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          GetNewApplicationResponse getNewApplication(GetNewApplicationRequest request)
                                                                                                     throws YarnException,
                                                                                                            IOException

      The interface used by clients to obtain a new `ApplicationId` for submitting new applications.

      The `ResourceManager` responds with a new, monotonically increasing, `ApplicationId` which is used by the client to submit a new application.

      The `ResourceManager` also responds with details such as maximum resource capabilities in the cluster as specified in `GetNewApplicationResponse`.

      Parameters:
        `request` - request to get a new `ApplicationId`
      Returns:
        response containing the new `ApplicationId` to be used to submit an application
      Throws:
        `YarnException`
        `IOException`
      See Also:
        `submitApplication(SubmitApplicationRequest)`

    - #### submitApplication

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          SubmitApplicationResponse submitApplication(SubmitApplicationRequest request)
                                                                                                     throws YarnException,
                                                                                                            IOException

      The interface used by clients to submit a new application to the `ResourceManager.`

      The client is required to provide details such as queue, `Resource` required to run the `ApplicationMaster`, the equivalent of `ContainerLaunchContext` for launching the `ApplicationMaster` etc. via the `SubmitApplicationRequest`.

      Currently the `ResourceManager` sends an immediate (empty) `SubmitApplicationResponse` on accepting the submission and throws an exception if it rejects the submission. However, this call needs to be followed by `ApplicationBaseProtocol.getApplicationReport(GetApplicationReportRequest)` to make sure that the application gets properly submitted - obtaining a `SubmitApplicationResponse` from ResourceManager doesn't guarantee that RM 'remembers' this application beyond failover or restart. If RM failover or RM restart happens before ResourceManager saves the application's state successfully, the subsequent `ApplicationBaseProtocol.getApplicationReport(GetApplicationReportRequest)` will throw a `ApplicationNotFoundException`. The Clients need to re-submit the application with the same `ApplicationSubmissionContext` when it encounters the `ApplicationNotFoundException` on the `ApplicationBaseProtocol.getApplicationReport(GetApplicationReportRequest)` call.

      During the submission process, it checks whether the application already exists. If the application exists, it will simply return SubmitApplicationResponse

      In secure mode,the `ResourceManager` verifies access to queues etc. before accepting the application submission.

      Parameters:
        `request` - request to submit a new application
      Returns:
        (empty) response on accepting the submission
      Throws:
        `YarnException`
        `IOException`
      See Also:
        `getNewApplication(GetNewApplicationRequest)`

    - #### failApplicationAttempt

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          FailApplicationAttemptResponse failApplicationAttempt(FailApplicationAttemptRequest request)
                                                                                                                 throws YarnException,
                                                                                                                        IOException

      The interface used by clients to request the `ResourceManager` to fail an application attempt.

      The client, via `FailApplicationAttemptRequest` provides the `ApplicationAttemptId` of the attempt to be failed.

      In secure mode,the `ResourceManager` verifies access to the application, queue etc. before failing the attempt.

      Currently, the `ResourceManager` returns an empty response on success and throws an exception on rejecting the request.

      Parameters:
        `request` - request to fail an attempt
      Returns:
        `ResourceManager` returns an empty response on success and throws an exception on rejecting the request
      Throws:
        `YarnException`
        `IOException`
      See Also:
        `getQueueUserAcls(GetQueueUserAclsInfoRequest)`

    - #### forceKillApplication

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          KillApplicationResponse forceKillApplication(KillApplicationRequest request)
                                                                                                      throws YarnException,
                                                                                                             IOException

      The interface used by clients to request the `ResourceManager` to abort submitted application.

      The client, via `KillApplicationRequest` provides the `ApplicationId` of the application to be aborted.

      In secure mode,the `ResourceManager` verifies access to the application, queue etc. before terminating the application.

      Currently, the `ResourceManager` returns an empty response on success and throws an exception on rejecting the request.

      Parameters:
        `request` - request to abort a submitted application
      Returns:
        `ResourceManager` returns an empty response on success and throws an exception on rejecting the request
      Throws:
        `YarnException`
        `IOException`
      See Also:
        `getQueueUserAcls(GetQueueUserAclsInfoRequest)`

    - #### getClusterMetrics

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          GetClusterMetricsResponse getClusterMetrics(GetClusterMetricsRequest request)
                                                                                                     throws YarnException,
                                                                                                            IOException

      The interface used by clients to get metrics about the cluster from the `ResourceManager`.

      The `ResourceManager` responds with a `GetClusterMetricsResponse` which includes the `YarnClusterMetrics` with details such as number of current nodes in the cluster.

      Parameters:
        `request` - request for cluster metrics
      Returns:
        cluster metrics
      Throws:
        `YarnException`
        `IOException`

    - #### getClusterNodes

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          GetClusterNodesResponse getClusterNodes(GetClusterNodesRequest request)
                                                                                                 throws YarnException,
                                                                                                        IOException

      The interface used by clients to get a report of all nodes in the cluster from the `ResourceManager`.

      The `ResourceManager` responds with a `GetClusterNodesResponse` which includes the `NodeReport` for all the nodes in the cluster.

      Parameters:
        `request` - request for report on all nodes
      Returns:
        report on all nodes
      Throws:
        `YarnException`
        `IOException`

    - #### getQueueInfo

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          GetQueueInfoResponse getQueueInfo(GetQueueInfoRequest request)
                                                                                           throws YarnException,
                                                                                                  IOException

      The interface used by clients to get information about queues from the `ResourceManager`.

      The client, via `GetQueueInfoRequest`, can ask for details such as used/total resources, child queues, running applications etc.

      In secure mode,the `ResourceManager` verifies access before providing the information.

      Parameters:
        `request` - request to get queue information
      Returns:
        queue information
      Throws:
        `YarnException`
        `IOException`

    - #### getQueueUserAcls

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          GetQueueUserAclsInfoResponse getQueueUserAcls(GetQueueUserAclsInfoRequest request)
                                                                                                       throws YarnException,
                                                                                                              IOException

      The interface used by clients to get information about queue acls for current user from the `ResourceManager`.

      The `ResourceManager` responds with queue acls for all existing queues.

      Parameters:
        `request` - request to get queue acls for current user
      Returns:
        queue acls for current user
      Throws:
        `YarnException`
        `IOException`

    - #### moveApplicationAcrossQueues

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues(MoveApplicationAcrossQueuesRequest request)
                                                                                                                           throws YarnException,
                                                                                                                                  IOException

      Move an application to a new queue.
      Parameters:
        `request` - the application ID and the target queue
      Returns:
        an empty response
      Throws:
        `YarnException`
        `IOException`

    - #### getNewReservation

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetNewReservationResponse getNewReservation(GetNewReservationRequest request)
                                                                                                       throws YarnException,
                                                                                                              IOException

      The interface used by clients to obtain a new `ReservationId` for submitting new reservations.

      The `ResourceManager` responds with a new, unique, `ReservationId` which is used by the client to submit a new reservation.

      Parameters:
        `request` - to get a new `ReservationId`
      Returns:
        response containing the new `ReservationId` to be used to submit a new reservation
      Throws:
        `YarnException` - if the reservation system is not enabled.
        `IOException` - on IO failures.
      See Also:
        `submitReservation(ReservationSubmissionRequest)`

    - #### submitReservation

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          ReservationSubmissionResponse submitReservation(ReservationSubmissionRequest request)
                                                                                                           throws YarnException,
                                                                                                                  IOException

      The interface used by clients to submit a new reservation to the `ResourceManager`.

      The client packages all details of its request in a `ReservationSubmissionRequest` object. This contains information about the amount of capacity, temporal constraints, and concurrency needs. Furthermore, the reservation might be composed of multiple stages, with ordering dependencies among them.

      In order to respond, a new admission control component in the `ResourceManager` performs an analysis of the resources that have been committed over the period of time the user is requesting, verify that the user requests can be fulfilled, and that it respect a sharing policy (e.g., `CapacityOverTimePolicy`). Once it has positively determined that the ReservationSubmissionRequest is satisfiable the `ResourceManager` answers with a `ReservationSubmissionResponse` that include a non-null `ReservationId`. Upon failure to find a valid allocation the response is an exception with the reason. On application submission the client can use this `ReservationId` to obtain access to the reserved resources.

      The system guarantees that during the time-range specified by the user, the reservationID will be corresponding to a valid reservation. The amount of capacity dedicated to such queue can vary overtime, depending of the allocation that has been determined. But it is guaranteed to satisfy all the constraint expressed by the user in the `ReservationSubmissionRequest`.

      Parameters:
        `request` - the request to submit a new Reservation
      Returns:
        response the `ReservationId` on accepting the submission
      Throws:
        `YarnException` - if the request is invalid or reservation cannot be created successfully
        `IOException`

    - #### updateReservation

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          ReservationUpdateResponse updateReservation(ReservationUpdateRequest request)
                                                                                                       throws YarnException,
                                                                                                              IOException

      The interface used by clients to update an existing Reservation. This is referred to as a re-negotiation process, in which a user that has previously submitted a Reservation.

      The allocation is attempted by virtually substituting all previous allocations related to this Reservation with new ones, that satisfy the new `ReservationUpdateRequest`. Upon success the previous allocation is substituted by the new one, and on failure (i.e., if the system cannot find a valid allocation for the updated request), the previous allocation remains valid. The `ReservationId` is not changed, and applications currently running within this reservation will automatically receive the resources based on the new allocation.

      Parameters:
        `request` - to update an existing Reservation (the ReservationRequest should refer to an existing valid `ReservationId`)
      Returns:
        response empty on successfully updating the existing reservation
      Throws:
        `YarnException` - if the request is invalid or reservation cannot be updated successfully
        `IOException`

    - #### deleteReservation

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          ReservationDeleteResponse deleteReservation(ReservationDeleteRequest request)
                                                                                                       throws YarnException,
                                                                                                              IOException

      The interface used by clients to remove an existing Reservation. Upon deletion of a reservation applications running with this reservation, are automatically downgraded to normal jobs running without any dedicated reservation.

      Parameters:
        `request` - to remove an existing Reservation (the ReservationRequest should refer to an existing valid `ReservationId`)
      Returns:
        response empty on successfully deleting the existing reservation
      Throws:
        `YarnException` - if the request is invalid or reservation cannot be deleted successfully
        `IOException`

    - #### listReservations

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          ReservationListResponse listReservations(ReservationListRequest request)
                                                                                                    throws YarnException,
                                                                                                           IOException

      The interface used by clients to get the list of reservations in a plan. The reservationId will be used to search for reservations to list if it is provided. Otherwise, it will select active reservations within the startTime and endTime (inclusive).

      Parameters:
        `request` - to list reservations in a plan. Contains fields to select String queue, ReservationId reservationId, long startTime, long endTime, and a bool includeReservationAllocations. queue: Required. Cannot be null or empty. Refers to the reservable queue in the scheduler that was selected when creating a reservation submission `ReservationSubmissionRequest`. reservationId: Optional. If provided, other fields will be ignored. startTime: Optional. If provided, only reservations that end after the startTime will be selected. This defaults to 0 if an invalid number is used. endTime: Optional. If provided, only reservations that start on or before endTime will be selected. This defaults to Long.MAX_VALUE if an invalid number is used. includeReservationAllocations: Optional. Flag that determines whether the entire reservation allocations are to be returned. Reservation allocations are subject to change in the event of re-planning as described by `ReservationDefinition`.
      Returns:
        response that contains information about reservations that are being searched for.
      Throws:
        `YarnException` - if the request is invalid
        `IOException` - on IO failures

    - #### getNodeToLabels

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse getNodeToLabels(org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest request)
                                                                                                                                               throws YarnException,
                                                                                                                                                      IOException

      The interface used by client to get node to labels mappings in existing cluster

      Parameters:
        `request` -
      Returns:
        node to labels mappings
      Throws:
        `YarnException`
        `IOException`

    - #### getLabelsToNodes

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesResponse getLabelsToNodes(org.apache.hadoop.yarn.api.protocolrecords.GetLabelsToNodesRequest request)
                                                                                                                                                throws YarnException,
                                                                                                                                                       IOException

      The interface used by client to get labels to nodes mappings in existing cluster

      Parameters:
        `request` -
      Returns:
        labels to nodes mappings
      Throws:
        `YarnException`
        `IOException`

    - #### getClusterNodeLabels

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetClusterNodeLabelsResponse getClusterNodeLabels(GetClusterNodeLabelsRequest request)
                                                                                                             throws YarnException,
                                                                                                                    IOException

      The interface used by client to get node labels in the cluster

      Parameters:
        `request` - to get node labels collection of this cluster
      Returns:
        node labels collection of this cluster
      Throws:
        `YarnException`
        `IOException`

    - #### updateApplicationPriority

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          UpdateApplicationPriorityResponse updateApplicationPriority(UpdateApplicationPriorityRequest request)
                                                                                                                       throws YarnException,
                                                                                                                              IOException

      The interface used by client to set priority of an application.

      Parameters:
        `request` - to set priority of an application
      Returns:
        an empty response
      Throws:
        `YarnException`
        `IOException`

    - #### signalToContainer

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          SignalContainerResponse signalToContainer(SignalContainerRequest request)
                                                                                                     throws YarnException,
                                                                                                            IOException

      The interface used by clients to request the `ResourceManager` to signal a container. For example, the client can send command OUTPUT_THREAD_DUMP to dump threads of the container.

      The client, via `SignalContainerRequest` provides the id of the container and the signal command.

      In secure mode,the `ResourceManager` verifies access to the application before signaling the container. The user needs to have `MODIFY_APP` permission.

      Currently, the `ResourceManager` returns an empty response on success and throws an exception on rejecting the request.

      Parameters:
        `request` - request to signal a container
      Returns:
        `ResourceManager` returns an empty response on success and throws an exception on rejecting the request
      Throws:
        `YarnException`
        `IOException`

    - #### updateApplicationTimeouts

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          UpdateApplicationTimeoutsResponse updateApplicationTimeouts(UpdateApplicationTimeoutsRequest request)
                                                                                                                       throws YarnException,
                                                                                                                              IOException

      The interface used by client to set ApplicationTimeouts of an application. The UpdateApplicationTimeoutsRequest should have timeout value with absolute time with ISO8601 format yyyy-MM-dd'T'HH:mm:ss.SSSZ.

      Note: If application timeout value is less than or equal to current time then update application throws YarnException.
      Parameters:
        `request` - to set ApplicationTimeouts of an application
      Returns:
        a response with updated timeouts.
      Throws:
        `YarnException` - if update request has empty values or application is in completing states.
        `IOException` - on IO failures

    - #### getResourceProfiles

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetAllResourceProfilesResponse getResourceProfiles(GetAllResourceProfilesRequest request)
                                                                                                              throws YarnException,
                                                                                                                     IOException

      The interface used by clients to get all the resource profiles that are available on the ResourceManager.

      Parameters:
        `request` - request to get all the resource profiles
      Returns:
        Response containing a map of the profile name to Resource capabilities
      Throws:
        `YARNFeatureNotEnabledException` - if resource-profile is disabled
        `YarnException` - if any error happens inside YARN
        `IOException` - in case of other errors

    - #### getResourceProfile

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetResourceProfileResponse getResourceProfile(GetResourceProfileRequest request)
                                                                                                         throws YarnException,
                                                                                                                IOException

      The interface to get the details for a specific resource profile.

      Parameters:
        `request` - request to get the details of a resource profile
      Returns:
        Response containing the details for a particular resource profile
      Throws:
        `YARNFeatureNotEnabledException` - if resource-profile is disabled
        `YarnException` - if any error happens inside YARN
        `IOException` - in case of other errors

    - #### getResourceTypeInfo

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetAllResourceTypeInfoResponse getResourceTypeInfo(GetAllResourceTypeInfoRequest request)
                                                                                                              throws YarnException,
                                                                                                                     IOException

      The interface to get the details for a specific resource profile.

      Parameters:
        `request` - request to get the details of a resource profile
      Returns:
        Response containing the details for a particular resource profile
      Throws:
        `YarnException` - if any error happens inside YARN
        `IOException` - in case of other errors

    - #### getAttributesToNodes

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetAttributesToNodesResponse getAttributesToNodes(GetAttributesToNodesRequest request)
                                                                                                             throws YarnException,
                                                                                                                    IOException

      The interface used by client to get attributes to nodes mappings available in ResourceManager.

      Parameters:
        `request` - request to get details of attributes to nodes mapping.
      Returns:
        Response containing the details of attributes to nodes mappings.
      Throws:
        `YarnException` - if any error happens inside YARN
        `IOException` - incase of other errors

    - #### getClusterNodeAttributes

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetClusterNodeAttributesResponse getClusterNodeAttributes(GetClusterNodeAttributesRequest request)
                                                                                                                     throws YarnException,
                                                                                                                            IOException

      The interface used by client to get node attributes available in ResourceManager.

      Parameters:
        `request` - request to get node attributes collection of this cluster.
      Returns:
        Response containing node attributes collection.
      Throws:
        `YarnException` - if any error happens inside YARN.
        `IOException` - incase of other errors.

    - #### getNodesToAttributes

          @InterfaceAudience.Public
           @InterfaceStability.Unstable
          GetNodesToAttributesResponse getNodesToAttributes(GetNodesToAttributesRequest request)
                                                                                                             throws YarnException,
                                                                                                                    IOException

      The interface used by client to get node to attributes mappings. in existing cluster.

      Parameters:
        `request` - request to get nodes to attributes mapping.
      Returns:
        nodes to attributes mappings.
      Throws:
        `YarnException` - if any error happens inside YARN.
        `IOException`

Copyright © 2022 Apache Software Foundation. All rights reserved.