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.records;
020
021 import java.nio.ByteBuffer;
022 import java.util.List;
023 import java.util.Map;
024
025 import org.apache.hadoop.classification.InterfaceAudience.Public;
026 import org.apache.hadoop.classification.InterfaceStability.Stable;
027 import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
028 import org.apache.hadoop.yarn.server.api.ApplicationInitializationContext;
029 import org.apache.hadoop.yarn.server.api.AuxiliaryService;
030 import org.apache.hadoop.yarn.util.Records;
031
032 /**
033 * <p><code>ContainerLaunchContext</code> represents all of the information
034 * needed by the <code>NodeManager</code> to launch a container.</p>
035 *
036 * <p>It includes details such as:
037 * <ul>
038 * <li>{@link ContainerId} of the container.</li>
039 * <li>{@link Resource} allocated to the container.</li>
040 * <li>User to whom the container is allocated.</li>
041 * <li>Security tokens (if security is enabled).</li>
042 * <li>
043 * {@link LocalResource} necessary for running the container such
044 * as binaries, jar, shared-objects, side-files etc.
045 * </li>
046 * <li>Optional, application-specific binary service data.</li>
047 * <li>Environment variables for the launched process.</li>
048 * <li>Command to launch the container.</li>
049 * </ul>
050 * </p>
051 *
052 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
053 */
054 @Public
055 @Stable
056 public abstract class ContainerLaunchContext {
057
058 @Public
059 @Stable
060 public static ContainerLaunchContext newInstance(
061 Map<String, LocalResource> localResources,
062 Map<String, String> environment, List<String> commands,
063 Map<String, ByteBuffer> serviceData, ByteBuffer tokens,
064 Map<ApplicationAccessType, String> acls) {
065 ContainerLaunchContext container =
066 Records.newRecord(ContainerLaunchContext.class);
067 container.setLocalResources(localResources);
068 container.setEnvironment(environment);
069 container.setCommands(commands);
070 container.setServiceData(serviceData);
071 container.setTokens(tokens);
072 container.setApplicationACLs(acls);
073 return container;
074 }
075
076 /**
077 * Get all the tokens needed by this container. It may include file-system
078 * tokens, ApplicationMaster related tokens if this container is an
079 * ApplicationMaster or framework level tokens needed by this container to
080 * communicate to various services in a secure manner.
081 *
082 * @return tokens needed by this container.
083 */
084 @Public
085 @Stable
086 public abstract ByteBuffer getTokens();
087
088 /**
089 * Set security tokens needed by this container.
090 * @param tokens security tokens
091 */
092 @Public
093 @Stable
094 public abstract void setTokens(ByteBuffer tokens);
095
096 /**
097 * Get <code>LocalResource</code> required by the container.
098 * @return all <code>LocalResource</code> required by the container
099 */
100 @Public
101 @Stable
102 public abstract Map<String, LocalResource> getLocalResources();
103
104 /**
105 * Set <code>LocalResource</code> required by the container. All pre-existing
106 * Map entries are cleared before adding the new Map
107 * @param localResources <code>LocalResource</code> required by the container
108 */
109 @Public
110 @Stable
111 public abstract void setLocalResources(Map<String, LocalResource> localResources);
112
113 /**
114 * <p>
115 * Get application-specific binary <em>service data</em>. This is a map keyed
116 * by the name of each {@link AuxiliaryService} that is configured on a
117 * NodeManager and value correspond to the application specific data targeted
118 * for the keyed {@link AuxiliaryService}.
119 * </p>
120 *
121 * <p>
122 * This will be used to initialize this application on the specific
123 * {@link AuxiliaryService} running on the NodeManager by calling
124 * {@link AuxiliaryService#initializeApplication(ApplicationInitializationContext)}
125 * </p>
126 *
127 * @return application-specific binary <em>service data</em>
128 */
129 @Public
130 @Stable
131 public abstract Map<String, ByteBuffer> getServiceData();
132
133 /**
134 * <p>
135 * Set application-specific binary <em>service data</em>. This is a map keyed
136 * by the name of each {@link AuxiliaryService} that is configured on a
137 * NodeManager and value correspond to the application specific data targeted
138 * for the keyed {@link AuxiliaryService}. All pre-existing Map entries are
139 * preserved.
140 * </p>
141 *
142 * @param serviceData
143 * application-specific binary <em>service data</em>
144 */
145 @Public
146 @Stable
147 public abstract void setServiceData(Map<String, ByteBuffer> serviceData);
148
149 /**
150 * Get <em>environment variables</em> for the container.
151 * @return <em>environment variables</em> for the container
152 */
153 @Public
154 @Stable
155 public abstract Map<String, String> getEnvironment();
156
157 /**
158 * Add <em>environment variables</em> for the container. All pre-existing Map
159 * entries are cleared before adding the new Map
160 * @param environment <em>environment variables</em> for the container
161 */
162 @Public
163 @Stable
164 public abstract void setEnvironment(Map<String, String> environment);
165
166 /**
167 * Get the list of <em>commands</em> for launching the container.
168 * @return the list of <em>commands</em> for launching the container
169 */
170 @Public
171 @Stable
172 public abstract List<String> getCommands();
173
174 /**
175 * Add the list of <em>commands</em> for launching the container. All
176 * pre-existing List entries are cleared before adding the new List
177 * @param commands the list of <em>commands</em> for launching the container
178 */
179 @Public
180 @Stable
181 public abstract void setCommands(List<String> commands);
182
183 /**
184 * Get the <code>ApplicationACL</code>s for the application.
185 * @return all the <code>ApplicationACL</code>s
186 */
187 @Public
188 @Stable
189 public abstract Map<ApplicationAccessType, String> getApplicationACLs();
190
191 /**
192 * Set the <code>ApplicationACL</code>s for the application. All pre-existing
193 * Map entries are cleared before adding the new Map
194 * @param acls <code>ApplicationACL</code>s for the application
195 */
196 @Public
197 @Stable
198 public abstract void setApplicationACLs(Map<ApplicationAccessType, String> acls);
199 }