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     * $HADOOP_CLASSPATH.
164     */
165    HADOOP_CLASSPATH("HADOOP_CLASSPATH"),
166
167    /**
168     * $LD_LIBRARY_PATH
169     */
170    LD_LIBRARY_PATH("LD_LIBRARY_PATH"),
171    
172    /**
173     * $HADOOP_CONF_DIR
174     * Final, non-modifiable.
175     */
176    HADOOP_CONF_DIR("HADOOP_CONF_DIR"),
177    
178    /**
179     * $HADOOP_COMMON_HOME
180     */
181    HADOOP_COMMON_HOME("HADOOP_COMMON_HOME"),
182    
183    /**
184     * $HADOOP_HDFS_HOME
185     */
186    HADOOP_HDFS_HOME("HADOOP_HDFS_HOME"),
187    
188    /**
189     * $MALLOC_ARENA_MAX
190     */
191    MALLOC_ARENA_MAX("MALLOC_ARENA_MAX"),
192    
193    /**
194     * $HADOOP_YARN_HOME
195     */
196    HADOOP_YARN_HOME("HADOOP_YARN_HOME"),
197
198    /**
199     * $CONTAINER_ID
200     * Final, exported by NodeManager and non-modifiable by users.
201     */
202    CONTAINER_ID("CONTAINER_ID"),
203
204    /**
205     * $NM_HOST
206     * Final, exported by NodeManager and non-modifiable by users.
207     */
208    NM_HOST("NM_HOST"),
209
210    /**
211     * $NM_HTTP_PORT
212     * Final, exported by NodeManager and non-modifiable by users.
213     */
214    NM_HTTP_PORT("NM_HTTP_PORT"),
215
216    /**
217     * $NM_PORT
218     * Final, exported by NodeManager and non-modifiable by users.
219     */
220    NM_PORT("NM_PORT"),
221
222    /**
223     * $LOCAL_DIRS
224     * Final, exported by NodeManager and non-modifiable by users.
225     */
226    LOCAL_DIRS("LOCAL_DIRS"),
227
228    /**
229     * $LOG_DIRS
230     * Final, exported by NodeManager and non-modifiable by users.
231     * Comma separate list of directories that the container should use for
232     * logging.
233     */
234    LOG_DIRS("LOG_DIRS");
235
236    private final String variable;
237    private Environment(String variable) {
238      this.variable = variable;
239    }
240    
241    public String key() {
242      return variable;
243    }
244    
245    public String toString() {
246      return variable;
247    }
248
249    /**
250     * Expand the environment variable based on client OS environment variable
251     * expansion syntax (e.g. $VAR for Linux and %VAR% for Windows).
252     * <p>
253     * Note: Use $$() method for cross-platform practice i.e. submit an
254     * application from a Windows client to a Linux/Unix server or vice versa.
255     * </p>
256     */
257    public String $() {
258      if (Shell.WINDOWS) {
259        return "%" + variable + "%";
260      } else {
261        return "$" + variable;
262      }
263    }
264
265    /**
266     * Expand the environment variable in platform-agnostic syntax. The
267     * parameter expansion marker "{{VAR}}" will be replaced with real parameter
268     * expansion marker ('%' for Windows and '$' for Linux) by NodeManager on
269     * container launch. For example: {{VAR}} will be replaced as $VAR on Linux,
270     * and %VAR% on Windows.
271     */
272    @Public
273    @Unstable
274    public String $$() {
275      return PARAMETER_EXPANSION_LEFT + variable + PARAMETER_EXPANSION_RIGHT;
276    }
277  }
278}