Apache
/
hadoop
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

MAPREDUCE-3371. Review and improve the yarn-api javadocs. (Ravi Prakash via mahadev) - Merging r1206899 from trunk. 

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/branches/branch-0.23@1206909 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Mahadev Konar 2011-11-27 23:17:09 +00:00
parent 77b7c94aa0
commit f0c0a094ff
28 changed files with 141 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
hadoop-mapreduce-project/CHANGES.txt
View File

@ -53,6 +53,9 @@ Release 0.23.1 - Unreleased
MAPREDUCE-3411. Performance Upgrade for jQuery (Jonathan Eagles via
mahadev)
MAPREDUCE-3371. Review and improve the yarn-api javadocs. (Ravi Prakash
via mahadev)
OPTIMIZATIONS
BUG FIXES

4
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
View File

@ -91,8 +91,8 @@ public interface AMRMProtocol {
*
* <p>This also doubles up as a <em>heartbeat</em> to let the
* <code>ResourceManager</code> know that the <code>ApplicationMaster</code>
* is alive. Thus, applications should use periodically make this call to
* be kept alive.</p>
* is alive. Thus, applications should periodically make this call to be kept
* alive. The frequency depends on ??</p>
*
* <p>The <code>ResourceManager</code> responds with list of allocated
* {@link Container}, status of completed containers and headroom information

5
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
View File

@ -68,7 +68,8 @@ public interface ClientRMProtocol {
* {@link GetNewApplicationResponse}.</p>
*
* @param request request to get a new <code>ApplicationId</code>
* @return new <code>ApplicationId</code> to be used to submit an application
* @return response containing the new <code>ApplicationId</code> to be used
* to submit an application
* @throws YarnRemoteException
* @see #submitApplication(SubmitApplicationRequest)
*/
@ -216,7 +217,7 @@ public interface ClientRMProtocol {
/**
* <p>The interface used by clients to get information about <em>queue
* acls</em> for <em>current users</em> from the <code>ResourceManager</code>.
* acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
* </p>
*
* <p>The <code>ResourceManager</code> responds with queue acls for all

9
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java
View File

@ -79,7 +79,7 @@ public interface ContainerManager {
* to <em>stop</em> a {@link Container} allocated to it using this interface.
* </p>
*
* <p>The <code>ApplicationMaster</code></p> sends a
* <p>The <code>ApplicationMaster</code> sends a
* {@link StopContainerRequest} which includes the {@link ContainerId} of the
* container to be stopped.</p>
*
@ -105,8 +105,8 @@ public interface ContainerManager {
* current status of a <code>Container</code> from the
* <code>NodeManager</code>.</p>
*
* <p>The <code>ApplicationMaster</code></p> sends a
* {@link GetContainerStatusRequest} which includes the {@link ContainerId} of
* <p>The <code>ApplicationMaster</code> sends a
* {@link GetContainerStatusRequest} which includes the {@link ContainerId} of
* the container whose status is needed.</p>
*
*<p>The <code>NodeManager</code> responds with
@ -115,7 +115,8 @@ public interface ContainerManager {
*
* @param request request to get <code>ContainerStatus</code> of a container
* with the specified <code>ContainerId</code>
* @return <code>ContainerStatus</code> of the container
* @return response containing the <code>ContainerStatus</code> of the
* container
* @throws YarnRemoteException
*/
@Public

11
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
View File

@ -50,7 +50,6 @@ import org.apache.hadoop.yarn.api.records.ResourceRequest;
* <li>
* A list of unused {@link Container} which are being returned.
* </li>
* <li></li>
* </ul>
* </p>
*
@ -81,7 +80,7 @@ public interface AllocateRequest {
void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
/**
* Get the <em>response id</em>.
* Get the <em>response id</em> used to track duplicate responses.
* @return <em>response id</em>
*/
@Public
@ -89,7 +88,7 @@ public interface AllocateRequest {
int getResponseId();
/**
* Set the <em>response id</em>
* Set the <em>response id</em> used to track duplicate responses.
* @param id <em>response id</em>
*/
@Public
@ -113,7 +112,7 @@ public interface AllocateRequest {
void setProgress(float progress);
/**
* Get the list of <code>ResourceRequest</code> to upate the
* Get the list of <code>ResourceRequest</code> to update the
* <code>ResourceManager</code> about the application's resource requirements.
* @return the list of <code>ResourceRequest</code>
*/
@ -130,9 +129,9 @@ public interface AllocateRequest {
int getAskCount();
/**
* Add list of <code>ResourceRequest</code> to upate the
* Add list of <code>ResourceRequest</code> to update the
* <code>ResourceManager</code> about the application's resource requirements.
* @param resourceRequest list of <code>ResourceRequest</code> to upate the
* @param resourceRequest list of <code>ResourceRequest</code> to update the
* <code>ResourceManager</code> about the application's
* resource requirements
*/

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
View File

@ -34,7 +34,7 @@ import org.apache.hadoop.yarn.api.records.Container;
* <ul>
* <li>Response ID to track duplicate responses.</li>
* <li>
* A reboot flag to let the <code>ApplicationMaster</code> that its
* A reboot flag to let the <code>ApplicationMaster</code> know that its
* horribly out of sync and needs to reboot.</li>
* <li>A list of newly allocated {@link Container}.</li>
* <li>A list of completed {@link Container}.</li>

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsRequest.java
View File

@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
* <p>The request from clients to get a report of all Applications
* in the cluster from the <code>ResourceManager</code>.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ClientRMProtocol#getAllApplications(GetAllApplicationsRequest)
*/
@Public

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsRequest.java
View File

@ -25,6 +25,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
/**
* <p>The request sent by clients to get cluster metrics from the
* <code>ResourceManager</code>.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ClientRMProtocol#getClusterMetrics(GetClusterMetricsRequest)
*/

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesRequest.java
View File

@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
* <p>The request from clients to get a report of all nodes
* in the cluster from the <code>ResourceManager</code>.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ClientRMProtocol#getClusterNodes(GetClusterNodesRequest)
*/
@Public

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesResponse.java
View File

@ -29,7 +29,7 @@ import org.apache.hadoop.yarn.api.records.NodeReport;
/**
* <p>The response sent by the <code>ResourceManager</code> to a client
* requesting an {@link NodeReport} for all nodes.</p>
* requesting a {@link NodeReport} for all nodes.</p>
*
* <p>The <code>NodeReport</code> contains per-node information such as
* available resources, number of containers, tracking url, rack name, health

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java
View File

@ -27,7 +27,7 @@ import org.apache.hadoop.yarn.api.records.ContainerStatus;
/**
* <p>The response sent by the <code>NodeManager</code> to the
* <code>ApplicationMaster</code> when asked to obtainer <em>status</em>
* <code>ApplicationMaster</code> when asked to obtain the <em>status</em>
* of a container.</p>
*
* @see ContainerManager#getContainerStatus(GetContainerStatusRequest)

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationRequest.java
View File

@ -27,6 +27,8 @@ import org.apache.hadoop.yarn.api.records.ApplicationId;
* <p>The request sent by clients to get a new {@link ApplicationId} for
* submitting an application.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ClientRMProtocol#getNewApplication(GetNewApplicationRequest)
*/
@Public

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationResponse.java
View File

@ -28,7 +28,7 @@ import org.apache.hadoop.yarn.api.records.Resource;
/**
* <p>The response sent by the <code>ResourceManager</code> to the client for
* a request to a new {@link ApplicationId} for submitting applications.</p>
* a request to get a new {@link ApplicationId} for submitting applications.</p>
*
* @see ClientRMProtocol#getNewApplication(GetNewApplicationRequest)
*/

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoRequest.java
View File

@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
* <p>The request sent by clients to the <code>ResourceManager</code> to
* get queue acls for the <em>current user</em>.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ClientRMProtocol#getQueueUserAcls(GetQueueUserAclsInfoRequest)
*/
@Public

42
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java
View File

@ -35,11 +35,53 @@ import org.apache.hadoop.yarn.api.ContainerManager;
@Public
@Stable
public interface StartContainerResponse {
/**
* <p>Get the responses from all auxiliary services running on the
* <code>NodeManager</code>.</p>
* <p>The responses are returned as a Map between the auxiliary service names
* and their corresponding opaque blob <code>ByteBuffer</code>s</p>
* @return a Map between the auxiliary service names and their outputs
*/
Map<String, ByteBuffer> getAllServiceResponse();
/**
* Get the response from a single auxiliary service running on the
* <code>NodeManager</code>
*
* @param key The auxiliary service name whose response is desired.
* @return The opaque blob <code>ByteBuffer</code> returned by the auxiliary
* service.
*/
ByteBuffer getServiceResponse(String key);
/**
* Add to the list of auxiliary services which have been started on the
* <code>NodeManager</code>. This is done only once when the
* <code>NodeManager</code> starts up
* @param serviceResponse A map from auxiliary service names to the opaque
* blob <code>ByteBuffer</code>s for that auxiliary service
*/
void addAllServiceResponse(Map<String, ByteBuffer> serviceResponse);
/**
* Add to the list of auxiliary services which have been started on the
* <code>NodeManager</code>. This is done only once when the
* <code>NodeManager</code> starts up
*
* @param key The auxiliary service name
* @param value The opaque blob <code>ByteBuffer</code> managed by the
* auxiliary service
*/
void setServiceResponse(String key, ByteBuffer value);
/**
* Remove a single auxiliary service from the StartContainerResponse object
* @param key The auxiliary service to remove
*/
void removeServiceResponse(String key);
/**
* Remove all the auxiliary services from the StartContainerResponse object
*/
void clearServiceResponse();
}

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java
View File

@ -27,6 +27,8 @@ import org.apache.hadoop.yarn.api.ContainerManager;
* <code>ApplicationMaster</code> when asked to <em>stop</em> an
* allocated container.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ContainerManager#stopContainer(StopContainerRequest)
*/
@Public

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationResponse.java
View File

@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
* <p>The response sent by the <code>ResourceManager</code> to a client on
* application submission.</p>
*
* <p>Currently, this is empty.</p>
*
* @see ClientRMProtocol#submitApplication(SubmitApplicationRequest)
*/
@Public

4
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
View File

@ -35,7 +35,7 @@ import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest;
* <ul>
* <li>Response ID to track duplicate responses.</li>
* <li>
* A reboot flag to let the <code>ApplicationMaster</code> that its
* A reboot flag to let the <code>ApplicationMaster</code> know that its
* horribly out of sync and needs to reboot.</li>
* <li>A list of newly allocated {@link Container}.</li>
* <li>A list of completed {@link Container}.</li>
@ -100,7 +100,7 @@ public interface AMResponse {
/**
* Get the <em>available headroom</em> for resources in the cluster for the
* application.
* @return limit available headroom for resources in the cluster for the
* @return limit of available headroom for resources in the cluster for the
* application
*/
@Public

3
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationReport.java
View File

@ -33,7 +33,7 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
* <li>Applications user.</li>
* <li>Application queue.</li>
* <li>Application name.</li>
* <li>Host on which the <code>ApplicationMaster</code>is running.</li>
* <li>Host on which the <code>ApplicationMaster</code> is running.</li>
* <li>RPC port of the <code>ApplicationMaster</code>.</li>
* <li>Tracking URL.</li>
* <li>{@link YarnApplicationState} of the application.</li>
@ -215,6 +215,7 @@ public interface ApplicationReport {
/**
* Get the <em>final finish status</em> of the application.
* @return <em>final finish status</em> of the application
*/
@Public
@Stable

29
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationResourceUsageReport.java
View File

@ -33,22 +33,43 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
@Public
@Stable
public interface ApplicationResourceUsageReport {
/**
* Get the number of used containers
* @return the number of used containers
*/
@Public
@Stable
int getNumUsedContainers();
/**
* Set the number of used containers
* @param num_containers the number of used containers
*/
@Private
@Unstable
void setNumUsedContainers(int num_containers);
/**
* Get the number of reserved containers
* @return the number of reserved containers
*/
@Public
@Stable
int getNumReservedContainers();
/**
* Set the number of reserved containers
* @param num_reserved_containers the number of reserved containers
*/
@Private
@Unstable
void setNumReservedContainers(int num_reserved_containers);
/**
* Get the used <code>Resource</code>
* @return the used <code>Resource</code>
*/
@Public
@Stable
Resource getUsedResources();
@ -57,6 +78,10 @@ public interface ApplicationResourceUsageReport {
@Unstable
void setUsedResources(Resource resources);
/**
* Get the reserved <code>Resource</code>
* @return the reserved <code>Resource</code>
*/
@Public
@Stable
Resource getReservedResources();
@ -65,6 +90,10 @@ public interface ApplicationResourceUsageReport {
@Unstable
void setReservedResources(Resource reserved_resources);
/**
* Get the needed <code>Resource</code>
* @return the needed <code>Resource</code>
*/
@Public
@Stable
Resource getNeededResources();

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationSubmissionContext.java
View File

@ -26,7 +26,7 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
import org.apache.hadoop.yarn.api.ClientRMProtocol;
/**
* <p><code>ApplicationSubmissionContext</code> represents the all of the
* <p><code>ApplicationSubmissionContext</code> represents all of the
* information needed by the <code>ResourceManager</code> to launch
* the <code>ApplicationMaster</code> for an application.</p>
*

3
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Container.java
View File

@ -38,8 +38,7 @@ import org.apache.hadoop.yarn.api.ContainerManager;
* <ul>
* <li>{@link ContainerId} for the container, which is globally unique.</li>
* <li>
* {@link NodeId} of the node on which identifies the node on which it
* is allocated.
* {@link NodeId} of the node on which it is allocated.
* </li>
* <li>HTTP uri of the node.</li>
* <li>{@link Resource} allocated to the container.</li>

19
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java
View File

@ -27,7 +27,7 @@ import org.apache.hadoop.classification.InterfaceStability.Stable;
import org.apache.hadoop.yarn.api.ContainerManager;
/**
* <p><code>ContainerLaunchContext</code> represents the all of the information
* <p><code>ContainerLaunchContext</code> represents all of the information
* needed by the <code>NodeManager</code> to launch a container.</p>
*
* <p>It includes details such as:
@ -127,7 +127,8 @@ public interface ContainerLaunchContext {
Map<String, LocalResource> getLocalResources();
/**
* Set <code>LocalResource</code> required by the container.
* Set <code>LocalResource</code> required by the container. All pre-existing
* Map entries are cleared before adding the new Map
* @param localResources <code>LocalResource</code> required by the container
*/
@Public
@ -143,7 +144,8 @@ public interface ContainerLaunchContext {
Map<String, ByteBuffer> getServiceData();
/**
* Set application-specific binary <em>service data</em>.
* Set application-specific binary <em>service data</em>. All pre-existing Map
* entries are preserved.
* @param serviceData application-specific binary <em>service data</em>
*/
@Public
@ -159,7 +161,8 @@ public interface ContainerLaunchContext {
Map<String, String> getEnvironment();
/**
* Add <em>environment variables</em> for the container.
* Add <em>environment variables</em> for the container. All pre-existing Map
* entries are cleared before adding the new Map
* @param environment <em>environment variables</em> for the container
*/
@Public
@ -175,7 +178,8 @@ public interface ContainerLaunchContext {
List<String> getCommands();
/**
* Add the list of <em>commands</em> for launching the container.
* Add the list of <em>commands</em> for launching the container. All
* pre-existing List entries are cleared before adding the new List
* @param commands the list of <em>commands</em> for launching the container
*/
@Public
@ -191,8 +195,9 @@ public interface ContainerLaunchContext {
public Map<ApplicationAccessType, String> getApplicationACLs();
/**
* Set the <code>ApplicationACL</code>s for the application.
* @param acls
* Set the <code>ApplicationACL</code>s for the application. All pre-existing
* Map entries are cleared before adding the new Map
* @param acls <code>ApplicationACL</code>s for the application
*/
@Public
@Stable

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeHealthStatus.java
View File

@ -35,8 +35,6 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
* </li>
* <li>The previous time at which the health status was reported.</li>
* <li>A diagnostic report on the health status.</li>
* <li></li>
* <li></li>
* </ul>
* </p>
*

13
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Priority.java
View File

@ -18,10 +18,23 @@
package org.apache.hadoop.yarn.api.records;
/**
* The priority assigned to a ResourceRequest or Application or Container
* allocation
*
*/
public interface Priority extends Comparable<Priority> {
/**
* Get the assigned priority
* @return the assigned priority
*/
public abstract int getPriority();
/**
* Set the assigned priority
* @param priority the assigned priority
*/
public abstract void setPriority(int priority);
}

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueInfo.java
View File

@ -27,7 +27,7 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
import org.apache.hadoop.yarn.api.ClientRMProtocol;
/**
* <p>QueueInfo</p> is a report of the runtime information of the queue.</p>
* <p>QueueInfo is a report of the runtime information of the queue.</p>
*
* <p>It includes information such as:
* <ul>

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-applications/hadoop-yarn-applications-distributedshell/src/main/java/org/apache/hadoop/yarn/applications/distributedshell/ApplicationMaster.java
View File

@ -93,7 +93,7 @@ import org.apache.hadoop.yarn.util.Records;
* to inform the <code>ResourceManager</code> that it is up and alive. The {@link AMRMProtocol#allocate} to the
* <code>ResourceManager</code> from the <code>ApplicationMaster</code> acts as a heartbeat.
*
* <p> For the actual handling of the job, the <code>ApplicationMaster</code> has to request for the
* <p> For the actual handling of the job, the <code>ApplicationMaster</code> has to request the
* <code>ResourceManager</code> via {@link AllocateRequest} for the required no. of containers using {@link ResourceRequest}
* with the necessary resource specifications such as node location, computational (memory/disk/cpu) resource requirements.
* The <code>ResourceManager</code> responds with an {@link AllocateResponse} that informs the <code>ApplicationMaster</code>

2
hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/AuxServices.java
View File

@ -68,7 +68,7 @@ public class AuxServices extends AbstractService
/**
* @return the meta data for all registered services, that have been started.
* If a service has not been started no metadata will be available. The key
* the the name of the service as defined in the configuration.
* is the name of the service as defined in the configuration.
*/
public Map<String, ByteBuffer> getMeta() {
Map<String, ByteBuffer> metaClone = new HashMap<String, ByteBuffer>(