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    
019    package org.apache.hadoop.yarn.api;
020    
021    import org.apache.hadoop.classification.InterfaceAudience.Public;
022    import org.apache.hadoop.classification.InterfaceStability.Stable;
023    import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusRequest;
024    import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusResponse;
025    import org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest;
026    import org.apache.hadoop.yarn.api.protocolrecords.StartContainerResponse;
027    import org.apache.hadoop.yarn.api.protocolrecords.StopContainerRequest;
028    import org.apache.hadoop.yarn.api.protocolrecords.StopContainerResponse;
029    import org.apache.hadoop.yarn.api.records.Container;
030    import org.apache.hadoop.yarn.api.records.ContainerId;
031    import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
032    import org.apache.hadoop.yarn.api.records.ContainerStatus;
033    import 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
048    public 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    }