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;
020
021import org.apache.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceAudience.Private;
023import org.apache.hadoop.classification.InterfaceStability.Evolving;
024import org.apache.hadoop.classification.InterfaceStability.Unstable;
025import org.apache.hadoop.security.UserGroupInformation;
026import org.apache.hadoop.util.Shell;
027
028/**
029 * This is the API for the applications comprising of constants that YARN sets
030 * up for the applications and the containers.
031 *
032 * TODO: Investigate the semantics and security of each cross-boundary refs.
033 */
034@Public
035@Evolving
036public interface ApplicationConstants {
037
038  /**
039   * The environment variable for APP_SUBMIT_TIME. Set in AppMaster environment
040   * only
041   */
042  public static final String APP_SUBMIT_TIME_ENV = "APP_SUBMIT_TIME_ENV";
043
044  /**
045   * The cache file into which container token is written
046   */
047  public static final String CONTAINER_TOKEN_FILE_ENV_NAME =
048      UserGroupInformation.HADOOP_TOKEN_FILE_LOCATION;
049
050  /**
051   * The environmental variable for APPLICATION_WEB_PROXY_BASE. Set in
052   * ApplicationMaster's environment only. This states that for all non-relative
053   * web URLs in the app masters web UI what base should they have.
054   */
055  public static final String APPLICATION_WEB_PROXY_BASE_ENV =
056    "APPLICATION_WEB_PROXY_BASE";
057
058  /**
059   * The temporary environmental variable for container log directory. This
060   * should be replaced by real container log directory on container launch.
061   */
062  public static final String LOG_DIR_EXPANSION_VAR = "<LOG_DIR>";
063
064  /**
065   * This constant is used to construct class path and it will be replaced with
066   * real class path separator(':' for Linux and ';' for Windows) by
067   * NodeManager on container launch. User has to use this constant to construct
068   * class path if user wants cross-platform practice i.e. submit an application
069   * from a Windows client to a Linux/Unix server or vice versa.
070   */
071  @Public
072  @Unstable
073  public static final String CLASS_PATH_SEPARATOR= "<CPS>";
074
075  /**
076   * The following two constants are used to expand parameter and it will be
077   * replaced with real parameter expansion marker ('%' for Windows and '$' for
078   * Linux) by NodeManager on container launch. For example: {{VAR}} will be
079   * replaced as $VAR on Linux, and %VAR% on Windows. User has to use this
080   * constant to construct class path if user wants cross-platform practice i.e.
081   * submit an application from a Windows client to a Linux/Unix server or vice
082   * versa.
083   */
084  @Public
085  @Unstable
086  public static final String PARAMETER_EXPANSION_LEFT="{{";
087
088  /**
089   * User has to use this constant to construct class path if user wants
090   * cross-platform practice i.e. submit an application from a Windows client to
091   * a Linux/Unix server or vice versa.
092   */
093  @Public
094  @Unstable
095  public static final String PARAMETER_EXPANSION_RIGHT="}}";
096
097  public static final String STDERR = "stderr";
098
099  public static final String STDOUT = "stdout";
100
101  /**
102   * Environment for Applications.
103   *
104   * Some of the environment variables for applications are <em>final</em>
105   * i.e. they cannot be modified by the applications.
106   */
107  public enum Environment {
108    /**
109     * $USER
110     * Final, non-modifiable.
111     */
112    USER("USER"),
113
114    /**
115     * $LOGNAME
116     * Final, non-modifiable.
117     */
118    LOGNAME("LOGNAME"),
119
120    /**
121     * $HOME
122     * Final, non-modifiable.
123     */
124    HOME("HOME"),
125
126    /**
127     * $PWD
128     * Final, non-modifiable.
129     */
130    PWD("PWD"),
131
132    /**
133     * $PATH
134     */
135    PATH("PATH"),
136
137    /**
138     * $SHELL
139     */
140    SHELL("SHELL"),
141
142    /**
143     * $JAVA_HOME
144     */
145    JAVA_HOME("JAVA_HOME"),
146
147    /**
148     * $CLASSPATH
149     */
150    CLASSPATH("CLASSPATH"),
151
152    /**
153     * $APP_CLASSPATH
154     */
155    APP_CLASSPATH("APP_CLASSPATH"),
156
157    /**
158     * $LD_LIBRARY_PATH
159     */
160    LD_LIBRARY_PATH("LD_LIBRARY_PATH"),
161
162    /**
163     * $YARN_RESOURCEMANAGER_APPLICATION_QUEUE
164     * The queue into which the app was submitted/launched.
165     */
166    YARN_RESOURCEMANAGER_APPLICATION_QUEUE(
167        "YARN_RESOURCEMANAGER_APPLICATION_QUEUE"),
168
169    /**
170     * $HADOOP_CONF_DIR
171     * Final, non-modifiable.
172     */
173    HADOOP_CONF_DIR("HADOOP_CONF_DIR"),
174
175    /**
176     * $HADOOP_COMMON_HOME
177     */
178    HADOOP_COMMON_HOME("HADOOP_COMMON_HOME"),
179
180    /**
181     * $HADOOP_HDFS_HOME
182     */
183    HADOOP_HDFS_HOME("HADOOP_HDFS_HOME"),
184
185    /**
186     * $MALLOC_ARENA_MAX
187     */
188    MALLOC_ARENA_MAX("MALLOC_ARENA_MAX"),
189
190    /**
191     * $HADOOP_YARN_HOME
192     */
193    HADOOP_YARN_HOME("HADOOP_YARN_HOME"),
194
195    /**
196     * $CLASSPATH_PREPEND_DISTCACHE
197     * Private, Windows specific
198     */
199    @Private
200    CLASSPATH_PREPEND_DISTCACHE("CLASSPATH_PREPEND_DISTCACHE"),
201
202    /**
203     * $CONTAINER_ID
204     * Final, exported by NodeManager and non-modifiable by users.
205     */
206    CONTAINER_ID("CONTAINER_ID"),
207
208    /**
209     * $NM_HOST
210     * Final, exported by NodeManager and non-modifiable by users.
211     */
212    NM_HOST("NM_HOST"),
213
214    /**
215     * $NM_HTTP_PORT
216     * Final, exported by NodeManager and non-modifiable by users.
217     */
218    NM_HTTP_PORT("NM_HTTP_PORT"),
219
220    /**
221     * $NM_PORT
222     * Final, exported by NodeManager and non-modifiable by users.
223     */
224    NM_PORT("NM_PORT"),
225
226    /**
227     * $LOCAL_DIRS
228     * Final, exported by NodeManager and non-modifiable by users.
229     */
230    LOCAL_DIRS("LOCAL_DIRS"),
231
232    /**
233     * $LOCAL_USER_DIRS
234     * Final, exported by NodeManager and non-modifiable by users.
235     */
236    LOCAL_USER_DIRS("LOCAL_USER_DIRS"),
237
238    /**
239     * $LOG_DIRS
240     * Final, exported by NodeManager and non-modifiable by users.
241     * Comma separate list of directories that the container should use for
242     * logging.
243     */
244    LOG_DIRS("LOG_DIRS");
245
246    private final String variable;
247    private Environment(String variable) {
248      this.variable = variable;
249    }
250
251    public String key() {
252      return variable;
253    }
254
255    public String toString() {
256      return variable;
257    }
258
259    /**
260     * Expand the environment variable based on client OS environment variable
261     * expansion syntax (e.g. $VAR for Linux and %VAR% for Windows).
262     * <p>
263     * Note: Use $$() method for cross-platform practice i.e. submit an
264     * application from a Windows client to a Linux/Unix server or vice versa.
265     * </p>
266     * @return expanded environment variable.
267     */
268    public String $() {
269      if (Shell.WINDOWS) {
270        return "%" + variable + "%";
271      } else {
272        return "$" + variable;
273      }
274    }
275
276    /**
277     * Expand the environment variable in platform-agnostic syntax. The
278     * parameter expansion marker "{{VAR}}" will be replaced with real parameter
279     * expansion marker ('%' for Windows and '$' for Linux) by NodeManager on
280     * container launch. For example: {{VAR}} will be replaced as $VAR on Linux,
281     * and %VAR% on Windows.
282     * @return expanded environment variable.
283     */
284    @Public
285    @Unstable
286    public String $$() {
287      return PARAMETER_EXPANSION_LEFT + variable + PARAMETER_EXPANSION_RIGHT;
288    }
289  }
290}