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    
019    package org.apache.hadoop.yarn.api;
020    
021    import org.apache.hadoop.classification.InterfaceAudience.Public;
022    import org.apache.hadoop.classification.InterfaceStability.Evolving;
023    import org.apache.hadoop.classification.InterfaceStability.Unstable;
024    import org.apache.hadoop.security.UserGroupInformation;
025    import 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
035    public 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    }