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 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>Stop an started container.</p>
091 *
092 * @param containerId the Id of the started container
093 * @param nodeId the Id of the <code>NodeManager</code>
094 *
095 * @throws YarnException
096 * @throws IOException
097 */
098 public abstract void stopContainer(ContainerId containerId, NodeId nodeId)
099 throws YarnException, IOException;
100
101 /**
102 * <p>Query the status of a container.</p>
103 *
104 * @param containerId the Id of the started container
105 * @param nodeId the Id of the <code>NodeManager</code>
106 *
107 * @return the status of a container
108 * @throws YarnException
109 * @throws IOException
110 */
111 public abstract ContainerStatus getContainerStatus(ContainerId containerId,
112 NodeId nodeId) throws YarnException, IOException;
113
114 /**
115 * <p>Set whether the containers that are started by this client, and are
116 * still running should be stopped when the client stops. By default, the
117 * feature should be enabled.</p> However, containers will be stopped only
118 * when service is stopped. i.e. after {@link NMClient#stop()}.
119 *
120 * @param enabled whether the feature is enabled or not
121 */
122 public abstract void cleanupRunningContainersOnStop(boolean enabled);
123
124 /**
125 * Set the NM Token cache of the <code>NMClient</code>. This cache must be
126 * shared with the {@link AMRMClient} that requested the containers managed
127 * by this <code>NMClient</code>
128 * <p/>
129 * If a NM token cache is not set, the {@link NMTokenCache#getSingleton()}
130 * singleton instance will be used.
131 *
132 * @param nmTokenCache the NM token cache to use.
133 */
134 public void setNMTokenCache(NMTokenCache nmTokenCache) {
135 this.nmTokenCache = nmTokenCache;
136 }
137
138 /**
139 * Get the NM token cache of the <code>NMClient</code>. This cache must be
140 * shared with the {@link AMRMClient} that requested the containers managed
141 * by this <code>NMClient</code>
142 * <p/>
143 * If a NM token cache is not set, the {@link NMTokenCache#getSingleton()}
144 * singleton instance will be used.
145 *
146 * @return the NM token cache
147 */
148 public NMTokenCache getNMTokenCache() {
149 return nmTokenCache;
150 }
151
152 }