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