org.apache.hadoop.yarn.api

## Interface ApplicationMasterProtocol

-     @InterfaceAudience.Public
       @InterfaceStability.Stable
      public interface ApplicationMasterProtocol

  The protocol between a live instance of `ApplicationMaster` and the `ResourceManager`.

  This is used by the `ApplicationMaster` to register/unregister and to request and obtain resources in the cluster from the `ResourceManager`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `AllocateResponse` | `allocate(AllocateRequest request)` The main interface between an `ApplicationMaster` and the `ResourceManager`.
    `FinishApplicationMasterResponse` | `finishApplicationMaster(FinishApplicationMasterRequest request)` The interface used by an `ApplicationMaster` to notify the `ResourceManager` about its completion (success or failed).
    `RegisterApplicationMasterResponse` | `registerApplicationMaster(RegisterApplicationMasterRequest request)` The interface used by a new `ApplicationMaster` to register with the `ResourceManager`.

- - ### Method Detail

    - #### registerApplicationMaster

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          RegisterApplicationMasterResponse registerApplicationMaster(RegisterApplicationMasterRequest request)
                                                                                                                     throws YarnException,
                                                                                                                            IOException

      The interface used by a new `ApplicationMaster` to register with the `ResourceManager`.

      The `ApplicationMaster` needs to provide details such as RPC Port, HTTP tracking url etc. as specified in `RegisterApplicationMasterRequest`.

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

      Re-register is only allowed for `Unmanaged Application Master` (UAM) HA, with `ApplicationSubmissionContext.getKeepContainersAcrossApplicationAttempts()` set to true.

      Parameters:
        `request` - registration request
      Returns:
        registration respose
      Throws:
        `YarnException`
        `IOException`
        `org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException` - The exception is thrown when an ApplicationMaster tries to register more then once.
      See Also:
        `RegisterApplicationMasterRequest`, `RegisterApplicationMasterResponse`

    - #### finishApplicationMaster

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          FinishApplicationMasterResponse finishApplicationMaster(FinishApplicationMasterRequest request)
                                                                                                                 throws YarnException,
                                                                                                                        IOException

      The interface used by an `ApplicationMaster` to notify the `ResourceManager` about its completion (success or failed).

      The `ApplicationMaster` has to provide details such as final state, diagnostics (in case of failures) etc. as specified in `FinishApplicationMasterRequest`.

      The `ResourceManager` responds with `FinishApplicationMasterResponse`.

      Parameters:
        `request` - completion request
      Returns:
        completion response
      Throws:
        `YarnException`
        `IOException`
      See Also:
        `FinishApplicationMasterRequest`, `FinishApplicationMasterResponse`

    - #### allocate

          @InterfaceAudience.Public
           @InterfaceStability.Stable
          AllocateResponse allocate(AllocateRequest request)
                                                                                   throws YarnException,
                                                                                          IOException

      The main interface between an `ApplicationMaster` and the `ResourceManager`.

      The `ApplicationMaster` uses this interface to provide a list of `ResourceRequest` and returns unused `Container` allocated to it via `AllocateRequest`. Optionally, the `ApplicationMaster` can also blacklist resources which it doesn't want to use.

      This also doubles up as a heartbeat to let the `ResourceManager` know that the `ApplicationMaster` is alive. Thus, applications should periodically make this call to be kept alive. The frequency depends on `YarnConfiguration.RM_AM_EXPIRY_INTERVAL_MS` which defaults to `YarnConfiguration.DEFAULT_RM_AM_EXPIRY_INTERVAL_MS`.

      The `ResourceManager` responds with list of allocated `Container`, status of completed containers and headroom information for the application.

      The `ApplicationMaster` can use the available headroom (resources) to decide how to utilized allocated resources and make informed decisions about future resource requests.

      Parameters:
        `request` - allocation request
      Returns:
        allocation response
      Throws:
        `YarnException`
        `IOException`
        `org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException` - This exception is thrown when an ApplicationMaster calls allocate without registering first.
        `org.apache.hadoop.yarn.exceptions.InvalidResourceBlacklistRequestException` - This exception is thrown when an application provides an invalid specification for blacklist of resources.
        `org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException` - This exception is thrown when a `ResourceRequest` is out of the range of the configured lower and upper limits on the resources.
      See Also:
        `AllocateRequest`, `AllocateResponse`

Copyright © 2022 Apache Software Foundation. All rights reserved.