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 }