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