Add log4j starter and some documentation

As discussed in gh-162

docs/howto.md

@@ -437,6 +437,90 @@ server.port: ${port:8080}
 > Spring can bind to capitalized synonyms for `Environment`
 > properties.
 
+## Configure Logback for Logging
+
+Spring Boot has no mandatory logging dependence, except for the
+`commons-logging` API, of which there are many implementations to
+choose from. To use [Logback](http://logback.qos.ch) you need to
+include it, and some bindings for `commons-logging` on the classpath.
+The simplest way to do that is through the starter poms which all
+depend on `spring-boot-start-logging`.  For a web application you only
+need the web starter since it depends transitively on the logging
+starter. E.g. in Maven:
+
+```xml
+<dependency>
+	<groupId>org.springframework.boot</groupId>
+	<artifactId>spring-boot-starter-web</artifactId>
+</dependency>
+```
+
+Spring Boot has a `LoggingSystem` abstraction that attempts to select
+a system depending on the contents of the classpath. If Logback is
+available it is the first choice. So if you put a `logback.xml` in the
+root of your classpath it will be picked up from there. Spring Boot
+provides a default base configuration that you can include if you just
+want to set levels, e.g.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+	<include resource="org/springframework/boot/logging/logback/base.xml"/>	
+	<logger name="org.springframework.web" level="DEBUG"/>
+</configuration>
+```
+
+If you look at the default `logback.xml` in the spring-boot JAR you
+will see that it uses some useful System properties which the
+`LoggingSystem` takes care of creating for you. These are:
+
+* `${PID}` the current process ID
+* `${LOG_FILE}` if `logging.file` was set in Boot's external configuration
+* `${LOG_PATH` if `logging.path` was set (representing a directory for
+  log files to live in)
+  
+Spring Boot also provides some nice ANSI colour terminal output on a
+console (but not in a log file) using a custom Logback converter. See
+the default `base.xml` configuration for details.
+
+If Groovy is on the classpath you should be able to configure Logback
+with `logback.groovy` as well (it will be given preference if
+present).
+
+## Configure Log4j for Logging
+
+Spring Boot supports [Log4j](http://logging.apache.org/log4j/1.x/) for
+logging configuration, but it has to be on the classpath. If you are
+using the starter poms for assembling dependencies that means you have
+to exclude logback and then include log4j back. If you aren't using
+the starter poms then you need to provide `commons-logging` (at least)
+in addition to Log4j.
+
+The simplest path to using Log4j is probably through the starter poms,
+even though it requires some jiggling with excludes, e.g. in Maven:
+
+```xml
+<dependency>
+	<groupId>org.springframework.boot</groupId>
+	<artifactId>spring-boot-starter-web</artifactId>
+	<exclusions>
+		<exclusion>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-boot-starter-logging</artifactId>
+		</exclusion>
+	</exclusions>
+</dependency>
+<dependency>
+	<groupId>org.springframework.boot</groupId>
+	<artifactId>spring-boot-starter-log4j</artifactId>
+</dependency>
+```
+
+Note the use of the log4j starter to gather together the dependencies
+for common logging requirements (e.g. including having Tomcat use
+`java.util.logging` but configure the output using Log4j). See the
+[Actuator Log4j Sample]() for more detail and to see it in action.
+
 ## Test a Spring Boot Application
 
 A Spring Boot application is just a Spring `ApplicationContext` so

spring-boot-samples/pom.xml

@@ -15,6 +15,7 @@
 	</properties>
 	<modules>
 		<module>spring-boot-sample-actuator</module>
+		<module>spring-boot-sample-actuator-log4j</module>
 		<module>spring-boot-sample-actuator-ui</module>
 		<module>spring-boot-sample-amqp</module>
 		<module>spring-boot-sample-aop</module>

spring-boot-samples/spring-boot-sample-actuator-log4j/README.md

@@ -0,0 +1,21 @@
+# Spring Boot Actuator Sample
+
+You can build this sample using Maven (>3) or Gradle (1.6). 
+
+With Maven:
+
+```
+$ mvn package
+$ java -jar target/*.jar
+```
+
+Then access the app via a browser (or curl) on http://localhost:8080 (the user name is "user" and look at the INFO log output for the password to login).
+
+With gradle:
+
+```
+$ gradle build
+$ java -jar build/libs/*.jar
+```
+
+The gradle build contains an intentionally odd configuration to exclude the security dependencies from the executable JAR. So the app run like this behaves differently than the one run from the Maven-built JAR file. See comments in the `build.gradle` for details.

spring-boot-samples/spring-boot-sample-actuator-log4j/pom.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<parent>
+		<!-- Your own application should inherit from spring-boot-starter-parent -->
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-samples</artifactId>
+		<version>0.5.0.BUILD-SNAPSHOT</version>
+	</parent>
+	<artifactId>spring-boot-sample-actuator-log4j</artifactId>
+	<packaging>jar</packaging>
+	<properties>
+		<main.basedir>${basedir}/../..</main.basedir>
+	</properties>
+	<dependencies>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-boot-starter-actuator</artifactId>
+			<exclusions>
+				<exclusion>
+					<groupId>${project.groupId}</groupId>
+					<artifactId>spring-boot-starter-logging</artifactId>
+				</exclusion>
+			</exclusions>
+		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-boot-starter-web</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>${project.groupId}</groupId>
+			<artifactId>spring-boot-starter-log4j</artifactId>
+		</dependency>
+	</dependencies>
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-maven-plugin</artifactId>
+			</plugin>
+		</plugins>
+	</build>
+</project>

spring-boot-samples/spring-boot-sample-actuator-log4j/src/main/java/org/springframework/boot/sample/actuator/log4j/HelloWorldService.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2012-2013 the original author or authors.
+ *
+ * Licensed 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.springframework.boot.sample.actuator.log4j;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+
+@Component
+public class HelloWorldService {
+
+	@Autowired
+	private ServiceProperties configuration;
+
+	public String getHelloMessage() {
+		return "Hello " + this.configuration.getName();
+	}
+
+}

spring-boot-samples/spring-boot-sample-actuator-log4j/src/main/java/org/springframework/boot/sample/actuator/log4j/SampleActuatorApplication.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2012-2013 the original author or authors.
+ *
+ * Licensed 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.springframework.boot.sample.actuator.log4j;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@EnableAutoConfiguration
+@EnableConfigurationProperties
+@ComponentScan
+public class SampleActuatorApplication {
+
+	public static void main(String[] args) throws Exception {
+		SpringApplication.run(SampleActuatorApplication.class, args);
+	}
+
+}

spring-boot-samples/spring-boot-sample-actuator-log4j/src/main/java/org/springframework/boot/sample/actuator/log4j/SampleController.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2012-2013 the original author or authors.
+ *
+ * Licensed 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.springframework.boot.sample.actuator.log4j;
+
+import java.util.Collections;
+import java.util.Map;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.ResponseBody;
+
+@Controller
+public class SampleController {
+
+	@Autowired
+	private HelloWorldService helloWorldService;
+
+	@RequestMapping("/")
+	@ResponseBody
+	public Map<String, String> helloWorld() {
+		return Collections.singletonMap("message",
+				this.helloWorldService.getHelloMessage());
+	}
+
+	@RequestMapping("/foo")
+	@ResponseBody
+	public String foo() {
+		throw new IllegalArgumentException("Server error");
+	}
+}

spring-boot-samples/spring-boot-sample-actuator-log4j/src/main/java/org/springframework/boot/sample/actuator/log4j/ServiceProperties.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2012-2013 the original author or authors.
+ *
+ * Licensed 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.springframework.boot.sample.actuator.log4j;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@ConfigurationProperties(name = "service", ignoreUnknownFields = false)
+@Component
+public class ServiceProperties {
+
+	private String name = "World";
+
+	public String getName() {
+		return this.name;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+
+}

spring-boot-samples/spring-boot-sample-actuator-log4j/src/main/resources/application.properties

@@ -0,0 +1,17 @@
+logging.file: /tmp/logs/app.log
+management.port: 8080
+management.address: 127.0.0.1
+endpoints.shutdown.enabled: true
+server.port: 8080
+server.tomcat.basedir: target/tomcat
+server.tomcat.access_log_pattern: %h %t "%r" %s %b
+security.require_ssl: false
+service.name: Phil
+shell.ssh.enabled: true
+shell.ssh.port: 2222
+#shell.telnet.enabled: false
+#shell.telnet.port: 1111
+shell.auth: spring
+#shell.auth: key
+#shell.auth.key.path: ${user.home}/test/id_rsa.pub.pem
+#shell.auth: simple

spring-boot-samples/spring-boot-sample-actuator-log4j/src/main/resources/log4j.properties

@@ -0,0 +1,14 @@
+log4j.rootCategory=INFO, CONSOLE
+
+PID=????
+LOG_PATTERN=[%d{yyyy-MM-dd HH:mm:ss.SSS}] log4j%X{context} - ${PID} %5p [%t] --- %c{1}: %m%n
+
+# CONSOLE is set to be a ConsoleAppender using a PatternLayout.
+log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
+log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
+log4j.appender.CONSOLE.layout.ConversionPattern=${LOG_PATTERN}
+
+log4j.category.org.hibernate.validator.internal.util.Version=WARN
+log4j.category.org.apache.coyote.http11.Http11NioProtocol=WARN
+log4j.category.org.apache.tomcat.util.net.NioSelectorPool=WARN
+log4j.category.org.apache.catalina.startup.DigesterFactory=ERROR

spring-boot-samples/spring-boot-sample-actuator-log4j/src/test/java/org/springframework/boot/sample/actuator/log4j/SampleActuatorApplicationTests.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2012-2013 the original author or authors.
+ *
+ * Licensed 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.springframework.boot.sample.actuator.log4j;
+
+import static org.junit.Assert.assertEquals;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.springframework.boot.SpringApplication;
+import org.springframework.context.ConfigurableApplicationContext;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.client.ClientHttpResponse;
+import org.springframework.web.client.DefaultResponseErrorHandler;
+import org.springframework.web.client.RestTemplate;
+
+/**
+ * Basic integration tests for service demo application.
+ * 
+ * @author Dave Syer
+ */
+public class SampleActuatorApplicationTests {
+
+	private static ConfigurableApplicationContext context;
+
+	@BeforeClass
+	public static void start() throws Exception {
+		Future<ConfigurableApplicationContext> future = Executors
+				.newSingleThreadExecutor().submit(
+						new Callable<ConfigurableApplicationContext>() {
+							@Override
+							public ConfigurableApplicationContext call() throws Exception {
+								return SpringApplication
+										.run(SampleActuatorApplication.class);
+							}
+						});
+		context = future.get(60, TimeUnit.SECONDS);
+	}
+
+	@AfterClass
+	public static void stop() {
+		if (context != null) {
+			context.close();
+		}
+	}
+
+	@Test
+	public void testHome() throws Exception {
+		@SuppressWarnings("rawtypes")
+		ResponseEntity<Map> entity = getRestTemplate().getForEntity(
+				"http://localhost:8080", Map.class);
+		assertEquals(HttpStatus.OK, entity.getStatusCode());
+		@SuppressWarnings("unchecked")
+		Map<String, Object> body = entity.getBody();
+		assertEquals("Hello Phil", body.get("message"));
+	}
+
+
+	private RestTemplate getRestTemplate() {
+		RestTemplate restTemplate = new RestTemplate();
+		restTemplate.setErrorHandler(new DefaultResponseErrorHandler() {
+			@Override
+			public void handleError(ClientHttpResponse response) throws IOException {
+			}
+		});
+		return restTemplate;
+
+	}
+
+}

spring-boot-samples/spring-boot-sample-actuator/pom.xml

@@ -19,8 +19,8 @@
 			<artifactId>spring-boot-starter-actuator</artifactId>
 			<exclusions>
 				<exclusion>
-					<groupId>ch.qos.logback</groupId>
-					<artifactId>logback-classic</artifactId>
+					<groupId>${project.groupId}</groupId>
+					<artifactId>spring-boot-starter-logging</artifactId>
 				</exclusion>
 			</exclusions>
 		</dependency>
@@ -73,12 +73,8 @@
 			</activation>
 			<dependencies>
 				<dependency>
-					<groupId>org.apache.tomcat.embed</groupId>
-					<artifactId>tomcat-embed-core</artifactId>
-				</dependency>
-				<dependency>
-					<groupId>org.apache.tomcat.embed</groupId>
-					<artifactId>tomcat-embed-logging-juli</artifactId>
+					<groupId>org.springframework.boot</groupId>
+					<artifactId>spring-boot-starter-tomcat</artifactId>
 				</dependency>
 			</dependencies>
 		</profile>
@@ -117,12 +113,8 @@
 			</activation>
 			<dependencies>
 				<dependency>
-					<groupId>org.slf4j</groupId>
-					<artifactId>slf4j-log4j12</artifactId>
-				</dependency>
-				<dependency>
-					<groupId>log4j</groupId>
-					<artifactId>log4j</artifactId>
+					<groupId>org.springframework.boot</groupId>
+					<artifactId>spring-boot-starter-log4j</artifactId>
 				</dependency>
 			</dependencies>
 		</profile>
@@ -133,8 +125,8 @@
 			</activation>
 			<dependencies>
 				<dependency>
-					<groupId>ch.qos.logback</groupId>
-					<artifactId>logback-classic</artifactId>
+					<groupId>org.springframework.boot</groupId>
+					<artifactId>spring-boot-starter-logging</artifactId>
 				</dependency>
 			</dependencies>
 		</profile>

spring-boot-starters/pom.xml

@@ -23,6 +23,7 @@
 		<module>spring-boot-starter-jdbc</module>
 		<module>spring-boot-starter-jetty</module>
 		<module>spring-boot-starter-logging</module>
+		<module>spring-boot-starter-log4j</module>
 		<module>spring-boot-starter-mobile</module>
 		<module>spring-boot-starter-actuator</module>
 		<module>spring-boot-starter-parent</module>

spring-boot-starters/spring-boot-starter-actuator/pom.xml

@@ -23,9 +23,5 @@
 			<artifactId>spring-boot-actuator</artifactId>
 			<version>${project.version}</version>
 		</dependency>
-		<dependency>
-			<groupId>org.slf4j</groupId>
-			<artifactId>log4j-over-slf4j</artifactId>
-		</dependency>
 	</dependencies>
 </project>

spring-boot-starters/spring-boot-starter-log4j/pom.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<parent>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-starters</artifactId>
+		<version>0.5.0.BUILD-SNAPSHOT</version>
+	</parent>
+	<artifactId>spring-boot-starter-log4j</artifactId>
+	<packaging>jar</packaging>
+	<properties>
+		<main.basedir>${basedir}/../..</main.basedir>
+	</properties>
+	<dependencies>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>jcl-over-slf4j</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>jul-to-slf4j</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>slf4j-log4j12</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>log4j</groupId>
+			<artifactId>log4j</artifactId>
+		</dependency>
+	</dependencies>
+</project>

spring-boot-starters/spring-boot-starter-log4j/src/main/resources/META-INF/spring.provides

@@ -0,0 +1 @@
+provides: logback-classic,jcl-over-slf4j,jul-to-slf4j

spring-boot-starters/spring-boot-starter-logging/pom.xml

@@ -21,6 +21,10 @@
 			<groupId>org.slf4j</groupId>
 			<artifactId>jul-to-slf4j</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>log4j-over-slf4j</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>ch.qos.logback</groupId>
 			<artifactId>logback-classic</artifactId>

spring-boot-starters/spring-boot-starter-parent/pom.xml

@@ -94,6 +94,11 @@
 				<artifactId>spring-boot-starter-logging</artifactId>
 				<version>${spring-boot.version}</version>
 			</dependency>
+			<dependency>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-starter-log4j</artifactId>
+				<version>${spring-boot.version}</version>
+			</dependency>
 			<dependency>
 				<groupId>org.springframework.boot</groupId>
 				<artifactId>spring-boot-starter-mobile</artifactId>