001/**
002* Licensed to the Apache Software Foundation (ASF) under one
003* or more contributor license agreements.  See the NOTICE file
004* distributed with this work for additional information
005* regarding copyright ownership.  The ASF licenses this file
006* to you under the Apache License, Version 2.0 (the
007* "License"); you may not use this file except in compliance
008* with the License.  You may obtain a copy of the License at
009*
010*     http://www.apache.org/licenses/LICENSE-2.0
011*
012* Unless required by applicable law or agreed to in writing, software
013* distributed under the License is distributed on an "AS IS" BASIS,
014* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015* See the License for the specific language governing permissions and
016* limitations under the License.
017*/
018
019package org.apache.hadoop.yarn.api;
020
021import org.apache.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceStability.Stable;
023import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusRequest;
024import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusResponse;
025import org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest;
026import org.apache.hadoop.yarn.api.protocolrecords.StartContainerResponse;
027import org.apache.hadoop.yarn.api.protocolrecords.StopContainerRequest;
028import org.apache.hadoop.yarn.api.protocolrecords.StopContainerResponse;
029import org.apache.hadoop.yarn.api.records.Container;
030import org.apache.hadoop.yarn.api.records.ContainerId;
031import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
032import org.apache.hadoop.yarn.api.records.ContainerStatus;
033import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
034
035/**
036 * <p>The protocol between an <code>ApplicationMaster</code> and a 
037 * <code>NodeManager</code> to start/stop containers and to get status
038 * of running containers.</p>
039 * 
040 * <p>If security is enabled the <code>NodeManager</code> verifies that the
041 * <code>ApplicationMaster</code> has truly been allocated the container
042 * by the <code>ResourceManager</code> and also verifies all interactions such 
043 * as stopping the container or obtaining status information for the container.
044 * </p>
045 */
046@Public
047@Stable
048public interface ContainerManager {
049  /**
050   * <p>The <code>ApplicationMaster</code> requests a <code>NodeManager</code>
051   * to <em>start</em> a {@link Container} allocated to it using this interface.
052   * </p>
053   * 
054   * <p>The <code>ApplicationMaster</code> has to provide details such as
055   * allocated resource capability, security tokens (if enabled), command
056   * to be executed to start the container, environment for the process, 
057   * necessary binaries/jar/shared-objects etc. via the 
058   * {@link ContainerLaunchContext} in the {@link StartContainerRequest}.</p>
059   * 
060   * <p>Currently the <code>NodeManager</code> sends an immediate, empty 
061   * response via {@link StartContainerResponse} to signify acceptance of the
062   * request and throws an exception in case of errors. The 
063   * <code>ApplicationMaster</code> can use 
064   * {@link #getContainerStatus(GetContainerStatusRequest)} to get updated 
065   * status of the to-be-launched or launched container.</p>
066   * 
067   * @param request request to start a container
068   * @return empty response to indicate acceptance of the request 
069   *         or an exception
070   * @throws YarnRemoteException
071   */
072  @Public
073  @Stable
074  StartContainerResponse startContainer(StartContainerRequest request)
075      throws YarnRemoteException;
076
077  /**
078   * <p>The <code>ApplicationMaster</code> requests a <code>NodeManager</code>
079   * to <em>stop</em> a {@link Container} allocated to it using this interface.
080   * </p>
081   * 
082   * <p>The <code>ApplicationMaster</code> sends a
083   * {@link StopContainerRequest} which includes the {@link ContainerId} of the
084   * container to be stopped.</p>
085   * 
086   * <p>Currently the <code>NodeManager</code> sends an immediate, empty 
087   * response via {@link StopContainerResponse} to signify acceptance of the
088   * request and throws an exception in case of errors. The 
089   * <code>ApplicationMaster</code> can use 
090   * {@link #getContainerStatus(GetContainerStatusRequest)} to get updated 
091   * status of the container.</p>
092   * 
093   * @param request request to stop a container
094   * @return empty response to indicate acceptance of the request 
095   *         or an exception
096   * @throws YarnRemoteException
097   */
098  @Public
099  @Stable
100  StopContainerResponse stopContainer(StopContainerRequest request)
101      throws YarnRemoteException;
102
103  /**
104   * <p>The api used by the <code>ApplicationMaster</code> to request for 
105   * current status of a <code>Container</code> from the 
106   * <code>NodeManager</code>.</p>
107   * 
108   * <p>The <code>ApplicationMaster</code> sends a
109   * {@link GetContainerStatusRequest} which includes the {@link ContainerId} of
110   * the container whose status is needed.</p>
111   *
112   *<p>The <code>NodeManager</code> responds with 
113   *{@link GetContainerStatusResponse} which includes the 
114   *{@link ContainerStatus} of the container.</p>
115   *
116   * @param request request to get <code>ContainerStatus</code> of a container
117   *                with the specified <code>ContainerId</code>
118   * @return response containing the <code>ContainerStatus</code> of the
119   * container
120   * @throws YarnRemoteException
121   */
122  @Public
123  @Stable
124  GetContainerStatusResponse getContainerStatus(
125      GetContainerStatusRequest request) throws YarnRemoteException;
126}