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