001 /** 002 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, software 014 * distributed under the License is distributed on an "AS IS" BASIS, 015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 016 * See the License for the specific language governing permissions and 017 * limitations under the License. 018 */ 019 020 package org.apache.hadoop.yarn.client.api; 021 022 import java.io.IOException; 023 import java.nio.ByteBuffer; 024 import java.util.Map; 025 026 import org.apache.hadoop.classification.InterfaceAudience; 027 import org.apache.hadoop.classification.InterfaceAudience.Private; 028 import org.apache.hadoop.classification.InterfaceAudience.Public; 029 import org.apache.hadoop.classification.InterfaceStability; 030 import org.apache.hadoop.service.AbstractService; 031 import org.apache.hadoop.yarn.api.records.Container; 032 import org.apache.hadoop.yarn.api.records.ContainerId; 033 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 034 import org.apache.hadoop.yarn.api.records.ContainerStatus; 035 import org.apache.hadoop.yarn.api.records.NodeId; 036 import org.apache.hadoop.yarn.client.api.impl.NMClientImpl; 037 import org.apache.hadoop.yarn.exceptions.YarnException; 038 039 @InterfaceAudience.Public 040 @InterfaceStability.Stable 041 public abstract class NMClient extends AbstractService { 042 043 /** 044 * Create a new instance of NMClient. 045 */ 046 @Public 047 public static NMClient createNMClient() { 048 NMClient client = new NMClientImpl(); 049 return client; 050 } 051 052 /** 053 * Create a new instance of NMClient. 054 */ 055 @Public 056 public static NMClient createNMClient(String name) { 057 NMClient client = new NMClientImpl(name); 058 return client; 059 } 060 061 @Private 062 protected NMClient(String name) { 063 super(name); 064 } 065 066 /** 067 * <p>Start an allocated container.</p> 068 * 069 * <p>The <code>ApplicationMaster</code> or other applications that use the 070 * client must provide the details of the allocated container, including the 071 * Id, the assigned node's Id and the token via {@link Container}. In 072 * addition, the AM needs to provide the {@link ContainerLaunchContext} as 073 * well.</p> 074 * 075 * @param container the allocated container 076 * @param containerLaunchContext the context information needed by the 077 * <code>NodeManager</code> to launch the 078 * container 079 * @return a map between the auxiliary service names and their outputs 080 * @throws YarnException 081 * @throws IOException 082 */ 083 public abstract Map<String, ByteBuffer> startContainer(Container container, 084 ContainerLaunchContext containerLaunchContext) 085 throws YarnException, IOException; 086 087 /** 088 * <p>Stop an started container.</p> 089 * 090 * @param containerId the Id of the started container 091 * @param nodeId the Id of the <code>NodeManager</code> 092 * 093 * @throws YarnException 094 * @throws IOException 095 */ 096 public abstract void stopContainer(ContainerId containerId, NodeId nodeId) 097 throws YarnException, IOException; 098 099 /** 100 * <p>Query the status of a container.</p> 101 * 102 * @param containerId the Id of the started container 103 * @param nodeId the Id of the <code>NodeManager</code> 104 * 105 * @return the status of a container 106 * @throws YarnException 107 * @throws IOException 108 */ 109 public abstract ContainerStatus getContainerStatus(ContainerId containerId, 110 NodeId nodeId) throws YarnException, IOException; 111 112 /** 113 * <p>Set whether the containers that are started by this client, and are 114 * still running should be stopped when the client stops. By default, the 115 * feature should be enabled.</p> However, containers will be stopped only 116 * when service is stopped. i.e. after {@link NMClient#stop()}. 117 * 118 * @param enabled whether the feature is enabled or not 119 */ 120 public abstract void cleanupRunningContainersOnStop(boolean enabled); 121 }