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 java.io.IOException;
022    
023    import org.apache.hadoop.classification.InterfaceAudience.Public;
024    import org.apache.hadoop.classification.InterfaceStability.Stable;
025    import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusesRequest;
026    import org.apache.hadoop.yarn.api.protocolrecords.GetContainerStatusesResponse;
027    import org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest;
028    import org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest;
029    import org.apache.hadoop.yarn.api.protocolrecords.StartContainersResponse;
030    import org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest;
031    import org.apache.hadoop.yarn.api.protocolrecords.StopContainersResponse;
032    import org.apache.hadoop.yarn.api.records.Container;
033    import org.apache.hadoop.yarn.api.records.ContainerId;
034    import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
035    import org.apache.hadoop.yarn.api.records.ContainerStatus;
036    import org.apache.hadoop.yarn.exceptions.NMNotYetReadyException;
037    import org.apache.hadoop.yarn.exceptions.YarnException;
038    
039    /**
040     * <p>The protocol between an <code>ApplicationMaster</code> and a 
041     * <code>NodeManager</code> to start/stop containers and to get status
042     * of running containers.</p>
043     * 
044     * <p>If security is enabled the <code>NodeManager</code> verifies that the
045     * <code>ApplicationMaster</code> has truly been allocated the container
046     * by the <code>ResourceManager</code> and also verifies all interactions such 
047     * as stopping the container or obtaining status information for the container.
048     * </p>
049     */
050    @Public
051    @Stable
052    public interface ContainerManagementProtocol {
053    
054      /**
055       * <p>
056       * The <code>ApplicationMaster</code> provides a list of
057       * {@link StartContainerRequest}s to a <code>NodeManager</code> to
058       * <em>start</em> {@link Container}s allocated to it using this interface.
059       * </p>
060       * 
061       * <p>
062       * The <code>ApplicationMaster</code> has to provide details such as allocated
063       * resource capability, security tokens (if enabled), command to be executed
064       * to start the container, environment for the process, necessary
065       * binaries/jar/shared-objects etc. via the {@link ContainerLaunchContext} in
066       * the {@link StartContainerRequest}.
067       * </p>
068       * 
069       * <p>
070       * The <code>NodeManager</code> sends a response via
071       * {@link StartContainersResponse} which includes a list of
072       * {@link Container}s of successfully launched {@link Container}s, a
073       * containerId-to-exception map for each failed {@link StartContainerRequest} in
074       * which the exception indicates errors from per container and a
075       * allServicesMetaData map between the names of auxiliary services and their
076       * corresponding meta-data. Note: None-container-specific exceptions will
077       * still be thrown by the API method itself.
078       * </p>
079       * <p>
080       * The <code>ApplicationMaster</code> can use
081       * {@link #getContainerStatuses(GetContainerStatusesRequest)} to get updated
082       * statuses of the to-be-launched or launched containers.
083       * </p>
084       * 
085       * @param request
086       *          request to start a list of containers
087       * @return response including conatinerIds of all successfully launched
088       *         containers, a containerId-to-exception map for failed requests and
089       *         a allServicesMetaData map.
090       * @throws YarnException
091       * @throws IOException
092       * @throws NMNotYetReadyException
093       *           This exception is thrown when NM starts from scratch but has not
094       *           yet connected with RM.
095       */
096      @Public
097      @Stable
098      StartContainersResponse startContainers(StartContainersRequest request)
099          throws YarnException, IOException;
100    
101      /**
102       * <p>
103       * The <code>ApplicationMaster</code> requests a <code>NodeManager</code> to
104       * <em>stop</em> a list of {@link Container}s allocated to it using this
105       * interface.
106       * </p>
107       * 
108       * <p>
109       * The <code>ApplicationMaster</code> sends a {@link StopContainersRequest}
110       * which includes the {@link ContainerId}s of the containers to be stopped.
111       * </p>
112       * 
113       * <p>
114       * The <code>NodeManager</code> sends a response via
115       * {@link StopContainersResponse} which includes a list of {@link ContainerId}
116       * s of successfully stopped containers, a containerId-to-exception map for
117       * each failed request in which the exception indicates errors from per
118       * container. Note: None-container-specific exceptions will still be thrown by
119       * the API method itself. <code>ApplicationMaster</code> can use
120       * {@link #getContainerStatuses(GetContainerStatusesRequest)} to get updated
121       * statuses of the containers.
122       * </p>
123       * 
124       * @param request
125       *          request to stop a list of containers
126       * @return response which includes a list of containerIds of successfully
127       *         stopped containers, a containerId-to-exception map for failed
128       *         requests.
129       * @throws YarnException
130       * @throws IOException
131       */
132      @Public
133      @Stable
134      StopContainersResponse stopContainers(StopContainersRequest request)
135          throws YarnException, IOException;
136    
137      /**
138       * <p>
139       * The API used by the <code>ApplicationMaster</code> to request for current
140       * statuses of <code>Container</code>s from the <code>NodeManager</code>.
141       * </p>
142       * 
143       * <p>
144       * The <code>ApplicationMaster</code> sends a
145       * {@link GetContainerStatusesRequest} which includes the {@link ContainerId}s
146       * of all containers whose statuses are needed.
147       * </p>
148       * 
149       * <p>
150       * The <code>NodeManager</code> responds with
151       * {@link GetContainerStatusesResponse} which includes a list of
152       * {@link ContainerStatus} of the successfully queried containers and a
153       * containerId-to-exception map for each failed request in which the exception
154       * indicates errors from per container. Note: None-container-specific
155       * exceptions will still be thrown by the API method itself.
156       * </p>
157       * 
158       * @param request
159       *          request to get <code>ContainerStatus</code>es of containers with
160       *          the specified <code>ContainerId</code>s
161       * @return response containing the list of <code>ContainerStatus</code> of the
162       *         successfully queried containers and a containerId-to-exception map
163       *         for failed requests.
164       * 
165       * @throws YarnException
166       * @throws IOException
167       */
168      @Public
169      @Stable
170      GetContainerStatusesResponse getContainerStatuses(
171          GetContainerStatusesRequest request) throws YarnException,
172          IOException;
173    }