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}