Update documentation and tests

docs/source/manual/configuration.rst

@@ -69,7 +69,7 @@ GZip
 .. code-block:: yaml
 
     server:
-      gzip: 
+      gzip:
         bufferSize: 8KiB
 
 
@@ -105,13 +105,15 @@ Request Log
 .. code-block:: yaml
 
     server:
-      requestLog: 
-        timeZone: UTC
+      requestLog:
+        - type: SLF4J
+          timeZone: UTC
 
 
 ====================== ================ ===========
 Name                   Default          Description
 ====================== ================ ===========
+type                   SLF4J            The request log type. SLF4J or Logback-Access.
 timeZone               UTC              The time zone to which request timestamps will be converted.
 appenders              console appender The set of AppenderFactory appenders to which requests will be logged.
                                         *TODO* See logging/appender refs for more info
@@ -224,7 +226,7 @@ Name                      Default                   Description
 applicationConnectors     An `HTTP connector`_      A set of :ref:`connectors <man-configuration-connectors>` which will
                           listening on port 8080.   handle application requests.
 adminConnectors           An `HTTP connector`_      An `HTTP connector`_ listening on port 8081.
-                          listening on port 8081.   A set of :ref:`connectors <man-configuration-connectors>` which will 
+                          listening on port 8081.   A set of :ref:`connectors <man-configuration-connectors>` which will
                                                     handle admin requests.
 adminMinThreads           1                         The minimum number of threads to use for admin requests.
 adminMaxThreads           64                        The maximum number of threads to use for admin requests.
@@ -246,7 +248,7 @@ HTTP
 ----
 
 .. code-block:: yaml
-    
+
     # Extending from the default server configuration
     server:
       applicationConnectors:
@@ -300,7 +302,7 @@ idleTimeout              30 seconds          The maximum idle time for a connect
                                              or when waiting for a new message to be sent on a connection.
                                              This value is interpreted as the maximum time between some progress being made on the
                                              connection. So if a single byte is read or written, then the timeout is reset.
-minBufferPoolSize        64 bytes            The minimum size of the buffer pool. 
+minBufferPoolSize        64 bytes            The minimum size of the buffer pool.
 bufferPoolIncrement      1KiB                The increment by which the buffer pool should be increased.
 maxBufferPoolSize        64KiB               The maximum size of the buffer pool.
 acceptorThreads          # of CPUs/2         The number of worker threads dedicated to accepting connections.
@@ -327,7 +329,7 @@ HTTPS
 Extends the attributes that are available to the :ref:`HTTP connector <man-configuration-http>`
 
 .. code-block:: yaml
-    
+
     # Extending from the default server configuration
     server:
       applicationConnectors:
@@ -337,14 +339,14 @@ Extends the attributes that are available to the :ref:`HTTP connector <man-confi
           keyStorePath: /path/to/file
           keyStorePassword: changeit
           keyStoreType: JKS
-          keyStoreProvider: 
+          keyStoreProvider:
           trustStorePath: /path/to/file
           trustStorePassword: changeit
           trustStoreType: JKS
-          trustStoreProvider: 
+          trustStoreProvider:
           keyManagerPassword: changeit
           needClientAuth: false
-          wantClientAuth: 
+          wantClientAuth:
           certAlias: <alias>
           crlPath: /path/to/file
           enableCRLDP: false
@@ -395,8 +397,8 @@ excludedProtocols                (none)              A list of protocols (e.g.,
 supportedCipherSuites            (none)              A list of cipher suites (e.g., ``TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256``) which
                                                      are supported. All other cipher suites will be refused
 excludedCipherSuites             (none)              A list of cipher suites (e.g., ``TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256``) which
-                                                     are excluded. These cipher suites will be refused and exclusion takes higher 
-                                                     precedence than inclusion, such that if a cipher suite is listed in 
+                                                     are excluded. These cipher suites will be refused and exclusion takes higher
+                                                     precedence than inclusion, such that if a cipher suite is listed in
                                                      ``supportedCipherSuites`` and ``excludedCipherSuites``, the cipher suite will be
                                                      excluded. To verify that the proper cipher suites are being whitelisted and
                                                      blacklisted, it is recommended to use the tool `sslyze`_.
@@ -550,6 +552,7 @@ Name                   Default      Description
 type                   REQUIRED     The appender type. Must be ``console``.
 threshold              ALL          The lowest level of events to print to the console.
 timeZone               UTC          The time zone to which event timestamps will be converted.
+                                    Will be ignored if a logFormat is supplied.
 target                 stdout       The name of the standard stream to which events will be written.
                                     Can be ``stdout`` or ``stderr``.
 logFormat              default      The Logback pattern with which events will be formatted. See
@@ -588,10 +591,11 @@ threshold                    ALL          The lowest level of events to write to
 archive                      true         Whether or not to archive old events in separate files.
 archivedLogFilenamePattern   (none)       Required if ``archive`` is ``true``.
                                           The filename pattern for archived files. ``%d`` is replaced with the date in ``yyyy-MM-dd`` form,
-                                          and the fact that it ends with ``.gz`` indicates the file will be gzipped as it's archived.                                
+                                          and the fact that it ends with ``.gz`` indicates the file will be gzipped as it's archived.
                                           Likewise, filename patterns which end in ``.zip`` will be filled as they are archived.
 archivedFileCount            5            The number of archived files to keep. Must be between ``1`` and ``50``.
 timeZone                     UTC          The time zone to which event timestamps will be converted.
+                                          Will be ignored if a logFormat is supplied.
 logFormat                    default      The Logback pattern with which events will be formatted. See
                                           the Logback_ documentation for details.
 ============================ ===========  ==================================================================================================
@@ -802,11 +806,11 @@ Name                   Default          Description
 ====================== ===============  ====================================================================================================
 host                   localhost        The hostname (or group) of the Ganglia server(s) to report to.
 port                   8649             The port of the Ganglia server(s) to report to.
-mode                   unicast          The UDP addressing mode to announce the metrics with. One of ``unicast`` 
+mode                   unicast          The UDP addressing mode to announce the metrics with. One of ``unicast``
                                         or ``multicast``.
 ttl                    1                The time-to-live of the UDP packets for the announced metrics.
 uuid                   (none)           The UUID to tag announced metrics with.
-spoof                  (none)           The hostname and port to use instead of this nodes for the announced metrics. 
+spoof                  (none)           The hostname and port to use instead of this nodes for the announced metrics.
                                         In the format ``hostname:port``.
 tmax                   60               The tmax value to announce metrics with.
 dmax                   0                The dmax value to announce metrics with.
@@ -993,7 +997,7 @@ TLS
 Name                         Default            Description
 ===========================  =================  ============================================================================================================================
 protocol                     TLSv1.2            The default protocol the client will attempt to use during the SSL Handshake.
-                                                See 
+                                                See
                                                 `here <http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#SSLContext>`_ for more information.
 verifyHostname               true               Whether to verify the hostname of the server against the hostname presented in the server certificate.
 keyStorePath                 (none)             The path to the Java key store which contains the client certificate and private key.

dropwizard-jetty/src/main/java/io/dropwizard/jetty/AsyncAccessEventAppenderFactory.java

@@ -4,7 +4,16 @@
 import ch.qos.logback.core.AsyncAppenderBase;
 import io.dropwizard.logging.AsyncAppenderFactory;
 
+/**
+ * An implementation of {@link AsyncAppenderFactory} for {@link IAccessEvent}.
+ */
 public class AsyncAccessEventAppenderFactory implements AsyncAppenderFactory<IAccessEvent> {
+
+    /**
+     * Creates an {@link AsyncAppenderFactory} of type {@link IAccessEvent} that prepares events
+     * for deferred processing
+     * @return the {@link AsyncAppenderFactory}
+     */
     @Override
     public AsyncAppenderBase<IAccessEvent> build() {
         return new AsyncAppenderBase<IAccessEvent>() {

dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLayout.java

@@ -0,0 +1,21 @@
+package io.dropwizard.jetty;
+
+import ch.qos.logback.access.PatternLayout;
+import ch.qos.logback.core.Context;
+
+/**
+ * A base layout for Logback Access request logs.
+ * <ul>
+ *     <li>Extends {@link PatternLayout}.</li>
+ *     <li>Disables pattern headers.</li>
+ * </ul>
+ */
+public class LogbackAccessRequestLayout extends PatternLayout {
+
+    public LogbackAccessRequestLayout(Context context, String pattern) {
+        setOutputPatternAsHeader(false);
+
+        setPattern(pattern);
+        setContext(context);
+    }
+}

dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLog.java → dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLog.java

@@ -6,9 +6,9 @@
  * The Dropwizard request log uses logback-access, but we override it to remove the requirement for logback-access.xml
  * based configuration.
  */
-public class DropwizardRequestLog extends RequestLogImpl {
+public class LogbackAccessRequestLog extends RequestLogImpl {
     @Override
     public void configure() {
-        setName("DropwizardRequestLog");
+        setName("LogbackAccessRequestLog");
     }
 }

dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLogFactory.java

@@ -1,8 +1,5 @@
 package io.dropwizard.jetty;
 
-import java.util.Optional;
-import java.util.TimeZone;
-
 import javax.validation.Valid;
 import javax.validation.constraints.NotNull;
 
@@ -26,31 +23,20 @@
 import io.dropwizard.logging.filter.NullFilterFactory;
 
 /**
- * A factory for creating {@link RequestLog} instances.
+ * A factory for creating {@link LogbackAccessRequestLog} instances.
  * <p/>
  * <b>Configuration Parameters:</b>
  * <table>
- * <tr>
- * <td>Name</td>
- * <td>Default</td>
- * <td>Description</td>
- * </tr>
- * <tr>
- * <td>{@code timeZone}</td>
- * <td>UTC</td>
- * <td>The time zone to which request timestamps will be converted, if using the default {@code logFormat}.</td>
- * </tr>
- * <tr>
- * <td>{@code logFormat}</td>
- * <td>HTTP [%t{dd/MMM/yyyy:HH:mm:ss Z,UTC}] %h %l %u "%r" %s %b "%i{Referer}" "%i{User-Agent}"</td>
- * <td>The Logback pattern with which events will be formatted. See
- * <a href="http://logback.qos.ch/manual/layouts.html#logback-access">the Logback documentation</a> for details.</td>
- * </tr>
- * <tr>
- * <td>{@code appenders}</td>
- * <td>a default {@link ConsoleAppenderFactory console} appender</td>
- * <td>The set of {@link AppenderFactory appenders} to which requests will be logged.</td>
- * </tr>
+ *     <tr>
+ *         <td>Name</td>
+ *         <td>Default</td>
+ *         <td>Description</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code appenders}</td>
+ *         <td>a default {@link ConsoleAppenderFactory console} appender</td>
+ *         <td>The set of {@link AppenderFactory appenders} to which requests will be logged.</td>
+ *     </tr>
  * </table>
  */
 @JsonTypeName("logback-access")
@@ -83,13 +69,13 @@ public RequestLog build(String name) {
 
         final LoggerContext context = logger.getLoggerContext();
 
-        final DropwizardRequestLog requestLog = new DropwizardRequestLog();
+        final LogbackAccessRequestLog requestLog = new LogbackAccessRequestLog();
 
         final FilterFactory<IAccessEvent> thresholdFilterFactory = new NullFilterFactory<>();
         final AsyncAppenderFactory<IAccessEvent> asyncAppenderFactory = new AsyncAccessEventAppenderFactory();
 
         for (AppenderFactory<IAccessEvent> output : appenders) {
-            final Layout<IAccessEvent> layout = new DropwizardRequestLayout(context, output.getLogFormat());
+            final Layout<IAccessEvent> layout = new LogbackAccessRequestLayout(context, output.getLogFormat());
             layout.start();
             requestLog.addAppender(output.build(context, name, layout, thresholdFilterFactory, asyncAppenderFactory));
         }

dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLayoutTest.java

@@ -0,0 +1,21 @@
+package io.dropwizard.jetty;
+
+import ch.qos.logback.core.Context;
+import org.junit.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+
+public class LogbackAccessRequestLayoutTest {
+
+    @Test
+    public void outputPatternAsHeaderIsFalse() {
+        final Context context = mock(Context.class);
+        final String pattern = "pattern";
+        final LogbackAccessRequestLayout layout = new LogbackAccessRequestLayout(context, pattern);
+
+        assertThat(layout.isOutputPatternAsHeader()).isFalse();
+        assertThat(layout.getContext()).isEqualTo(context);
+        assertThat(layout.getPattern()).isEqualTo(pattern);
+    }
+}

dropwizard-jetty/src/test/java/io/dropwizard/jetty/DropwizardRequestLogTest.java → dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLogTest.java

@@ -19,11 +19,11 @@
 import ch.qos.logback.access.spi.IAccessEvent;
 import ch.qos.logback.core.Appender;
 
-public class DropwizardRequestLogTest {
+public class LogbackAccessRequestLogTest {
 
     @SuppressWarnings("unchecked")
     private final Appender<IAccessEvent> appender = mock(Appender.class);
-    private final DropwizardRequestLog requestLog = new DropwizardRequestLog();
+    private final LogbackAccessRequestLog requestLog = new LogbackAccessRequestLog();
 
     private final Request request = mock(Request.class);
     private final Response response = mock(Response.class);

dropwizard-logging/src/main/java/io/dropwizard/logging/AbstractAppenderFactory.java

@@ -33,6 +33,19 @@
  *         <td>The minimum event level the appender will handle.</td>
  *     </tr>
  *     <tr>
+ *         <td>{@code logFormat}</td>
+ *         <td>(none)</td>
+ *         <td>An appender-specific log format.</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code timeZone}</td>
+ *         <td>{@code UTC}</td>
+ *         <td>
+ *             The time zone to which event timestamps will be converted.
+ *             Ignored if logFormat is supplied.
+ *         </td>
+ *     </tr>
+ *     <tr>
  *         <td>{@code queueSize}</td>
  *         <td>{@link AsyncAppenderBase}</td>
  *         <td>The maximum capacity of the blocking queue.</td>

dropwizard-logging/src/main/java/io/dropwizard/logging/AppenderFactory.java

@@ -25,11 +25,14 @@
 @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
 public interface AppenderFactory<E> extends Discoverable {
     /**
-     * Given a Logback context, an application name, and a layout, build a new appender.
+     * Given a Logback context, an application name, a layout,
+     * a thresholdFilterFactory, and an asyncAppenderFactory build a new appender.
      *
      * @param context         the Logback context
      * @param applicationName the application name
      * @param layout          the layout for logging
+     * @param thresholdFilterFactory the factory for the threshold filter
+     * @param asyncAppenderFactory   the factory for the async appender
      * @return a new, started {@link Appender}
      */
     Appender<E> build(LoggerContext context,
@@ -38,5 +41,8 @@ Appender<E> build(LoggerContext context,
                                   FilterFactory<E> thresholdFilterFactory,
                                   AsyncAppenderFactory<E> asyncAppenderFactory);
 
+    /**
+     * @return the log format of this AppenderFactory
+     */
     String getLogFormat();
 }

dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncAppenderFactory.java

@@ -2,6 +2,15 @@
 
 import ch.qos.logback.core.AsyncAppenderBase;
 
+/**
+ * Factory used to create an {@link AsyncAppenderBase} of type E
+ * @param <E> The type of log event
+ */
 public interface AsyncAppenderFactory<E> {
+
+    /**
+     * Creates an {@link AsyncAppenderBase} of type E
+     * @return a new {@link AsyncAppenderBase}
+     */
     AsyncAppenderBase<E> build();
 }

dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncLoggingEventAppenderFactory.java

@@ -4,7 +4,15 @@
 import ch.qos.logback.classic.spi.ILoggingEvent;
 import ch.qos.logback.core.AsyncAppenderBase;
 
+/**
+ * An implementation of {@link AsyncAppenderFactory} for {@link ILoggingEvent}.
+ */
 public class AsyncLoggingEventAppenderFactory implements AsyncAppenderFactory<ILoggingEvent> {
+
+    /**
+     * Creates an {@link AsyncAppenderFactory} of type {@link ILoggingEvent}
+     * @return the {@link AsyncAppenderFactory}
+     */
     @Override
     public AsyncAppenderBase<ILoggingEvent> build() {
         return new AsyncAppender();