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

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

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;
 
+/**
+ * <p>The protocol between an <code>ApplicationMaster</code> and a 
+ * <code>NodeManager</code> to start/stop containers and to get status
+ * of running containers.</p>
+ * 
+ * <p>If security is enabled the <code>NodeManager</code> verifies that the
+ * <code>ApplicationMaster</code> has truly been allocated the container
+ * by the <code>ResourceManager</code> and also verifies all interactions such 
+ * as stopping the container or obtaining status information for the container.
+ * </p>
+ */
+@Public
+@Stable
 public interface ContainerManager {
+  /**
+   * <p>The <code>ApplicationMaster</code> requests a <code>NodeManager</code>
+   * to <em>start</em> a {@link Container} allocated to it using this interface.
+   * </p>
+   * 
+   * <p>The <code>ApplicationMaster</code> 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}.</p>
+   * 
+   * <p>Currently the <code>NodeManager</code> sends an immediate, empty 
+   * response via {@link StartContainerResponse} to signify acceptance of the
+   * request and throws an exception in case of errors. The 
+   * <code>ApplicationMaster</code> can use 
+   * {@link #getContainerStatus(GetContainerStatusRequest)} to get updated 
+   * status of the to-be-launched or launched container.</p>
+   * 
+   * @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;
 
+  /**
+   * <p>The <code>ApplicationMaster</code> requests a <code>NodeManager</code>
+   * to <em>stop</em> a {@link Container} allocated to it using this interface.
+   * </p>
+   * 
+   * <p>The <code>ApplicationMaster</code></p> sends a 
+   * {@link StopContainerRequest} which includes the {@link ContainerId} of the
+   * container to be stopped.</p>
+   * 
+   * <p>Currently the <code>NodeManager</code> sends an immediate, empty 
+   * response via {@link StopContainerResponse} to signify acceptance of the
+   * request and throws an exception in case of errors. The 
+   * <code>ApplicationMaster</code> can use 
+   * {@link #getContainerStatus(GetContainerStatusRequest)} to get updated 
+   * status of the container.</p>
+   * 
+   * @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;
 
+  /**
+   * <p>The api used by the <code>ApplicationMaster</code> to request for 
+   * 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 
+   * the container whose status is needed.</p>
+   *
+   *<p>The <code>NodeManager</code> responds with 
+   *{@link GetContainerStatusResponse} which includes the 
+   *{@link ContainerStatus} of the container.</p>
+   *
+   * @param request request to get <code>ContainerStatus</code> of a container
+   *                with the specified <code>ContainerId</code>
+   * @return
+   * @throws YarnRemoteException
+   */
+  @Public
+  @Stable
   GetContainerStatusResponse getContainerStatus(
       GetContainerStatusRequest request) throws YarnRemoteException;
 }

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;
 
+/**
+ * <p>The request sent by the <code>ApplicationMaster</code> to the
+ * <code>NodeManager</code> to get {@link ContainerStatus} of a container via
+ * {@link ContainerManager#getContainerStatus(GetContainerStatusRequest)}.</p>
+ */
+@Public
+@Stable
 public interface GetContainerStatusRequest {
+  /**
+   * Get the <code>ContainerId</code> of container for which to obtain the
+   * <code>ContainerStatus</code>.
+   * @return <code>ContainerId</code> of container for which to obtain the
+   *         <code>ContainerStatus</code>
+   */
+  @Public
+  @Stable
   public abstract ContainerId getContainerId();
+  
+  @Private
+  @Unstable
   public abstract void setContainerId(ContainerId containerId);
 }

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;
 
+/**
+ * <p>The response sent by the <code>NodeManager</code> to the 
+ * <code>ApplicationMaster</code> when asked to obtainer <em>status</em> 
+ * of a container via
+ * {@link ContainerManager#getContainerStatus(GetContainerStatusRequest)}.</p>
+ */
+@Public
+@Stable
 public interface GetContainerStatusResponse {
+  /**
+   * Get the <code>ContainerStatus</code> of the container.
+   * @return <code>ContainerStatus</code> of the container
+   */
+  @Public
+  @Stable
   public abstract ContainerStatus getStatus();
+  
+  @Private
+  @Unstable
   public abstract void setStatus(ContainerStatus containerStatus);
 }

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;
 
+/**
+ * <p>The request sent by the <code>ApplicationMaster</code> to the
+ * <code>NodeManager</code> to <em>start</em> a container via
+ * {@link ContainerManager#startContainer(StartContainerRequest)}.</p>
+ * 
+ * <p>The <code>ApplicationMaster</code> 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}.</p>
+ *
+ */
+@Public
+@Stable
 public interface StartContainerRequest {
+  /**
+   * Get the <code>ContainerLaunchContext</code> for the container to be started
+   * by the <code>NodeManager</code>.
+   * 
+   * @return <code>ContainerLaunchContext</code> for the container to be started
+   *         by the <code>NodeManager</code>
+   */
+  @Public
+  @Stable
   public abstract ContainerLaunchContext getContainerLaunchContext();
   
+  @Private
+  @Unstable
   public abstract void setContainerLaunchContext(ContainerLaunchContext context);
 }

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;
+
+/**
+ * <p>The response sent by the <code>NodeManager</code> to the 
+ * <code>ApplicationMaster</code> when asked to <em>start</em> an
+ * allocated container via
+ * {@link ContainerManager#startContainer(StartContainerRequest)}.</p>
+ */
+@Public
+@Stable
 public interface StartContainerResponse {
 
 }

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;
 
+/**
+ * <p>The request sent by the <code>ApplicationMaster</code> to the
+ * <code>NodeManager</code> to <em>stop</em> a container via
+ * {@link ContainerManager#stopContainer(StopContainerRequest)}.</p>
+ */
+@Public
+@Stable
 public interface StopContainerRequest {
+  /**
+   * Get the <code>ContainerId</code> of the container to be stopped.
+   * @return <code>ContainerId</code> of container to be stopped
+   */
+  @Public
+  @Stable
   ContainerId getContainerId();
+  
+  @Private
+  @Unstable
   void setContainerId(ContainerId containerId);
 }

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;
+
+/**
+ * <p>The response sent by the <code>NodeManager</code> to the 
+ * <code>ApplicationMaster</code> when asked to <em>stop</em> an
+ * allocated container via
+ * {@link ContainerManager#stopContainer(StopContainerRequest)}.</p>
+ */
+@Public
+@Stable
 public interface StopContainerResponse {
 
 }

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.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;
+
+/**
+ * <p><code>ContainerLaunchContext</code> represents the all of the information
+ * needed by the <code>NodeManager</code> to launch a container.</p>
+ * 
+ * <p>It includes details such as:
+ *   <ul>
+ *     <li>{@link ContainerId} of the container.</li>
+ *     <li>{@link Resource} allocated to the container.</li>
+ *     <li>User to whom the container is allocated.</li>
+ *     <li>Security tokens (if security is enabled).</li>
+ *     <li>
+ *       {@link LocalResource} necessary for running the container such
+ *       as binaries, jar, shared-objects, side-files etc. 
+ *     </li>
+ *     <li>Optional, application-specific binary service data.</li>
+ *     <li>Environment variables for the launched process.</li>
+ *     <li>Command to be executed to launch the container.</li>
+ *     <li></li>
+ *     <li></li>
+ *     <li></li>
+ *     <li></li>
+ *     <li></li>
+ *     <li></li>
+ *     <li></li>
+ *     <li></li>
+ *   </ul>
+ * </p>
+ */
+@Public
+@Stable
 public interface ContainerLaunchContext {
+  /**
+   * Get <code>ContainerId</code> of container to be launched.
+   * @return <code>ContainerId</code> of container to be launched
+   */
+  @Public
+  @Stable
   ContainerId getContainerId();
+
+  @Private
+  @Unstable
+  void setContainerId(ContainerId containerId);
+
+  /**
+   * Get the <em>user</em> to whom the container has been allocated.
+   * @return the <em>user</em> to whom the container has been allocated
+   */
+  @Public
+  @Stable
   String getUser();
+  
+  @Private
+  @Unstable
+  void setUser(String user);
+
+  /**
+   * Get the <code>Resource</code> allocated to the container by the
+   * <code>ResourceManager</code>.
+   * @return <code>Resource</code> allocated to the container by the
+   *         <code>ResourceManager</code>
+   */
+  @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 <code>LocalResource</code> required by the container.
+   * @return all <code>LocalResource</code> required by the container
+   */
+  @Public
+  @Stable
   Map<String, LocalResource> getAllLocalResources();
+  
+  @Private
+  @Unstable
   LocalResource getLocalResource(String key);
   
-  
-  ByteBuffer getContainerTokens();
-  
+  @Private
+  @Unstable
+  void addAllLocalResources(Map<String, LocalResource> 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<String, ByteBuffer> getAllServiceData();
+  
+  @Private
+  @Unstable
   ByteBuffer getServiceData(String key);
   
+  @Private
+  @Unstable
+  void addAllServiceData(Map<String, ByteBuffer> serviceData);
+
+  @Private
+  @Unstable
+  void setServiceData(String key, ByteBuffer value);
+
+  @Private
+  @Unstable
+  void removeServiceData(String key);
+
+  @Private
+  @Unstable
+  void clearServiceData();
+
+  /**
+   * Get <em>environment variables</em> for the launched container.
+   * @return <em>environment variables</em> for the launched container
+   */
+  @Public
+  @Stable
   Map<String, String> getAllEnv();
+  
+  @Private
+  @Unstable
   String getEnv(String key);
   
+  @Private
+  @Unstable
+  void addAllEnv(Map<String, String> env);
+
+  @Private
+  @Unstable
+  void setEnv(String key, String value);
+
+  @Private
+  @Unstable
+  void removeEnv(String key);
+
+  @Private
+  @Unstable
+  void clearEnv();
+
+  /**
+   * Get the list of <em>commands</em> for launching the container.
+   * @return the list of <em>commands</em> for launching the container
+   */
+  @Public
+  @Stable
   List<String> 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<String, LocalResource> localResources);
-  void setLocalResource(String key, LocalResource value);
-  void removeLocalResource(String key);
-  void clearLocalResources();
-  
-  void setContainerTokens(ByteBuffer containerToken);
-  
-  void addAllServiceData(Map<String, ByteBuffer> serviceData);
-  void setServiceData(String key, ByteBuffer value);
-  void removeServiceData(String key);
-  void clearServiceData();
-  
-  void addAllEnv(Map<String, String> env);
-  void setEnv(String key, String value);
-  void removeEnv(String key);
-  void clearEnv();
-  
+  @Private
+  @Unstable
   void addAllCommands(List<String> commands);
+  
+  @Private
+  @Unstable
   void addCommand(String command);
+  
+  @Private
+  @Unstable
   void removeCommand(int index);
+  
+  @Private
+  @Unstable
   void clearCommands();
 }