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 020package org.apache.hadoop.yarn.client.api; 021 022import java.io.IOException; 023import java.nio.ByteBuffer; 024import java.util.Map; 025 026import org.apache.hadoop.classification.InterfaceAudience; 027import org.apache.hadoop.classification.InterfaceAudience.Private; 028import org.apache.hadoop.classification.InterfaceAudience.Public; 029import org.apache.hadoop.classification.InterfaceStability; 030import org.apache.hadoop.service.AbstractService; 031import org.apache.hadoop.yarn.api.records.Container; 032import org.apache.hadoop.yarn.api.records.ContainerId; 033import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 034import org.apache.hadoop.yarn.api.records.ContainerStatus; 035import org.apache.hadoop.yarn.api.records.NodeId; 036import org.apache.hadoop.yarn.client.api.impl.NMClientImpl; 037import org.apache.hadoop.yarn.exceptions.YarnException; 038 039@InterfaceAudience.Public 040@InterfaceStability.Stable 041public 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 NMTokenCache nmTokenCache = NMTokenCache.getSingleton(); 062 063 @Private 064 protected NMClient(String name) { 065 super(name); 066 } 067 068 /** 069 * <p>Start an allocated container.</p> 070 * 071 * <p>The <code>ApplicationMaster</code> or other applications that use the 072 * client must provide the details of the allocated container, including the 073 * Id, the assigned node's Id and the token via {@link Container}. In 074 * addition, the AM needs to provide the {@link ContainerLaunchContext} as 075 * well.</p> 076 * 077 * @param container the allocated container 078 * @param containerLaunchContext the context information needed by the 079 * <code>NodeManager</code> to launch the 080 * container 081 * @return a map between the auxiliary service names and their outputs 082 * @throws YarnException 083 * @throws IOException 084 */ 085 public abstract Map<String, ByteBuffer> startContainer(Container container, 086 ContainerLaunchContext containerLaunchContext) 087 throws YarnException, IOException; 088 089 /** 090 * <p>Increase the resource of a container.</p> 091 * 092 * <p>The <code>ApplicationMaster</code> or other applications that use the 093 * client must provide the details of the container, including the Id and 094 * the target resource encapsulated in the updated container token via 095 * {@link Container}. 096 * </p> 097 * 098 * @param container the container with updated token 099 * @throws YarnException 100 * @throws IOException 101 */ 102 public abstract void increaseContainerResource(Container container) 103 throws YarnException, IOException; 104 105 /** 106 * <p>Stop an started container.</p> 107 * 108 * @param containerId the Id of the started container 109 * @param nodeId the Id of the <code>NodeManager</code> 110 * 111 * @throws YarnException 112 * @throws IOException 113 */ 114 public abstract void stopContainer(ContainerId containerId, NodeId nodeId) 115 throws YarnException, IOException; 116 117 /** 118 * <p>Query the status of a container.</p> 119 * 120 * @param containerId the Id of the started container 121 * @param nodeId the Id of the <code>NodeManager</code> 122 * 123 * @return the status of a container 124 * @throws YarnException 125 * @throws IOException 126 */ 127 public abstract ContainerStatus getContainerStatus(ContainerId containerId, 128 NodeId nodeId) throws YarnException, IOException; 129 130 /** 131 * <p>Set whether the containers that are started by this client, and are 132 * still running should be stopped when the client stops. By default, the 133 * feature should be enabled.</p> However, containers will be stopped only 134 * when service is stopped. i.e. after {@link NMClient#stop()}. 135 * 136 * @param enabled whether the feature is enabled or not 137 */ 138 public abstract void cleanupRunningContainersOnStop(boolean enabled); 139 140 /** 141 * Set the NM Token cache of the <code>NMClient</code>. This cache must be 142 * shared with the {@link AMRMClient} that requested the containers managed 143 * by this <code>NMClient</code> 144 * <p> 145 * If a NM token cache is not set, the {@link NMTokenCache#getSingleton()} 146 * singleton instance will be used. 147 * 148 * @param nmTokenCache the NM token cache to use. 149 */ 150 public void setNMTokenCache(NMTokenCache nmTokenCache) { 151 this.nmTokenCache = nmTokenCache; 152 } 153 154 /** 155 * Get the NM token cache of the <code>NMClient</code>. This cache must be 156 * shared with the {@link AMRMClient} that requested the containers managed 157 * by this <code>NMClient</code> 158 * <p> 159 * If a NM token cache is not set, the {@link NMTokenCache#getSingleton()} 160 * singleton instance will be used. 161 * 162 * @return the NM token cache 163 */ 164 public NMTokenCache getNMTokenCache() { 165 return nmTokenCache; 166 } 167 168}