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 }