ApplicationMasterProtocol (Apache Hadoop Main 3.5.0 API)
Description: declaration: package: org.apache.hadoop.yarn.api, interface: ApplicationMasterProtocol

Package org.apache.hadoop.yarn.api

# Interface ApplicationMasterProtocol

@Public @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

  Modifier and Type
  Method
  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 Details

  - ### registerApplicationMaster

    @Public @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 response
    Throws:
      `YarnException` - exceptions from yarn servers.
      `IOException` - io error occur.
      `org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException` - The exception is thrown when an ApplicationMaster tries to register more then once.
    See Also:
      - `RegisterApplicationMasterRequest`
      - `RegisterApplicationMasterResponse`

  - ### finishApplicationMaster

    @Public @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` - exceptions from yarn servers.
      `IOException` - io error occur.
    See Also:
      - `FinishApplicationMasterRequest`
      - `FinishApplicationMasterResponse`

  - ### allocate

    @Public @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` - exceptions from yarn servers.
      `IOException` - io error occur.
      `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`