logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nickwilli...@apache.org
Subject svn commit: r1500398 - in /logging/log4j/log4j2/trunk: ./ core/ core/src/main/java/org/apache/logging/log4j/core/selector/ core/src/main/java/org/apache/logging/log4j/core/web/ core/src/main/resources/META-INF/ core/src/main/resources/META-INF/services...
Date Sun, 07 Jul 2013 09:57:01 GMT
Author: nickwilliams
Date: Sun Jul  7 09:57:01 2013
New Revision: 1500398

URL: http://svn.apache.org/r1500398
Log:
[LOG4J2-270], [LOG4J2-293] Removing the separate log4j-web artifact/submodule and integrating it into core. Adding support for web-fragment/auto-initialization in Servlet 3.0 and newer.

Added:
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContainerInitializer.java
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContextListener.java
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletFilter.java
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializer.java
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializerImpl.java
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/package-info.java
    logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/services/javax.servlet.ServletContainerInitializer
    logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/web-fragment.xml
    logging/log4j/log4j2/trunk/src/site/xdoc/manual/webapp.xml
Removed:
    logging/log4j/log4j2/trunk/web/
Modified:
    logging/log4j/log4j2/trunk/checkstyle-import-control.xml
    logging/log4j/log4j2/trunk/core/pom.xml
    logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.java
    logging/log4j/log4j2/trunk/dist/pom.xml
    logging/log4j/log4j2/trunk/flume-ng/src/site/xdoc/index.xml
    logging/log4j/log4j2/trunk/pom.xml
    logging/log4j/log4j2/trunk/samples/flume-embedded/pom.xml
    logging/log4j/log4j2/trunk/samples/flume-embedded/src/main/webapp/WEB-INF/web.xml
    logging/log4j/log4j2/trunk/samples/flume-remote/pom.xml
    logging/log4j/log4j2/trunk/samples/flume-remote/src/main/webapp/WEB-INF/web.xml
    logging/log4j/log4j2/trunk/samples/pom.xml
    logging/log4j/log4j2/trunk/src/site/site.xml
    logging/log4j/log4j2/trunk/src/site/xdoc/manual/logsep.xml
    logging/log4j/log4j2/trunk/src/site/xdoc/maven-artifacts.xml.vm

Modified: logging/log4j/log4j2/trunk/checkstyle-import-control.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/checkstyle-import-control.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/checkstyle-import-control.xml (original)
+++ logging/log4j/log4j2/trunk/checkstyle-import-control.xml Sun Jul  7 09:57:01 2013
@@ -34,6 +34,9 @@
   <!-- Disallow sun.* imports as they are not guaranteed to be the same across all JVMs -->
   <disallow pkg="sun" />
 
+  <!-- Disallow Servlet classes everywhere except in specific packages -->
+  <disallow pkg="javax.servlet" />
+
   <!-- Disallow optional dependencies JPA, MongoDB, CouchDB, etc. everywhere except in specific packages -->
   <disallow pkg="javax.persistence" />
   <disallow pkg="com.mongodb" />
@@ -77,6 +80,14 @@
       <allow pkg="com.fasterxml.jackson" />
     </subpackage>
 
+    <subpackage name="web">
+      <allow pkg="javax.servlet" />
+    </subpackage>
+
+  </subpackage>
+
+  <subpackage name="taglib">
+    <allow pkg="javax.servlet" />
   </subpackage>
 
 </import-control>

Modified: logging/log4j/log4j2/trunk/core/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/pom.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/core/pom.xml (original)
+++ logging/log4j/log4j2/trunk/core/pom.xml Sun Jul  7 09:57:01 2013
@@ -135,6 +135,12 @@
       <optional>true</optional>
     </dependency>
     <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>javax.servlet-api</artifactId>
+      <version>3.0.1</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
       <groupId>org.eclipse.persistence</groupId>
       <artifactId>javax.persistence</artifactId>
       <scope>compile</scope>

Modified: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.java?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.java (original)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.java Sun Jul  7 09:57:01 2013
@@ -43,7 +43,7 @@ import org.apache.logging.log4j.status.S
  *
  * The main downside to this ContextSelector is that Configuration is more challenging.
  *
- * This ContextSelector should not be used with a Servlet Filter such as the JNDIContextFilter.
+ * This ContextSelector should not be used with a Servlet Filter such as the Log4jServletFilter.
  */
 public class ClassLoaderContextSelector implements ContextSelector {
 

Added: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContainerInitializer.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContainerInitializer.java?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContainerInitializer.java (added)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContainerInitializer.java Sun Jul  7 09:57:01 2013
@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache license, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the license for the specific language governing permissions and
+ * limitations under the license.
+ */
+package org.apache.logging.log4j.core.web;
+
+import java.util.EnumSet;
+import java.util.Set;
+import javax.servlet.DispatcherType;
+import javax.servlet.FilterRegistration;
+import javax.servlet.ServletContainerInitializer;
+import javax.servlet.ServletContext;
+import javax.servlet.ServletException;
+
+/**
+ * In a Servlet 3.0 or newer environment, this initializer is responsible for starting up Log4j logging before anything
+ * else happens in application initialization.
+ */
+public class Log4jServletContainerInitializer implements ServletContainerInitializer {
+
+    @Override
+    public void onStartup(Set<Class<?>> classes, ServletContext servletContext) throws ServletException {
+        servletContext.log("Log4jServletContainerInitializer starting up Log4j in Servlet 3.0+ environment.");
+
+        Log4jWebInitializer initializer = Log4jWebInitializerImpl.getLog4jWebInitializer(servletContext);
+        initializer.initialize();
+
+        servletContext.addListener(new Log4jServletContextListener());
+
+        FilterRegistration.Dynamic filter = servletContext.addFilter("Log4jServletFilter", new Log4jServletFilter());
+        filter.addMappingForUrlPatterns(EnumSet.allOf(DispatcherType.class), false, "/*");
+    }
+}

Added: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContextListener.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContextListener.java?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContextListener.java (added)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletContextListener.java Sun Jul  7 09:57:01 2013
@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache license, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the license for the specific language governing permissions and
+ * limitations under the license.
+ */
+package org.apache.logging.log4j.core.web;
+
+import javax.servlet.ServletContext;
+import javax.servlet.ServletContextEvent;
+import javax.servlet.ServletContextListener;
+import javax.servlet.UnavailableException;
+
+/**
+ * In environments older than Servlet 3.0, this initializer is responsible for starting up Log4j logging before anything
+ * else happens in application initialization. In all environments, this shuts down Log4j after the application shuts
+ * down.
+ */
+public class Log4jServletContextListener implements ServletContextListener {
+
+    private ServletContext servletContext;
+    private Log4jWebInitializer initializer;
+
+    @Override
+    public void contextInitialized(ServletContextEvent event) {
+        this.servletContext = event.getServletContext();
+        this.servletContext.log("Log4jServletContextListener ensuring that Log4j starts up properly.");
+
+        this.initializer = Log4jWebInitializerImpl.getLog4jWebInitializer(this.servletContext);
+        try {
+            this.initializer.initialize();
+        } catch (UnavailableException e) {
+            throw new RuntimeException("Failed to initialize Log4j properly.", e);
+        }
+    }
+
+    @Override
+    public void contextDestroyed(ServletContextEvent event) {
+        if (this.servletContext == null || this.initializer == null) {
+            throw new IllegalStateException("Context destroyed before it was initialized.");
+        }
+        this.servletContext.log("Log4jServletContextListener ensuring that Log4j shuts down properly.");
+
+        this.initializer.deinitialize();
+    }
+}

Added: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletFilter.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletFilter.java?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletFilter.java (added)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jServletFilter.java Sun Jul  7 09:57:01 2013
@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache license, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the license for the specific language governing permissions and
+ * limitations under the license.
+ */
+package org.apache.logging.log4j.core.web;
+
+import java.io.IOException;
+import javax.servlet.Filter;
+import javax.servlet.FilterChain;
+import javax.servlet.FilterConfig;
+import javax.servlet.ServletContext;
+import javax.servlet.ServletException;
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+
+/**
+ * This is responsible for the following:
+ * <ul>
+ *     <li>Clearing the logger context when the application has finished starting up.</li>
+ *     <li>Setting the logger context before processing a request and clearing it after processing a request.</li>
+ *     <li>Setting the logger context when the application is starting to shut down.</li>
+ * </ul>
+ * This filter is a once-per-request filter. It is capable of filtering all the different types of requests
+ * (standard, asynchronous, error, etc.) but will not apply processing if the filter matches multiple times on the same
+ * logical request.
+ */
+public class Log4jServletFilter implements Filter {
+
+    private static final String ALREADY_FILTERED_ATTRIBUTE = Log4jServletFilter.class.getName() + ".FILTERED";
+
+    private ServletContext servletContext;
+    private Log4jWebInitializer initializer;
+
+    @Override
+    public void init(FilterConfig filterConfig) throws ServletException {
+        this.servletContext = filterConfig.getServletContext();
+        this.servletContext.log("Log4jServletFilter initialized.");
+
+        this.initializer = Log4jWebInitializerImpl.getLog4jWebInitializer(this.servletContext);
+        this.initializer.clearLoggerContext(); // the application is mostly finished starting up now
+    }
+
+    @Override
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
+            throws IOException, ServletException {
+        if (request.getAttribute(ALREADY_FILTERED_ATTRIBUTE) != null) {
+            chain.doFilter(request, response);
+        } else {
+            request.setAttribute(ALREADY_FILTERED_ATTRIBUTE, true);
+
+            try {
+                this.initializer.setLoggerContext();
+
+                chain.doFilter(request, response);
+            } finally {
+                this.initializer.clearLoggerContext();
+            }
+        }
+    }
+
+    @Override
+    public void destroy() {
+        if (this.servletContext == null || this.initializer == null) {
+            throw new IllegalStateException("Filter destroyed before it was initialized.");
+        }
+        this.servletContext.log("Log4jServletFilter destroyed.");
+
+        this.initializer.setLoggerContext(); // the application is just now starting to shut down
+    }
+}

Added: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializer.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializer.java?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializer.java (added)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializer.java Sun Jul  7 09:57:01 2013
@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache license, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the license for the specific language governing permissions and
+ * limitations under the license.
+ */
+package org.apache.logging.log4j.core.web;
+
+import javax.servlet.UnavailableException;
+
+/**
+ * Specifies an interface for initializing and deinitializing Log4j in a Java EE web application. The default and only
+ * implementation is {@link Log4jWebInitializerImpl}. The initializer is based on an interface to improve testability.
+ */
+interface Log4jWebInitializer {
+    /**
+     * The {@link javax.servlet.ServletContext} context-param name for the name of the {@link org.apache.logging.log4j.core.LoggerContext}.
+     */
+    public static final String LOG4J_CONTEXT_NAME = "log4jContextName";
+
+    /**
+     * The {@link javax.servlet.ServletContext} context-param name for the location of the configuration.
+     */
+    public static final String LOG4J_CONFIG_LOCATION = "log4jConfiguration";
+
+    /**
+     * The {@link javax.servlet.ServletContext} context-param name for the JNDI flag.
+     */
+    public static final String LOG4J_CONFIG_IS_JNDI = "isLog4jContextSelectorNamed";
+
+    /**
+     * The attribute key for the {@link javax.servlet.ServletContext} attribute that the singleton initializer instance
+     * is stored in.
+     */
+    static final String INITIALIZER_ATTRIBUTE = Log4jWebInitializer.class.getName() + ".INSTANCE";
+
+    /**
+     * Starts up Log4j in the web application. Calls {@link #setLoggerContext()} after initialization is complete.
+     *
+     * @throws UnavailableException if a JNDI config location is specified but no name is specified.
+     */
+    void initialize() throws UnavailableException;
+
+    /**
+     * Shuts down Log4j in the web application. Calls {@link #clearLoggerContext()} immediately before deinitialization
+     * begins.
+     */
+    void deinitialize();
+
+    /**
+     * Sets the logger context so that code executing afterwards can easily and quickly access loggers via
+     * {@link org.apache.logging.log4j.LogManager#getLogger}.
+     */
+    void setLoggerContext();
+
+    /**
+     * Clears the logger context set up in {@link #setLoggerContext()}.
+     */
+    void clearLoggerContext();
+}

Added: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializerImpl.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializerImpl.java?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializerImpl.java (added)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/Log4jWebInitializerImpl.java Sun Jul  7 09:57:01 2013
@@ -0,0 +1,179 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache license, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the license for the specific language governing permissions and
+ * limitations under the license.
+ */
+package org.apache.logging.log4j.core.web;
+
+import java.net.URI;
+import javax.servlet.ServletContext;
+import javax.servlet.UnavailableException;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.LoggerContext;
+import org.apache.logging.log4j.core.config.Configurator;
+import org.apache.logging.log4j.core.impl.ContextAnchor;
+import org.apache.logging.log4j.core.impl.Log4jContextFactory;
+import org.apache.logging.log4j.core.lookup.Interpolator;
+import org.apache.logging.log4j.core.lookup.StrSubstitutor;
+import org.apache.logging.log4j.core.selector.ContextSelector;
+import org.apache.logging.log4j.core.selector.NamedContextSelector;
+import org.apache.logging.log4j.spi.LoggerContextFactory;
+
+/**
+ * This class initializes and deinitializes Log4j no matter how the initialization occurs.
+ */
+class Log4jWebInitializerImpl implements Log4jWebInitializer {
+    private static final Object MUTEX = new Object();
+
+    private final StrSubstitutor substitutor = new StrSubstitutor(new Interpolator());
+    private final ServletContext servletContext;
+
+    private String name;
+    private NamedContextSelector selector;
+    private LoggerContext loggerContext;
+
+    private boolean initialized = false;
+    private boolean deinitialized = false;
+
+    private Log4jWebInitializerImpl(ServletContext servletContext) {
+        this.servletContext = servletContext;
+    }
+
+    @Override
+    public synchronized void initialize() throws UnavailableException {
+        if (this.deinitialized) {
+            throw new IllegalStateException("Cannot initialize Log4jWebInitializer after it was destroyed.");
+        }
+
+        // only do this once
+        if (!this.initialized) {
+            this.initialized = true;
+
+            this.name = this.substitutor.replace(this.servletContext.getInitParameter(LOG4J_CONTEXT_NAME));
+            String location = this.substitutor.replace(this.servletContext.getInitParameter(LOG4J_CONFIG_LOCATION));
+            boolean isJndi = "true".equals(this.servletContext.getInitParameter(LOG4J_CONFIG_IS_JNDI));
+
+            if (isJndi) {
+                this.initializeJndi(location);
+            } else {
+                this.initializeNonJndi(location);
+            }
+
+            this.setLoggerContext(); // the application is just now starting to start up
+        }
+    }
+
+    private void initializeJndi(String location) throws UnavailableException {
+        URI configLocation = null;
+        if (location != null) {
+            try {
+                configLocation = new URI(location);
+            } catch (Exception e) {
+                this.servletContext.log("Unable to convert configuration location [" + location + "] to a URI!", e);
+            }
+        }
+
+        if (this.name == null) {
+            throw new UnavailableException("A log4jContextName context parameter is required");
+        }
+
+        LoggerContext loggerContext;
+        LoggerContextFactory factory = LogManager.getFactory();
+        if (factory instanceof Log4jContextFactory) {
+            ContextSelector selector = ((Log4jContextFactory) factory).getSelector();
+            if (selector instanceof NamedContextSelector) {
+                this.selector = (NamedContextSelector) selector;
+                loggerContext = this.selector.locateContext(this.name, configLocation);
+            } else {
+                this.servletContext.log("Potential problem: Selector is not an instance of NamedContextSelector.");
+                return;
+            }
+        } else {
+            this.servletContext.log("Potential problem: Factory is not an instance of Log4jContextFactory.");
+            return;
+        }
+        this.loggerContext = loggerContext;
+        this.servletContext.log("Created logger context for [" + this.name + "] using [" +
+                loggerContext.getClass().getClassLoader() + "].");
+    }
+
+    private void initializeNonJndi(String location) {
+        if (this.name == null) {
+            this.name = this.servletContext.getServletContextName();
+        }
+
+        if (this.name == null && location == null) {
+            this.servletContext.log("No Log4j context configuration provided. This is very unusual.");
+            return;
+        }
+
+        this.loggerContext = Configurator.initialize(this.name, getClassLoader(), location);
+    }
+
+    @Override
+    public synchronized void deinitialize() {
+        if (!this.initialized) {
+            throw new IllegalStateException("Cannot deinitialize Log4jWebInitializer because it has not initialized.");
+        }
+
+        // only do this once
+        if (!this.deinitialized) {
+            this.deinitialized = true;
+
+            this.clearLoggerContext(); // the application is finished shutting down now
+
+            if (this.loggerContext != null) {
+                this.servletContext.log("Removing LoggerContext for [" + this.name + "].");
+                if (this.selector != null) {
+                    this.selector.removeContext(this.name);
+                }
+                this.loggerContext.stop();
+            }
+        }
+    }
+
+    @Override
+    public void setLoggerContext() {
+        if (this.loggerContext != null) {
+            ContextAnchor.THREAD_CONTEXT.set(this.loggerContext);
+        }
+    }
+
+    @Override
+    public void clearLoggerContext() {
+        ContextAnchor.THREAD_CONTEXT.remove();
+    }
+
+    private ClassLoader getClassLoader() {
+        try {
+            // if container is Servlet 3.0, use its getClassLoader method
+            return (ClassLoader) this.servletContext.getClass().getMethod("getClassLoader").invoke(this.servletContext);
+        } catch (Exception ignore) {
+            // otherwise, use this class's class loader
+            return Log4jWebInitializerImpl.class.getClassLoader();
+        }
+    }
+
+    static Log4jWebInitializer getLog4jWebInitializer(final ServletContext servletContext) {
+        synchronized (MUTEX) {
+            Log4jWebInitializer initializer = (Log4jWebInitializer) servletContext.getAttribute(INITIALIZER_ATTRIBUTE);
+            if (initializer == null) {
+                initializer = new Log4jWebInitializerImpl(servletContext);
+                servletContext.setAttribute(INITIALIZER_ATTRIBUTE, initializer);
+            }
+            return initializer;
+        }
+    }
+}

Added: logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/package-info.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/package-info.java?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/package-info.java (added)
+++ logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/web/package-info.java Sun Jul  7 09:57:01 2013
@@ -0,0 +1,22 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache license, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the license for the specific language governing permissions and
+ * limitations under the license.
+ */
+
+/**
+ * The classes in this package are responsible for properly initializing and deinitializing Log4j in a Java EE web
+ * application.
+ */
+package org.apache.logging.log4j.core.web;

Added: logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/services/javax.servlet.ServletContainerInitializer
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/services/javax.servlet.ServletContainerInitializer?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/services/javax.servlet.ServletContainerInitializer (added)
+++ logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/services/javax.servlet.ServletContainerInitializer Sun Jul  7 09:57:01 2013
@@ -0,0 +1,15 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+org.apache.logging.log4j.core.web.Log4jServletContainerInitializer
\ No newline at end of file

Added: logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/web-fragment.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/web-fragment.xml?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/web-fragment.xml (added)
+++ logging/log4j/log4j2/trunk/core/src/main/resources/META-INF/web-fragment.xml Sun Jul  7 09:57:01 2013
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
+                                  http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
+              version="3.0" metadata-complete="true">
+    <!-- The Log4j web fragment must be loaded before all other fragments. The configuration below should make this
+        happen automatically. If you experience problems, try specifying an <absolute-ordering> in your web.xml
+        deployment descriptor. -->
+    <name>log4j</name>
+    <distributable />
+    <ordering>
+        <before>
+            <others />
+        </before>
+    </ordering>
+</web-fragment>
\ No newline at end of file

Modified: logging/log4j/log4j2/trunk/dist/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/dist/pom.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/dist/pom.xml (original)
+++ logging/log4j/log4j2/trunk/dist/pom.xml Sun Jul  7 09:57:01 2013
@@ -188,23 +188,6 @@
       <classifier>javadoc</classifier>
     </dependency>
     <dependency>
-      <groupId>org.apache.logging.log4j</groupId>
-      <artifactId>log4j-web</artifactId>
-      <version>${project.version}</version>
-    </dependency>
-    <dependency>
-      <groupId>org.apache.logging.log4j</groupId>
-      <artifactId>log4j-web</artifactId>
-      <version>${project.version}</version>
-      <classifier>sources</classifier>
-    </dependency>
-    <dependency>
-      <groupId>org.apache.logging.log4j</groupId>
-      <artifactId>log4j-web</artifactId>
-      <version>${project.version}</version>
-      <classifier>javadoc</classifier>
-    </dependency>
-    <dependency>
       <groupId>org.apache.logging.log4j.osgi</groupId>
       <artifactId>log4j-core-osgi-async</artifactId>
       <version>${project.version}</version>

Modified: logging/log4j/log4j2/trunk/flume-ng/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/flume-ng/src/site/xdoc/index.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/flume-ng/src/site/xdoc/index.xml (original)
+++ logging/log4j/log4j2/trunk/flume-ng/src/site/xdoc/index.xml Sun Jul  7 09:57:01 2013
@@ -128,11 +128,6 @@
                     <version>${log4j2_version}</version>
                   </dependency>
                   <dependency>
-                    <groupId>org.apache.logging.log4j</groupId>
-                    <artifactId>log4j-web</artifactId>
-                    <version>${log4j2_version}</version>
-                  </dependency>
-                  <dependency>
                     <groupId>org.codehaus.jackson</groupId>
                     <artifactId>jackson-core-asl</artifactId>
                     <version>${jackson.version}</version>
@@ -191,11 +186,6 @@
                   <groupId>org.apache.logging.log4j</groupId>
                   <artifactId>log4j-jcl</artifactId>
                 </dependency>
-                <!-- Log4j 2 Servlet Context Listener -->
-                <dependency>
-                  <groupId>org.apache.logging.log4j</groupId>
-                  <artifactId>log4j-web</artifactId>
-                </dependency>
                 <!-- Avro transport protocol - required for Flume -->
                 <dependency>
                   <groupId>org.apache.avro</groupId>

Modified: logging/log4j/log4j2/trunk/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/pom.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/pom.xml (original)
+++ logging/log4j/log4j2/trunk/pom.xml Sun Jul  7 09:57:01 2013
@@ -758,7 +758,6 @@
     <module>log4j-to-slf4j</module>
     <module>jcl-bridge</module>
     <module>flume-ng</module>
-    <module>web</module>
     <module>taglib</module>
     <module>jmx-gui</module>
     <module>samples</module>

Modified: logging/log4j/log4j2/trunk/samples/flume-embedded/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/samples/flume-embedded/pom.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/samples/flume-embedded/pom.xml (original)
+++ logging/log4j/log4j2/trunk/samples/flume-embedded/pom.xml Sun Jul  7 09:57:01 2013
@@ -44,10 +44,6 @@
     </dependency>
     <dependency>
       <groupId>org.apache.logging.log4j</groupId>
-      <artifactId>log4j-web</artifactId>
-    </dependency>
-    <dependency>
-      <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-flume-ng</artifactId>
     </dependency>
     <dependency>

Modified: logging/log4j/log4j2/trunk/samples/flume-embedded/src/main/webapp/WEB-INF/web.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/samples/flume-embedded/src/main/webapp/WEB-INF/web.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/samples/flume-embedded/src/main/webapp/WEB-INF/web.xml (original)
+++ logging/log4j/log4j2/trunk/samples/flume-embedded/src/main/webapp/WEB-INF/web.xml Sun Jul  7 09:57:01 2013
@@ -46,7 +46,7 @@
 	</session-config>
 
 	<listener>
-		<listener-class>org.apache.logging.log4j.core.web.Log4jContextListener</listener-class>
+		<listener-class>org.apache.logging.log4j.core.web.Log4jServletContextListener</listener-class>
 	</listener>
 
 	<context-param>

Modified: logging/log4j/log4j2/trunk/samples/flume-remote/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/samples/flume-remote/pom.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/samples/flume-remote/pom.xml (original)
+++ logging/log4j/log4j2/trunk/samples/flume-remote/pom.xml Sun Jul  7 09:57:01 2013
@@ -44,10 +44,6 @@
     </dependency>
     <dependency>
       <groupId>org.apache.logging.log4j</groupId>
-      <artifactId>log4j-web</artifactId>
-    </dependency>
-    <dependency>
-      <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-flume-ng</artifactId>
     </dependency>
     <dependency>

Modified: logging/log4j/log4j2/trunk/samples/flume-remote/src/main/webapp/WEB-INF/web.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/samples/flume-remote/src/main/webapp/WEB-INF/web.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/samples/flume-remote/src/main/webapp/WEB-INF/web.xml (original)
+++ logging/log4j/log4j2/trunk/samples/flume-remote/src/main/webapp/WEB-INF/web.xml Sun Jul  7 09:57:01 2013
@@ -46,7 +46,7 @@
 	</session-config>
 
 	<listener>
-		<listener-class>org.apache.logging.log4j.core.web.Log4jContextListener</listener-class>
+		<listener-class>org.apache.logging.log4j.core.web.Log4jServletContextListener</listener-class>
 	</listener>
 
 	<context-param>

Modified: logging/log4j/log4j2/trunk/samples/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/samples/pom.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/samples/pom.xml (original)
+++ logging/log4j/log4j2/trunk/samples/pom.xml Sun Jul  7 09:57:01 2013
@@ -36,11 +36,6 @@
     <dependencies>
       <dependency>
         <groupId>org.apache.logging.log4j</groupId>
-        <artifactId>log4j-web</artifactId>
-        <version>${project.version}</version>
-      </dependency>
-      <dependency>
-        <groupId>org.apache.logging.log4j</groupId>
         <artifactId>log4j-flume-ng</artifactId>
         <version>${project.version}</version>
       </dependency>

Modified: logging/log4j/log4j2/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/site.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/site.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/site.xml Sun Jul  7 09:57:01 2013
@@ -54,6 +54,12 @@
         <item name="Unit Testing in Maven" href="/manual/configuration.html#UnitTestingInMaven"/>
       </item>
 
+      <item name="Web Applications" href="/manual/webapp.html" collapse="true">
+        <item name="Servlet 3.0 and Newer" href="/manual/webapp.html#Servlet-3.0" />
+        <item name="Servlet 2.5" href="/manual/webapp.html#Servlet-2.5" />
+        <item name="Context Parameters" href="/manual/webapp.html#ContextParams" />
+      </item>
+
       <item name="Plugins" href="/manual/plugins.html" collapse="true">
         <item name="Core" href="/manual/plugins.html#Core"/>
         <item name="Converters" href="/manual/plugins.html#Converters"/>
@@ -148,7 +154,6 @@
       <item name="SLF4J Binding" href="log4j-slf4j-impl/index.html"/>
       <item name="Log4j 2 to SLF4J Adapter" href="log4j-to-slf4j/index.html"/>
       <item name="Apache Flume" href="log4j-flume-ng/index.html"/>
-      <item name="Log4j Web" href="log4j-web/index.html"/>
       <item name="Log4j Tag Library" href="log4j-taglib/index.html"/>
       <item name="Log4j JMX GUI" href="log4j-jmx-gui/index.html"/>
     </menu>

Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/logsep.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/logsep.xml?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/logsep.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/logsep.xml Sun Jul  7 09:57:01 2013
@@ -44,14 +44,16 @@
             <p>
               A typical web application will be packaged as a WAR file and will include all of its dependencies in
               WEB-INF/lib and will have its configuration file located in the class path or in a location
-              configured in the web.xml.
+              configured in the web.xml. Be sure to follow the <a href="webapp.html">instructions to initialize Log4j 2
+              in a web application</a>.
             </p>
           <h4>Java EE Applications</h4>
             <p>
               A Java EE application will consist of one or more WAR files and possible some EJBs, typically all
               packaged in an EAR file. Usually, it is desirable to have a single configuration that applies to
               all the components in the EAR. The logging classes will generally be placed in a location shared
-              across all the components and the configuration needs to also be shareable.
+              across all the components and the configuration needs to also be shareable.  Be sure to follow the
+              <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>.
             </p>
           <h4>"Shared" Web Applications and REST Service Containers</h4>
             <p>
@@ -83,21 +85,25 @@
                   applications.</li>
                 <li>
                   Place the logging jars in the container's classpath and use the default ClassLoaderContextSelector.
-                  Include the Log4jContextListener in each web application. Each ContextListener can be configured
-                  to share the same configuration used at the container or they can be individually configured. If
-                  status logging is set to debug in the configuration there will be output from when logging is
-                  initialized in the container and then again in each web application.
+                  Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>. Each
+                  application can be configured to share the same configuration used at the container or can be
+                  individually configured. If status logging is set to debug in the configuration there will be output
+                  from when logging is initialized in the container and then again in each web application.
                 </li>
                 <li>
-                  Use the JNDIContextFilter and set the system property "Log4jContextSelector" to
-                  "org.apache.logging.log4j.core.selector.JNDIContextSelector". This will cause the container to
-                  use JNDI to locate each's web application's LoggerContext.
+                  Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a> and set
+                  the system property "Log4jContextSelector" to
+                  "org.apache.logging.log4j.core.selector.JNDIContextSelector." This will cause the container to
+                  use JNDI to locate each web application's <code>LoggerContext</code>. Be sure to set the
+                  <code>isLog4jContextSelectorNamed</code> context parameter to <code>true</code> and also set the
+                  <code>log4jContextName</code> and <code>log4jConfiguration</code> context parameters.
                 </li>
               </ol>
             </p>
-            <p>The exact method for setting system properties depends on the container.
-            For Tomcat, edit $CATALINA_HOME/conf/catalina.properties. 
-            Consult the documentation for other web containers.</p>
+            <p>
+              The exact method for setting system properties depends on the container. For Tomcat, edit
+              $CATALINA_HOME/conf/catalina.properties. Consult the documentation for other web containers.
+            </p>
         </subsection>
       </section>
     </body>

Added: logging/log4j/log4j2/trunk/src/site/xdoc/manual/webapp.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/webapp.xml?rev=1500398&view=auto
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/webapp.xml (added)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/webapp.xml Sun Jul  7 09:57:01 2013
@@ -0,0 +1,171 @@
+<?xml version="1.0"?>
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+<document>
+  <properties>
+    <title>Log4j 2 Web Applications</title>
+    <author email="nickwilliams@apache.org">Nick Williams</author>
+  </properties>
+
+  <body>
+    <section name="Using Log4j 2 in Web Applications">
+      <p>
+        You must take particular care when using Log4j or any other logging framework within a Java EE web application.
+        It's important for logging resources to be properly cleaned up (database connections closed, files closed, etc.)
+        when the container shuts down or the web application is undeployed. Because of the nature of class loaders
+        within web applications, Log4j resources cannot be cleaned up through normal means. Log4j must be "started" when
+        the web application deploys and "shut down" when the web application undeploys. How this works varies depending
+        on whether your application is a <a href="#Servlet-3.0">Servlet 3.0 or newer</a> or
+        <a href="#Servlet-2.5">Servlet 2.5</a> web application.
+      </p>
+      <a name="Servlet-3.0" />
+      <subsection name="Servlet 3.0 and Newer Web Applications">
+        <p>
+          A Servlet 3.0 or newer web application is any <code>&lt;web-app&gt;</code> whose <code>version</code>
+          attribute has a value of "3.0" or higher. Of course, the application must also be running in a compatible
+          web container. Some examples are: Tomcat 7.0 and higher, GlassFish 3.0 and higher, JBoss 7.0 and higher,
+          Oracle WebLogic 12c and higher, and IBM WebSphere 8.0 and higher.
+        </p>
+        <p>
+          <b>The Short Story</b><br />
+          Log4j 2 "just works" in Servlet 3.0 and newer web applications. It is capable of automatically starting when
+          the application deploys and shutting down when the application undeploys.
+        </p>
+        <p>
+          <b>The Long Story</b><br />
+          The Log4j 2 Core JAR file is a web-fragment configured to order before any other web fragments in your
+          application. It contains a <code>ServletContainerInitializer</code>
+          (<a href="../log4j-core/apidocs/org/apache/logging/log4j/core/web/Log4jServletContainerInitializer.html"
+            >Log4jServletContainerInitializer</a>) that the container automatically discovers and initializes. This adds
+          the <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/web/Log4jServletContextListener.html"
+            >Log4jServletContextListener</a> and
+          <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/web/Log4jServletFilter.html"
+            >Log4jServletFilter</a> to the <code>ServletContext</code>. These classes properly initialize
+          and deinitialize the Log4j configuration.
+        </p>
+        <p>
+          You can customize the behavior of the listener and filter using the <code>log4jContextName</code>,
+          <code>log4jConfiguration</code>, and/or <code>isLog4jContextSelectorNamed</code> context parameters. Read more
+          about this in the <a href="#ContextParams">Context Parameters</a> section below.
+        </p>
+      </subsection>
+      <a name="Servlet-2.5" />
+      <subsection name="Servlet 2.5 Web Applications">
+        <p>
+          A Servlet 2.5 web application is any <code>&lt;web-app&gt;</code> whose <code>version</code> attribute has a
+          value of "2.5." Note that Log4j 2 does not support Servlet 2.4 and older web applications. The
+          <code>version</code> attribute is the only thing that matters; even if the web application is running in a
+          Servlet 3.0 or newer container, it is a Servlet 2.5 web application if the <code>version</code> attribute
+          is "2.5."
+        </p>
+        <p>
+          If you are using Log4j in a Servlet 2.5 web application, you <em>must</em> configure the
+          <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/web/Log4jServletContextListener.html"
+            >Log4jServletContextListener</a> and
+          <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/web/Log4jServletFilter.html"
+            >Log4jServletFilter</a> in the deployment descriptor. The filter should match all requests of any type. The
+          listener should be the very first listener defined in the deployment descriptor, and the filter should be the
+          very first filter defined and mapped in the deployment descriptor. This is easily accomplished using the
+          following <code>web.xml</code> code:
+          <pre class="prettyprint linenums"><![CDATA[    <listener>
+        <listener-class>org.apache.logging.log4j.core.web.Log4jServletContextListener</listener-class>
+    </listener>
+
+    <filter>
+        <filter-name>log4jServletFilter</filter-name>
+        <filter-class>org.apache.logging.log4j.core.web.Log4jServletFilter</filter-class>
+    </filter>
+    <filter-mapping>
+        <filter-name>log4jServletFilter</filter-name>
+        <url-pattern>/*</url-pattern>
+        <dispatcher>REQUEST</dispatcher>
+        <dispatcher>FORWARD</dispatcher>
+        <dispatcher>INCLUDE</dispatcher>
+        <dispatcher>ERROR</dispatcher>
+    </filter-mapping>]]></pre>
+        </p>
+        <p>
+          You can customize the behavior of the listener and filter using the <code>log4jContextName</code>,
+          <code>log4jConfiguration</code>, and/or <code>isLog4jContextSelectorNamed</code> context parameters. Read more
+          about this in the <a href="#ContextParams">Context Parameters</a> section below.
+        </p>
+      </subsection>
+      <a name="ContextParams" />
+      <subsection name="Context Parameters">
+        <p>
+          By default, Log4j 2 uses the <code>ServletContext</code>'s context name as the <code>LoggerContext</code> name
+          and uses the standard pattern for locating the Log4j configuration file. There are three context parameters
+          that you can use to control this behavior. The first, <code>isLog4jContextSelectorNamed</code>, specifies
+          whether the context should be selected using the
+          <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JNDIContextSelector.html"
+            >JNDIContextSelector</a>. If <code>isLog4jContextSelectorNamed</code> is not specified or is anything other
+          than <code>true</code>, it is assumed to be <code>false</code>.
+        </p>
+        <p>
+          If <code>isLog4jContextSelectorNamed</code> is <code>true</code>, <code>log4jContextName</code> must be
+          specified; otherwise, the application will fail to start with an exception. <code>log4jConfiguration</code>
+          <em>should</em> also be specified in this case, and must be a valid URI for the configuration; however, this
+          parameter is not required.
+        </p>
+        <p>
+          If <code>isLog4jContextSelectorNamed</code> is not <code>true</code>, <code>log4jConfiguration</code> may be a
+          valid URI or a path to a file, or it may start with "classpath:" to denote a file that can be found on the
+          classpath.
+        </p>
+        <p>
+          When specifying these context parameters, you must specify them in the deployment descriptor
+          (<code>web.xml</code>) even in a Servlet 3.0 or never application. If you add them to the
+          <code>ServletContext</code> within a listener, Log4j will initialize before the context parameters are
+          available and they will have no effect. Here are some sample uses of these context parameters.
+        </p>
+        <p>
+          <b>Set the Logging Context Name to "myApplication"</b>
+          <pre class="prettyprint linenums"><![CDATA[    <context-param>
+        <param-name>log4jContextName</param-name>
+        <param-value>myApplication</param-value>
+    </context-param>]]></pre>
+        </p>
+        <p>
+          <b>Set the Configuration Path/File/URI to "/etc/myApp/log4j.xml"</b>
+          <pre class="prettyprint linenums"><![CDATA[    <context-param>
+        <param-name>log4jConfiguration</param-name>
+        <param-value>file:///etc/myApp/log4j.xml</param-value>
+    </context-param>]]></pre>
+        </p>
+        <p>
+          <b>Use the <code>JNDIContextSelector</code></b>
+          <pre class="prettyprint linenums"><![CDATA[    <context-param>
+        <param-name>isLog4jContextSelectorNamed</param-name>
+        <param-value>true</param-value>
+    </context-param>
+    <context-param>
+        <param-name>log4jContextName</param-name>
+        <param-value>appWithJndiSelector</param-value>
+    </context-param>
+    <context-param>
+        <param-name>log4jConfiguration</param-name>
+        <param-value>file://D:\conf\log4j.xml</param-value>
+    </context-param>]]></pre>
+          Note that in this case you must also set the "Log4jContextSelector" system property to
+          "org.apache.logging.log4j.core.selector.JNDIContextSelector."
+        </p>
+      </subsection>
+    </section>
+  </body>
+
+</document>
\ No newline at end of file

Modified: logging/log4j/log4j2/trunk/src/site/xdoc/maven-artifacts.xml.vm
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/maven-artifacts.xml.vm?rev=1500398&r1=1500397&r2=1500398&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/maven-artifacts.xml.vm (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/maven-artifacts.xml.vm Sun Jul  7 09:57:01 2013
@@ -144,24 +144,6 @@
   <dependency org="org.apache.logging.log4j" name="log4j-taglib" rev="${Log4jReleaseVersion}" />
 </dependencies>
 ]]></pre>
-        <h4>Log4j Web</h4>
-        <p>The Log4j Web artifact contains classes that can be used to initialize logging within a web application.</p>
-        <code>pom.xml</code>
-        <pre class="prettyprint linenums"><![CDATA[
-<dependencies>
-  <dependency>
-    <groupId>org.apache.logging.log4j</groupId>
-    <artifactId>log4j-web</artifactId>
-    <version>${Log4jReleaseVersion}</version>
-  </dependency>
-</dependencies>
-]]></pre>
-        <code>ivy.xml</code>
-        <pre class="prettyprint linenums"><![CDATA[
-<dependencies>
-  <dependency org="org.apache.logging.log4j" name="log4j-web" rev="${Log4jReleaseVersion}" />
-</dependencies>
-]]></pre>
         <h4>Apache Flume NG Appender</h4>
         <p>The Flume NG Appender allows applications to send events to Flume NG Agents.</p>
         <code>pom.xml</code>



Mime
View raw message