From b9259a271031eadad518ba7568cc090bcbfc9033 Mon Sep 17 00:00:00 2001 From: Arun Murthy Date: Mon, 29 Aug 2011 00:04:06 +0000 Subject: [PATCH] MAPREDUCE-2898. Javadoc for ContainerManager protocol and related records. git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@1162613 13f79535-47bb-0310-9956-ffa450edef68 --- hadoop-mapreduce-project/CHANGES.txt | 3 + .../hadoop/yarn/api/ContainerManager.java | 86 ++++++++ .../GetContainerStatusRequest.java | 24 +++ .../GetContainerStatusResponse.java | 22 ++ .../StartContainerRequest.java | 30 +++ .../StartContainerResponse.java | 12 ++ .../protocolrecords/StopContainerRequest.java | 21 ++ .../StopContainerResponse.java | 12 ++ .../api/records/ContainerLaunchContext.java | 203 +++++++++++++++--- 9 files changed, 389 insertions(+), 24 deletions(-) diff --git a/hadoop-mapreduce-project/CHANGES.txt b/hadoop-mapreduce-project/CHANGES.txt index 04600ddfd3c..bdc9d3eb602 100644 --- a/hadoop-mapreduce-project/CHANGES.txt +++ b/hadoop-mapreduce-project/CHANGES.txt @@ -1160,6 +1160,9 @@ Release 0.23.0 - Unreleased MAPREDUCE-2891. Javadoc for AMRMProtocol and related records. (acmurthy) + MAPREDUCE-2898. Javadoc for ContainerManager protocol and related records. + (acmurthy) + Release 0.22.0 - Unreleased INCOMPATIBLE CHANGES diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java index a778793992a..46071929aee 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java @@ -18,21 +18,107 @@ package org.apache.hadoop.yarn.api; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusRequest; import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusResponse; import org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest; import org.apache.hadoop.yarn.api.protocolrecords.StartContainerResponse; import org.apache.hadoop.yarn.api.protocolrecords.StopContainerRequest; import org.apache.hadoop.yarn.api.protocolrecords.StopContainerResponse; +import org.apache.hadoop.yarn.api.records.ContainerId; +import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; +import org.apache.hadoop.yarn.api.records.ContainerStatus; import org.apache.hadoop.yarn.exceptions.YarnRemoteException; +/** + *

The protocol between an ApplicationMaster and a + * NodeManager to start/stop containers and to get status + * of running containers.

+ * + *

If security is enabled the NodeManager verifies that the + * ApplicationMaster has truly been allocated the container + * by the ResourceManager and also verifies all interactions such + * as stopping the container or obtaining status information for the container. + *

+ */ +@Public +@Stable public interface ContainerManager { + /** + *

The ApplicationMaster requests a NodeManager + * to start a {@link Container} allocated to it using this interface. + *

+ * + *

The ApplicationMaster has to provide details such as + * allocated resource capability, security tokens (if enabled), command + * to be executed to start the container, environment for the process, + * necessary binaries/jar/shared-objects etc. via the + * {@link ContainerLaunchContext} in the {@link StartContainerRequest}.

+ * + *

Currently the NodeManager sends an immediate, empty + * response via {@link StartContainerResponse} to signify acceptance of the + * request and throws an exception in case of errors. The + * ApplicationMaster can use + * {@link #getContainerStatus(GetContainerStatusRequest)} to get updated + * status of the to-be-launched or launched container.

+ * + * @param request request to start a container + * @return empty response to indicate acceptance of the request + * or an exception + * @throws YarnRemoteException + */ + @Public + @Stable StartContainerResponse startContainer(StartContainerRequest request) throws YarnRemoteException; + /** + *

The ApplicationMaster requests a NodeManager + * to stop a {@link Container} allocated to it using this interface. + *

+ * + *

The ApplicationMaster

sends a + * {@link StopContainerRequest} which includes the {@link ContainerId} of the + * container to be stopped.

+ * + *

Currently the NodeManager sends an immediate, empty + * response via {@link StopContainerResponse} to signify acceptance of the + * request and throws an exception in case of errors. The + * ApplicationMaster can use + * {@link #getContainerStatus(GetContainerStatusRequest)} to get updated + * status of the container.

+ * + * @param request request to stop a container + * @return empty response to indicate acceptance of the request + * or an exception + * @throws YarnRemoteException + */ + @Public + @Stable StopContainerResponse stopContainer(StopContainerRequest request) throws YarnRemoteException; + /** + *

The api used by the ApplicationMaster to request for + * current status of a Container from the + * NodeManager.

+ * + *

The ApplicationMaster

sends a + * {@link GetContainerStatusRequest} which includes the {@link ContainerId} of + * the container whose status is needed.

+ * + *

The NodeManager responds with + *{@link GetContainerStatusResponse} which includes the + *{@link ContainerStatus} of the container.

+ * + * @param request request to get ContainerStatus of a container + * with the specified ContainerId + * @return + * @throws YarnRemoteException + */ + @Public + @Stable GetContainerStatusResponse getContainerStatus( GetContainerStatusRequest request) throws YarnRemoteException; } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusRequest.java index c9498b0d67e..61b0aa7f087 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusRequest.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusRequest.java @@ -18,9 +18,33 @@ package org.apache.hadoop.yarn.api.protocolrecords; +import org.apache.hadoop.classification.InterfaceAudience.Private; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.classification.InterfaceStability.Unstable; +import org.apache.hadoop.yarn.api.ContainerManager; import org.apache.hadoop.yarn.api.records.ContainerId; +import org.apache.hadoop.yarn.api.records.ContainerStatus; +/** + *

The request sent by the ApplicationMaster to the + * NodeManager to get {@link ContainerStatus} of a container via + * {@link ContainerManager#getContainerStatus(GetContainerStatusRequest)}.

+ */ +@Public +@Stable public interface GetContainerStatusRequest { + /** + * Get the ContainerId of container for which to obtain the + * ContainerStatus. + * @return ContainerId of container for which to obtain the + * ContainerStatus + */ + @Public + @Stable public abstract ContainerId getContainerId(); + + @Private + @Unstable public abstract void setContainerId(ContainerId containerId); } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java index bcf0ffd99a2..7893c733a60 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java @@ -18,9 +18,31 @@ package org.apache.hadoop.yarn.api.protocolrecords; +import org.apache.hadoop.classification.InterfaceAudience.Private; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.classification.InterfaceStability.Unstable; +import org.apache.hadoop.yarn.api.ContainerManager; import org.apache.hadoop.yarn.api.records.ContainerStatus; +/** + *

The response sent by the NodeManager to the + * ApplicationMaster when asked to obtainer status + * of a container via + * {@link ContainerManager#getContainerStatus(GetContainerStatusRequest)}.

+ */ +@Public +@Stable public interface GetContainerStatusResponse { + /** + * Get the ContainerStatus of the container. + * @return ContainerStatus of the container + */ + @Public + @Stable public abstract ContainerStatus getStatus(); + + @Private + @Unstable public abstract void setStatus(ContainerStatus containerStatus); } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerRequest.java index 1226c91a2a3..0f986442b57 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerRequest.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerRequest.java @@ -18,10 +18,40 @@ package org.apache.hadoop.yarn.api.protocolrecords; +import org.apache.hadoop.classification.InterfaceAudience.Private; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.classification.InterfaceStability.Unstable; +import org.apache.hadoop.yarn.api.ContainerManager; import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; +/** + *

The request sent by the ApplicationMaster to the + * NodeManager to start a container via + * {@link ContainerManager#startContainer(StartContainerRequest)}.

+ * + *

The ApplicationMaster has to provide details such as + * allocated resource capability, security tokens (if enabled), command + * to be executed to start the container, environment for the process, + * necessary binaries/jar/shared-objects etc. via the + * {@link ContainerLaunchContext}.

+ * + */ +@Public +@Stable public interface StartContainerRequest { + /** + * Get the ContainerLaunchContext for the container to be started + * by the NodeManager. + * + * @return ContainerLaunchContext for the container to be started + * by the NodeManager + */ + @Public + @Stable public abstract ContainerLaunchContext getContainerLaunchContext(); + @Private + @Unstable public abstract void setContainerLaunchContext(ContainerLaunchContext context); } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java index 7153d199853..ffbdbc9ee1a 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java @@ -18,6 +18,18 @@ package org.apache.hadoop.yarn.api.protocolrecords; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.yarn.api.ContainerManager; + +/** + *

The response sent by the NodeManager to the + * ApplicationMaster when asked to start an + * allocated container via + * {@link ContainerManager#startContainer(StartContainerRequest)}.

+ */ +@Public +@Stable public interface StartContainerResponse { } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerRequest.java index 0debb28b670..bb538137938 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerRequest.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerRequest.java @@ -18,9 +18,30 @@ package org.apache.hadoop.yarn.api.protocolrecords; +import org.apache.hadoop.classification.InterfaceAudience.Private; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.classification.InterfaceStability.Unstable; +import org.apache.hadoop.yarn.api.ContainerManager; import org.apache.hadoop.yarn.api.records.ContainerId; +/** + *

The request sent by the ApplicationMaster to the + * NodeManager to stop a container via + * {@link ContainerManager#stopContainer(StopContainerRequest)}.

+ */ +@Public +@Stable public interface StopContainerRequest { + /** + * Get the ContainerId of the container to be stopped. + * @return ContainerId of container to be stopped + */ + @Public + @Stable ContainerId getContainerId(); + + @Private + @Unstable void setContainerId(ContainerId containerId); } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java index ffbdd8a246b..6b59ae66703 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java @@ -18,6 +18,18 @@ package org.apache.hadoop.yarn.api.protocolrecords; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.yarn.api.ContainerManager; + +/** + *

The response sent by the NodeManager to the + * ApplicationMaster when asked to stop an + * allocated container via + * {@link ContainerManager#stopContainer(StopContainerRequest)}.

+ */ +@Public +@Stable public interface StopContainerResponse { } diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java index f9a7a179805..0921b926f28 100644 --- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java +++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java @@ -22,50 +22,205 @@ import java.nio.ByteBuffer; import java.util.List; import java.util.Map; +import org.apache.hadoop.classification.InterfaceAudience.Private; +import org.apache.hadoop.classification.InterfaceAudience.Public; +import org.apache.hadoop.classification.InterfaceStability.Stable; +import org.apache.hadoop.classification.InterfaceStability.Unstable; + +/** + *

ContainerLaunchContext represents the all of the information + * needed by the NodeManager to launch a container.

+ * + *

It includes details such as: + *

+ *

+ */ +@Public +@Stable public interface ContainerLaunchContext { + /** + * Get ContainerId of container to be launched. + * @return ContainerId of container to be launched + */ + @Public + @Stable ContainerId getContainerId(); + + @Private + @Unstable + void setContainerId(ContainerId containerId); + + /** + * Get the user to whom the container has been allocated. + * @return the user to whom the container has been allocated + */ + @Public + @Stable String getUser(); + + @Private + @Unstable + void setUser(String user); + + /** + * Get the Resource allocated to the container by the + * ResourceManager. + * @return Resource allocated to the container by the + * ResourceManager + */ + @Public + @Stable Resource getResource(); + @Private + @Unstable + void setResource(Resource resource); + + /** + * Get security tokens (if security is enabled). + * @return security tokens (if security is enabled) + */ + @Public + @Stable + ByteBuffer getContainerTokens(); + + @Private + @Unstable + void setContainerTokens(ByteBuffer containerToken); + + /** + * Get all LocalResource required by the container. + * @return all LocalResource required by the container + */ + @Public + @Stable Map getAllLocalResources(); + + @Private + @Unstable LocalResource getLocalResource(String key); - - ByteBuffer getContainerTokens(); - + @Private + @Unstable + void addAllLocalResources(Map localResources); + + @Private + @Unstable + void setLocalResource(String key, LocalResource value); + + @Private + @Unstable + void removeLocalResource(String key); + + @Private + @Unstable + void clearLocalResources(); + + /** + * Get application-specific binary service data. + * @return application-specific binary service data + */ + @Public + @Stable Map getAllServiceData(); + + @Private + @Unstable ByteBuffer getServiceData(String key); + @Private + @Unstable + void addAllServiceData(Map serviceData); + + @Private + @Unstable + void setServiceData(String key, ByteBuffer value); + + @Private + @Unstable + void removeServiceData(String key); + + @Private + @Unstable + void clearServiceData(); + + /** + * Get environment variables for the launched container. + * @return environment variables for the launched container + */ + @Public + @Stable Map getAllEnv(); + + @Private + @Unstable String getEnv(String key); + @Private + @Unstable + void addAllEnv(Map env); + + @Private + @Unstable + void setEnv(String key, String value); + + @Private + @Unstable + void removeEnv(String key); + + @Private + @Unstable + void clearEnv(); + + /** + * Get the list of commands for launching the container. + * @return the list of commands for launching the container + */ + @Public + @Stable List getCommandList(); + + @Private + @Unstable String getCommand(int index); + + @Private + @Unstable int getCommandCount(); - void setContainerId(ContainerId containerId); - void setUser(String user); - void setResource(Resource resource); - - void addAllLocalResources(Map localResources); - void setLocalResource(String key, LocalResource value); - void removeLocalResource(String key); - void clearLocalResources(); - - void setContainerTokens(ByteBuffer containerToken); - - void addAllServiceData(Map serviceData); - void setServiceData(String key, ByteBuffer value); - void removeServiceData(String key); - void clearServiceData(); - - void addAllEnv(Map env); - void setEnv(String key, String value); - void removeEnv(String key); - void clearEnv(); - + @Private + @Unstable void addAllCommands(List commands); + + @Private + @Unstable void addCommand(String command); + + @Private + @Unstable void removeCommand(int index); + + @Private + @Unstable void clearCommands(); }