Initial fully-functional version of DispatcherAppender

.gitignore

@@ -0,0 +1,6 @@
+target
+bin
+.classpath
+.project
+.settings
+

README.md

@@ -1,7 +1,64 @@
 Log4j DispatcherAppender
 ========================
 
-A Log4j Appender that dispatches to a different Appender instance depending
-on the value of the NDC.
+A [Log4j](http://logging.apache.org/log4j/1.2) `Appender` that
+dispatches to a different `Appender` instance depending on the value
+of the [Nested Diagnostic
+Context](http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html).
+The delegate appender is copied and a single property is overriden
+(e.g. a file location) based on a layout pattern.  A typical use case
+would be directing logs to a different file based on the business data
+that are being processed.
+
+Note that adding an appender to an existing one cannot be done using
+the Log4j `PropertiesConfigurator` so you have to use XML or Java to
+configure a `DispatcherAppender`.
 
 License: Apache 2.0
+
+Usage
+-----
+
+Sample `log4j.xml`:
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
+
+    <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false">
+
+      <appender name="LOGGER" class="org.springframework.util.log4j.DispatcherAppender">
+        <param name="propertyName" value="file" />
+        <layout class="org.apache.log4j.PatternLayout">
+            <param name="ConversionPattern" value="target/logs/%x.log" />
+        </layout>
+        <appender-ref ref="FILE" />
+      </appender>
+
+      <appender name="FILE" class="org.apache.log4j.FileAppender">
+        <param name="file" value="target/logs/default.log" />
+        <layout class="org.apache.log4j.PatternLayout">
+            <param name="ConversionPattern" value="%5p: %m%n" />
+        </layout>
+      </appender>
+
+      <root>
+        <priority value="info" />
+        <appender-ref ref="LOGGER" />
+      </root>
+
+    </log4j:configuration>
+
+Application code:
+
+    logger.info("foo");
+    NDC.push("alt");
+    try {
+      logger.info("foo");
+    } finally {
+      NDC.clear();
+    }
+
+Result:
+
+    $ ls target/logs
+    default.log    alt.log

pom.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+	<modelVersion>4.0.0</modelVersion>
+	<groupId>org.springframework.samples</groupId>
+	<artifactId>log4j-utils</artifactId>
+	<version>1.0.0.BUILD-SNAPSHOT</version>
+	<properties>
+		<maven.test.failure.ignore>true</maven.test.failure.ignore>
+	</properties>
+	<profiles>
+		<profile>
+			<id>strict</id>
+			<properties>
+				<maven.test.failure.ignore>false</maven.test.failure.ignore>
+			</properties>
+		</profile>
+	</profiles>
+
+	<dependencies>
+		<dependency>
+			<groupId>junit</groupId>
+			<artifactId>junit</artifactId>
+			<version>4.8.2</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>log4j</groupId>
+			<artifactId>log4j</artifactId>
+			<version>1.2.14</version>
+			<scope>compile</scope>
+		</dependency>
+		<dependency>
+			<groupId>commons-io</groupId>
+			<artifactId>commons-io</artifactId>
+			<version>1.4</version>
+			<scope>test</scope>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<pluginManagement>
+			<plugins>
+				<plugin>
+					<artifactId>maven-assembly-plugin</artifactId>
+					<inherited>false</inherited>
+					<configuration>
+						<descriptorRefs>
+							<descriptorRef>project</descriptorRef>
+						</descriptorRefs>
+					</configuration>
+				</plugin>
+			</plugins>
+		</pluginManagement>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<configuration>
+					<source>1.5</source>
+					<target>1.5</target>
+				</configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<configuration>
+					<!--forkMode>pertest</forkMode -->
+					<includes>
+						<include>**/*Tests.java</include>
+					</includes>
+					<excludes>
+						<exclude>**/Abstract*.java</exclude>
+					</excludes>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+
+</project>