org.apache.hadoop.yarn.api
Interface ApplicationClientProtocol


@InterfaceAudience.Public
@InterfaceStability.Stable
public interface ApplicationClientProtocol

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
 ReservationDeleteResponse deleteReservation(ReservationDeleteRequest request)
           The interface used by clients to remove an existing Reservation.
 KillApplicationResponse forceKillApplication(KillApplicationRequest request)
          The interface used by clients to request the ResourceManager to abort submitted application.
 GetApplicationAttemptReportResponse getApplicationAttemptReport(GetApplicationAttemptReportRequest request)
           The interface used by clients to get a report of an Application Attempt from the ResourceManager
 GetApplicationAttemptsResponse getApplicationAttempts(GetApplicationAttemptsRequest request)
           The interface used by clients to get a report of all Application attempts in the cluster from the ResourceManager
 GetApplicationReportResponse getApplicationReport(GetApplicationReportRequest request)
          The interface used by clients to get a report of an Application from the ResourceManager.
 GetApplicationsResponse getApplications(GetApplicationsRequest request)
          The interface used by clients to get a report of Applications matching the filters defined by GetApplicationsRequest in the cluster from the ResourceManager.
 GetClusterMetricsResponse getClusterMetrics(GetClusterMetricsRequest request)
          The interface used by clients to get metrics about the cluster from the 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.
 GetContainerReportResponse getContainerReport(GetContainerReportRequest request)
           The interface used by clients to get a report of an Container from the ResourceManager
 GetContainersResponse getContainers(GetContainersRequest request)
           The interface used by clients to get a report of Containers for an application attempt from the ResourceManager
 GetDelegationTokenResponse getDelegationToken(GetDelegationTokenRequest request)
          The interface used by clients to get delegation token, enabling the containers to be able to talk to the service using those tokens.
 GetNewApplicationResponse getNewApplication(GetNewApplicationRequest request)
          The interface used by clients to obtain a new ApplicationId for submitting new applications.
 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.
 MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues(MoveApplicationAcrossQueuesRequest request)
          Move an application to a new queue.
 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.
 ReservationUpdateResponse updateReservation(ReservationUpdateRequest request)
           The interface used by clients to update an existing Reservation.
 

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 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 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 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
org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException - The exception is thrown when a ResourceRequest is out of the range of the configured lower and upper resource boundaries.
See Also:
getNewApplication(GetNewApplicationRequest)

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)

getApplicationReport

@InterfaceAudience.Public
@InterfaceStability.Stable
GetApplicationReportResponse getApplicationReport(GetApplicationReportRequest request)
                                                  throws YarnException,
                                                         IOException

The interface used by clients to get a report of an Application from the ResourceManager.

The client, via GetApplicationReportRequest provides the ApplicationId of the application.

In secure mode,the ResourceManager verifies access to the application, queue etc. before accepting the request.

The ResourceManager responds with a GetApplicationReportResponse which includes the ApplicationReport for the application.

If the user does not have VIEW_APP access then the following fields in the report will be set to stubbed values:

Parameters:
request - request for an application report
Returns:
application report
Throws:
YarnException
IOException

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

getApplications

@InterfaceAudience.Public
@InterfaceStability.Stable
GetApplicationsResponse getApplications(GetApplicationsRequest request)
                                        throws YarnException,
                                               IOException

The interface used by clients to get a report of Applications matching the filters defined by GetApplicationsRequest in the cluster from the ResourceManager.

The ResourceManager responds with a GetApplicationsResponse which includes the ApplicationReport for the applications.

If the user does not have VIEW_APP access for an application then the corresponding report will be filtered as described in getApplicationReport(GetApplicationReportRequest).

Parameters:
request - request for report on applications
Returns:
report on applications matching the given application types defined in the request
Throws:
YarnException
IOException
See Also:
GetApplicationsRequest

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

getDelegationToken

@InterfaceAudience.Public
@InterfaceStability.Stable
GetDelegationTokenResponse getDelegationToken(GetDelegationTokenRequest request)
                                              throws YarnException,
                                                     IOException

The interface used by clients to get delegation token, enabling the containers to be able to talk to the service using those tokens.

The ResourceManager responds with the delegation Token that can be used by the client to speak to this service.

Parameters:
request - request to get a delegation token for the client.
Returns:
delegation token that can be used to talk to this service
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

getApplicationAttemptReport

@InterfaceAudience.Public
@InterfaceStability.Unstable
GetApplicationAttemptReportResponse getApplicationAttemptReport(GetApplicationAttemptReportRequest request)
                                                                throws YarnException,
                                                                       IOException

The interface used by clients to get a report of an Application Attempt from the ResourceManager

The client, via GetApplicationAttemptReportRequest provides the ApplicationAttemptId of the application attempt.

In secure mode,the ResourceManager verifies access to the method before accepting the request.

The ResourceManager responds with a GetApplicationAttemptReportResponse which includes the ApplicationAttemptReport for the application attempt.

If the user does not have VIEW_APP access then the following fields in the report will be set to stubbed values:

Parameters:
request - request for an application attempt report
Returns:
application attempt report
Throws:
YarnException
IOException

getApplicationAttempts

@InterfaceAudience.Public
@InterfaceStability.Unstable
GetApplicationAttemptsResponse getApplicationAttempts(GetApplicationAttemptsRequest request)
                                                      throws YarnException,
                                                             IOException

The interface used by clients to get a report of all Application attempts in the cluster from the ResourceManager

The ResourceManager responds with a GetApplicationAttemptsRequest which includes the ApplicationAttemptReport for all the applications attempts of a specified application attempt.

If the user does not have VIEW_APP access for an application then the corresponding report will be filtered as described in getApplicationAttemptReport(GetApplicationAttemptReportRequest).

Parameters:
request - request for reports on all application attempts of an application
Returns:
reports on all application attempts of an application
Throws:
YarnException
IOException

getContainerReport

@InterfaceAudience.Public
@InterfaceStability.Unstable
GetContainerReportResponse getContainerReport(GetContainerReportRequest request)
                                              throws YarnException,
                                                     IOException

The interface used by clients to get a report of an Container from the ResourceManager

The client, via GetContainerReportRequest provides the ContainerId of the container.

In secure mode,the ResourceManager verifies access to the method before accepting the request.

The ResourceManager responds with a GetContainerReportResponse which includes the ContainerReport for the container.

Parameters:
request - request for a container report
Returns:
container report
Throws:
YarnException
IOException

getContainers

@InterfaceAudience.Public
@InterfaceStability.Unstable
GetContainersResponse getContainers(GetContainersRequest request)
                                    throws YarnException,
                                           IOException

The interface used by clients to get a report of Containers for an application attempt from the ResourceManager

The client, via GetContainersRequest provides the ApplicationAttemptId of the application attempt.

In secure mode,the ResourceManager verifies access to the method before accepting the request.

The ResourceManager responds with a GetContainersResponse which includes a list of ContainerReport for all the containers of a specific application attempt.

Parameters:
request - request for a list of container reports of an application attempt.
Returns:
reports on all containers of an application attempt
Throws:
YarnException
IOException

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

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

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


Copyright © 2014 Apache Software Foundation. All Rights Reserved.