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