Issue #560 JUL fixes (#562)

* JUL Property Resource Logic fix

Adjusting the loading behavior of the esapi-java-logging.properties file
to account for a possible null stream resolution.
Updating the error handling from system error output to throwing
ConfigurationExceptions.
Tests updated accordingly

* JUL Default Logging configuration

Adding a default version of esapi-java-logging.properties to the
configuration directory.

* JUL Documentation updates

Noting the property file requirement and resource location in the class
java doc.

* Property Comment Updates

Supplying a more accurate description of the effect of Logger.ClientInfo

* Property Comment Updates

Supplying a more accurate description of the effect of Logger.ClientInfo

Author: jeremiahjstacey

configuration/esapi/ESAPI.properties

@@ -394,7 +394,7 @@ Logger.LogFileName=ESAPI_logging_file
 Logger.MaxLogFileSize=10000000
 # Determines whether ESAPI should log the user info.
 Logger.UserInfo=true
-# Determines whether ESAPI should log the app info.
+# Determines whether ESAPI should log the session id and client IP.
 Logger.ClientInfo=true
 
 #===========================================================================

configuration/esapi/esapi-java-logging.properties

@@ -0,0 +1,6 @@
+handlers= java.util.logging.ConsoleHandler
+.level= INFO
+java.util.logging.ConsoleHandler.level = INFO
+java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+java.util.logging.SimpleFormatter.format=[%1$tF %1$tT] [%3$-7s] %5$s %n
+#https://www.logicbig.com/tutorials/core-java-tutorial/logging/customizing-default-format.html

src/main/java/org/owasp/esapi/logging/java/JavaLogFactory.java

@@ -26,6 +26,7 @@
 import org.owasp.esapi.LogFactory;
 import org.owasp.esapi.Logger;
 import org.owasp.esapi.codecs.HTMLEntityCodec;
+import org.owasp.esapi.errors.ConfigurationException;
 import org.owasp.esapi.logging.appender.LogAppender;
 import org.owasp.esapi.logging.appender.LogPrefixAppender;
 import org.owasp.esapi.logging.cleaning.CodecLogScrubber;
@@ -35,6 +36,10 @@
 import org.owasp.esapi.reference.DefaultSecurityConfiguration;
 /**
  * LogFactory implementation which creates JAVA supporting Loggers.
+ * 
+ * This implementation requires that a file named 'esapi-java-logging.properties' exists on the classpath.
+ * <br>
+ * A default file implementation is available in the configuration jar on GitHub under the 'Releases'
  *
  */
 public class JavaLogFactory implements LogFactory {
@@ -86,9 +91,12 @@ public class JavaLogFactory implements LogFactory {
          */
         try (InputStream stream = JavaLogFactory.class.getClassLoader().
                 getResourceAsStream("esapi-java-logging.properties")) {
+            if (stream == null) {
+                throw new ConfigurationException("Unable to locate resource: esapi-java-logging.properties");
+            }
             logManager.readConfiguration(stream);
         } catch (IOException ioe) {
-            System.err.print(new IOException("Failed to load esapi-java-logging.properties.", ioe));        	
+            throw new ConfigurationException("Failed to load esapi-java-logging.properties.", ioe);        	
         }
     }
 

src/test/java/org/owasp/esapi/logging/java/JavaLogFactoryTest.java

@@ -14,24 +14,21 @@
  */
 package org.owasp.esapi.logging.java;
 
-import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertTrue;
-
 import java.io.IOException;
 import java.io.InputStream;
-import java.io.OutputStream;
-import java.io.PrintStream;
 import java.util.List;
 import java.util.logging.LogManager;
 
+import org.hamcrest.CustomMatcher;
 import org.junit.Assert;
 import org.junit.Rule;
 import org.junit.Test;
+import org.junit.rules.ExpectedException;
 import org.junit.rules.TestName;
 import org.junit.runner.RunWith;
 import org.mockito.ArgumentCaptor;
-import org.mockito.Mockito;
 import org.owasp.esapi.Logger;
+import org.owasp.esapi.errors.ConfigurationException;
 import org.owasp.esapi.logging.appender.LogAppender;
 import org.owasp.esapi.logging.appender.LogPrefixAppender;
 import org.owasp.esapi.logging.cleaning.CodecLogScrubber;
@@ -47,9 +44,12 @@
 public class JavaLogFactoryTest {
     @Rule
     public TestName testName = new TestName();
+    
+    @Rule
+    public ExpectedException exEx = ExpectedException.none();
 
     @Test
-    public void testIOExceptionOnMissingConfiguration() throws Exception {
+    public void testConfigurationExceptionOnMissingConfiguration() throws Exception {
         final IOException originException = new IOException(testName.getMethodName());
 
         LogManager testLogManager = new LogManager() {
@@ -59,31 +59,17 @@ public void readConfiguration(InputStream ins) throws IOException, SecurityExcep
             }
         };
 
-        OutputStream nullOutputStream = new OutputStream() {
+        exEx.expectMessage("Failed to load esapi-java-logging.properties");
+        exEx.expect(ConfigurationException.class);
+       
+        exEx.expectCause(new CustomMatcher<Throwable>("Check for IOException") {
             @Override
-            public void write(int b) throws IOException {
-                //No Op
+            public boolean matches(Object item) {
+               return item instanceof IOException;
             }
-        };
-
-        ArgumentCaptor<Object> stdErrOut = ArgumentCaptor.forClass(Object.class);
-        PrintStream orig = System.err;
-        try (PrintStream errPrinter = new PrintStream(nullOutputStream)) {
-            PrintStream spyPrinter = PowerMockito.spy(errPrinter);
-            Mockito.doCallRealMethod().when(spyPrinter).print(stdErrOut.capture());
-            System.setErr(spyPrinter);
-
-            JavaLogFactory.readLoggerConfiguration(testLogManager);
-
-            Object writeData = stdErrOut.getValue();
-            assertTrue(writeData instanceof IOException);
-            IOException actual = (IOException) writeData;
-            assertEquals(originException, actual.getCause());
-            assertEquals("Failed to load esapi-java-logging.properties.", actual.getMessage());
-        } finally {
-            System.setErr(orig);
-        }
+        });
 
+        JavaLogFactory.readLoggerConfiguration(testLogManager);
     }
 
     @Test

src/test/resources/esapi/ESAPI.properties

@@ -426,7 +426,7 @@ Logger.LogFileName=ESAPI_logging_file
 Logger.MaxLogFileSize=10000000
 # Determines whether ESAPI should log the user info.
 Logger.UserInfo=true
-# Determines whether ESAPI should log the app info.
+# Determines whether ESAPI should log the session id and client IP.
 Logger.ClientInfo=true
 
 #===========================================================================