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   * The environment variable for MAX_APP_ATTEMPTS. Set in AppMaster environment
103   * only
104   */
105  public static final String MAX_APP_ATTEMPTS_ENV = "MAX_APP_ATTEMPTS";
106
107  /**
108   * Environment for Applications.
109   * 
110   * Some of the environment variables for applications are <em>final</em> 
111   * i.e. they cannot be modified by the applications.
112   */
113  public enum Environment {
114    /**
115     * $USER
116     * Final, non-modifiable.
117     */
118    USER("USER"),
119    
120    /**
121     * $LOGNAME
122     * Final, non-modifiable.
123     */
124    LOGNAME("LOGNAME"),
125    
126    /**
127     * $HOME
128     * Final, non-modifiable.
129     */
130    HOME("HOME"),
131    
132    /**
133     * $PWD
134     * Final, non-modifiable.
135     */
136    PWD("PWD"),
137    
138    /**
139     * $PATH
140     */
141    PATH("PATH"),
142    
143    /**
144     * $SHELL
145     */
146    SHELL("SHELL"),
147    
148    /**
149     * $JAVA_HOME
150     */
151    JAVA_HOME("JAVA_HOME"),
152    
153    /**
154     * $CLASSPATH
155     */
156    CLASSPATH("CLASSPATH"),
157    
158    /**
159     * $APP_CLASSPATH
160     */
161    APP_CLASSPATH("APP_CLASSPATH"),
162    
163    /**
164     * $HADOOP_CLASSPATH.
165     */
166    HADOOP_CLASSPATH("HADOOP_CLASSPATH"),
167
168    /**
169     * $LD_LIBRARY_PATH
170     */
171    LD_LIBRARY_PATH("LD_LIBRARY_PATH"),
172    
173    /**
174     * $HADOOP_CONF_DIR
175     * Final, non-modifiable.
176     */
177    HADOOP_CONF_DIR("HADOOP_CONF_DIR"),
178    
179    /**
180     * $HADOOP_COMMON_HOME
181     */
182    HADOOP_COMMON_HOME("HADOOP_COMMON_HOME"),
183    
184    /**
185     * $HADOOP_HDFS_HOME
186     */
187    HADOOP_HDFS_HOME("HADOOP_HDFS_HOME"),
188    
189    /**
190     * $MALLOC_ARENA_MAX
191     */
192    MALLOC_ARENA_MAX("MALLOC_ARENA_MAX"),
193    
194    /**
195     * $HADOOP_YARN_HOME
196     */
197    HADOOP_YARN_HOME("HADOOP_YARN_HOME"),
198
199    /**
200     * $CLASSPATH_PREPEND_DISTCACHE
201     * Private, Windows specific
202     */
203    @Private
204    CLASSPATH_PREPEND_DISTCACHE("CLASSPATH_PREPEND_DISTCACHE"),
205
206    /**
207     * $CONTAINER_ID
208     * Final, exported by NodeManager and non-modifiable by users.
209     */
210    CONTAINER_ID("CONTAINER_ID"),
211
212    /**
213     * $NM_HOST
214     * Final, exported by NodeManager and non-modifiable by users.
215     */
216    NM_HOST("NM_HOST"),
217
218    /**
219     * $NM_HTTP_PORT
220     * Final, exported by NodeManager and non-modifiable by users.
221     */
222    NM_HTTP_PORT("NM_HTTP_PORT"),
223
224    /**
225     * $NM_PORT
226     * Final, exported by NodeManager and non-modifiable by users.
227     */
228    NM_PORT("NM_PORT"),
229
230    /**
231     * $LOCAL_DIRS
232     * Final, exported by NodeManager and non-modifiable by users.
233     */
234    LOCAL_DIRS("LOCAL_DIRS"),
235
236    /**
237     * $LOG_DIRS
238     * Final, exported by NodeManager and non-modifiable by users.
239     * Comma separate list of directories that the container should use for
240     * logging.
241     */
242    LOG_DIRS("LOG_DIRS");
243
244    private final String variable;
245    private Environment(String variable) {
246      this.variable = variable;
247    }
248    
249    public String key() {
250      return variable;
251    }
252    
253    public String toString() {
254      return variable;
255    }
256
257    /**
258     * Expand the environment variable based on client OS environment variable
259     * expansion syntax (e.g. $VAR for Linux and %VAR% for Windows).
260     * <p>
261     * Note: Use $$() method for cross-platform practice i.e. submit an
262     * application from a Windows client to a Linux/Unix server or vice versa.
263     * </p>
264     */
265    public String $() {
266      if (Shell.WINDOWS) {
267        return "%" + variable + "%";
268      } else {
269        return "$" + variable;
270      }
271    }
272
273    /**
274     * Expand the environment variable in platform-agnostic syntax. The
275     * parameter expansion marker "{{VAR}}" will be replaced with real parameter
276     * expansion marker ('%' for Windows and '$' for Linux) by NodeManager on
277     * container launch. For example: {{VAR}} will be replaced as $VAR on Linux,
278     * and %VAR% on Windows.
279     */
280    @Public
281    @Unstable
282    public String $$() {
283      return PARAMETER_EXPANSION_LEFT + variable + PARAMETER_EXPANSION_RIGHT;
284    }
285  }
286}