001/*
002 * Copyright 2002-2014 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.util;
018
019import java.io.FileNotFoundException;
020import javax.servlet.ServletContext;
021
022import org.springframework.util.ResourceUtils;
023import org.springframework.util.StringUtils;
024
025/**
026 * Convenience class that performs custom log4j initialization for web environments,
027 * allowing for log file paths within the web application, with the option to
028 * perform automatic refresh checks (for runtime changes in logging configuration).
029 *
030 * <p><b>WARNING: Assumes an expanded WAR file</b>, both for loading the configuration
031 * file and for writing the log files. If you want to keep your WAR unexpanded or
032 * don't need application-specific log files within the WAR directory, don't use
033 * log4j setup within the application (thus, don't use Log4jConfigListener or
034 * Log4jConfigServlet). Instead, use a global, VM-wide log4j setup (for example,
035 * in JBoss) or JDK 1.4's {@code java.util.logging} (which is global too).
036 *
037 * <p>Supports three init parameters at the servlet context level (that is,
038 * context-param entries in web.xml):
039 *
040 * <ul>
041 * <li><i>"log4jConfigLocation":</i><br>
042 * Location of the log4j config file; either a "classpath:" location (e.g.
043 * "classpath:myLog4j.properties"), an absolute file URL (e.g. "file:C:/log4j.properties),
044 * or a plain path relative to the web application root directory (e.g.
045 * "/WEB-INF/log4j.properties"). If not specified, default log4j initialization
046 * will apply ("log4j.properties" or "log4j.xml" in the class path; see the
047 * log4j documentation for details).
048 * <li><i>"log4jRefreshInterval":</i><br>
049 * Interval between config file refresh checks, in milliseconds. If not specified,
050 * no refresh checks will happen, which avoids starting log4j's watchdog thread.
051 * <li><i>"log4jExposeWebAppRoot":</i><br>
052 * Whether the web app root system property should be exposed, allowing for log
053 * file paths relative to the web application root directory. Default is "true";
054 * specify "false" to suppress expose of the web app root system property. See
055 * below for details on how to use this system property in log file locations.
056 * </ul>
057 *
058 * <p>Note: {@code initLogging} should be called before any other Spring activity
059 * (when using log4j), for proper initialization before any Spring logging attempts.
060 *
061 * <p>Log4j's watchdog thread will asynchronously check whether the timestamp
062 * of the config file has changed, using the given interval between checks.
063 * A refresh interval of 1000 milliseconds (one second), which allows to
064 * do on-demand log level changes with immediate effect, is not unfeasible.
065
066 * <p><b>WARNING:</b> Log4j's watchdog thread does not terminate until VM shutdown;
067 * in particular, it does not terminate on LogManager shutdown. Therefore, it is
068 * recommended to <i>not</i> use config file refreshing in a production J2EE
069 * environment; the watchdog thread would not stop on application shutdown there.
070 *
071 * <p>By default, this configurer automatically sets the web app root system property,
072 * for "${key}" substitutions within log file locations in the log4j config file,
073 * allowing for log file paths relative to the web application root directory.
074 * The default system property key is "webapp.root", to be used in a log4j config
075 * file like as follows:
076 *
077 * <p>{@code log4j.appender.myfile.File=${webapp.root}/WEB-INF/demo.log}
078 *
079 * <p>Alternatively, specify a unique context-param "webAppRootKey" per web application.
080 * For example, with "webAppRootKey = "demo.root":
081 *
082 * <p>{@code log4j.appender.myfile.File=${demo.root}/WEB-INF/demo.log}
083 *
084 * <p><b>WARNING:</b> Some containers (like Tomcat) do <i>not</i> keep system properties
085 * separate per web app. You have to use unique "webAppRootKey" context-params per web
086 * app then, to avoid clashes. Other containers like Resin do isolate each web app's
087 * system properties: Here you can use the default key (i.e. no "webAppRootKey"
088 * context-param at all) without worrying.
089 *
090 * @author Juergen Hoeller
091 * @author Marten Deinum
092 * @since 12.08.2003
093 * @see org.springframework.util.Log4jConfigurer
094 * @see Log4jConfigListener
095 * @deprecated as of Spring 4.2.1, in favor of Apache Log4j 2
096 * (following Apache's EOL declaration for log4j 1.x)
097 */
098@Deprecated
099public abstract class Log4jWebConfigurer {
100
101        /** Parameter specifying the location of the log4j config file */
102        public static final String CONFIG_LOCATION_PARAM = "log4jConfigLocation";
103
104        /** Parameter specifying the refresh interval for checking the log4j config file */
105        public static final String REFRESH_INTERVAL_PARAM = "log4jRefreshInterval";
106
107        /** Parameter specifying whether to expose the web app root system property */
108        public static final String EXPOSE_WEB_APP_ROOT_PARAM = "log4jExposeWebAppRoot";
109
110
111        /**
112         * Initialize log4j, including setting the web app root system property.
113         * @param servletContext the current ServletContext
114         * @see WebUtils#setWebAppRootSystemProperty
115         */
116        public static void initLogging(ServletContext servletContext) {
117                // Expose the web app root system property.
118                if (exposeWebAppRoot(servletContext)) {
119                        WebUtils.setWebAppRootSystemProperty(servletContext);
120                }
121
122                // Only perform custom log4j initialization in case of a config file.
123                String location = servletContext.getInitParameter(CONFIG_LOCATION_PARAM);
124                if (location != null) {
125                        // Perform actual log4j initialization; else rely on log4j's default initialization.
126                        try {
127                                // Resolve property placeholders before potentially resolving a real path.
128                                location = ServletContextPropertyUtils.resolvePlaceholders(location, servletContext);
129
130                                // Leave a URL (e.g. "classpath:" or "file:") as-is.
131                                if (!ResourceUtils.isUrl(location)) {
132                                        // Consider a plain file path as relative to the web application root directory.
133                                        location = WebUtils.getRealPath(servletContext, location);
134                                }
135
136                                // Write log message to server log.
137                                servletContext.log("Initializing log4j from [" + location + "]");
138
139                                // Check whether refresh interval was specified.
140                                String intervalString = servletContext.getInitParameter(REFRESH_INTERVAL_PARAM);
141                                if (StringUtils.hasText(intervalString)) {
142                                        // Initialize with refresh interval, i.e. with log4j's watchdog thread,
143                                        // checking the file in the background.
144                                        try {
145                                                long refreshInterval = Long.parseLong(intervalString);
146                                                org.springframework.util.Log4jConfigurer.initLogging(location, refreshInterval);
147                                        }
148                                        catch (NumberFormatException ex) {
149                                                throw new IllegalArgumentException("Invalid 'log4jRefreshInterval' parameter: " + ex.getMessage());
150                                        }
151                                }
152                                else {
153                                        // Initialize without refresh check, i.e. without log4j's watchdog thread.
154                                        org.springframework.util.Log4jConfigurer.initLogging(location);
155                                }
156                        }
157                        catch (FileNotFoundException ex) {
158                                throw new IllegalArgumentException("Invalid 'log4jConfigLocation' parameter: " + ex.getMessage());
159                        }
160                }
161        }
162
163        /**
164         * Shut down log4j, properly releasing all file locks
165         * and resetting the web app root system property.
166         * @param servletContext the current ServletContext
167         * @see WebUtils#removeWebAppRootSystemProperty
168         */
169        public static void shutdownLogging(ServletContext servletContext) {
170                servletContext.log("Shutting down log4j");
171                try {
172                        org.springframework.util.Log4jConfigurer.shutdownLogging();
173                }
174                finally {
175                        // Remove the web app root system property.
176                        if (exposeWebAppRoot(servletContext)) {
177                                WebUtils.removeWebAppRootSystemProperty(servletContext);
178                        }
179                }
180        }
181
182        /**
183         * Return whether to expose the web app root system property,
184         * checking the corresponding ServletContext init parameter.
185         * @see #EXPOSE_WEB_APP_ROOT_PARAM
186         */
187        private static boolean exposeWebAppRoot(ServletContext servletContext) {
188                String exposeWebAppRootParam = servletContext.getInitParameter(EXPOSE_WEB_APP_ROOT_PARAM);
189                return (exposeWebAppRootParam == null || Boolean.valueOf(exposeWebAppRootParam));
190        }
191
192}