Log special (#451)

* Close issue #448

* Close issue #444. Delete deprecated decodeToObject() method and 2 related encodeObject() methods. General whitespace clean-up. Delete EncoderTest.testBase64decodToObject() method which is no longer relevant.

* Close issue #385.  Close issue #386.
NOTE: Was unwilling to comply with request in these 2 issues to make logSpecial()
'protected'. Could not do so without introducing potential security vulnerabilities.
However, since the intent of the user submitting these 2 GitHub issues was only to override
logSpecial() in order to completely suppress the output from them to stdout or stderr,
I have arranged it so that setting the System property
'org.owasp.esapi.logSpecial.discard' to 'true' will do exactly this...it will
suppress all output from logSpecial. (Also, the calls to System.err.println() and
System.out.println() have been replaced by calls to logSpecial(), which will log
to System.out if not suppressed. So the end result is all or nothing. I suspect
that most will keep the default behavior, which is to print to System.out rather
than suppressing all output.

Author: kwwall

src/main/java/org/owasp/esapi/configuration/AbstractPrioritizedPropertyLoader.java

@@ -44,13 +44,13 @@ public String name() {
     /**
      * Initializes properties object and fills it with data from configuration file.
      */
-    protected void initProperties() {
+    private void initProperties() {
         properties = new Properties();
         File file = new File(filename);
         if (file.exists() && file.isFile()) {
             loadPropertiesFromFile(file);
         } else {
-            System.err.println("Configuration file " + filename + " does not exist");
+            logSpecial("Configuration file " + filename + " does not exist");
         }
     }
 
@@ -59,4 +59,33 @@ protected void initProperties() {
      * @param file
      */
     protected abstract void loadPropertiesFromFile(File file);
+
+    /**
+     * Used to log errors to the console during the loading of the properties file itself. Can't use
+     * standard logging in this case, since the Logger may not be initialized yet. Output is sent to
+     * {@code PrintStream} {@code System.out}.  Output is discarded if the {@code System} property
+     * "org.owasp.esapi.logSpecial.discard" is set to {@code true}.
+     *
+     * @param msg The message to log to the console.
+     * @param t   Associated exception that was caught.
+     */
+    protected final void logSpecial(String msg, Throwable t) {
+        // Note: It is really distasteful to tie this class to DefaultSecurityConfiguration
+        //       like this, but the alternative is to move the logSpecial() and
+        //       logToStdout() some utilities class and that is even more
+        //       distasteful because it may encourage people to use these. -kwwall
+        org.owasp.esapi.reference.DefaultSecurityConfiguration.logToStdout(msg, t);
+    }
+
+    /**
+     * Used to log errors to the console during the loading of the properties file itself. Can't use
+     * standard logging in this case, since the Logger may not be initialized yet. Output is sent to
+     * {@code PrintStream} {@code System.out}.  Output is discarded if the {@code System} property
+     * "org.owasp.esapi.logSpecial.discard" is set to {@code true}.
+     *
+     * @param msg The message to log to the console.
+     */
+    protected final void logSpecial(String msg) {
+        logSpecial(msg, null);
+    }
 }

src/main/java/org/owasp/esapi/configuration/StandardEsapiPropertyLoader.java

@@ -90,13 +90,13 @@ protected void loadPropertiesFromFile(File file) {
             input = new FileInputStream(file);
             properties.load(input);
         } catch (IOException ex) {
-            System.err.println("Loading " + file.getName() + " via file I/O failed. Exception was: " + ex);
+            logSpecial("Loading " + file.getName() + " via file I/O failed.", ex);
         } finally {
             if (input != null) {
                 try {
                     input.close();
                 } catch (IOException e) {
-                    System.err.println("Could not close stream");
+                    logSpecial("Could not close stream");
                 }
             }
         }

src/main/java/org/owasp/esapi/reference/DefaultSecurityConfiguration.java

@@ -153,6 +153,18 @@ public static SecurityConfiguration getInstance() {
     public static final String VALIDATION_PROPERTIES_MULTIVALUED = "Validator.ConfigurationFile.MultiValued";
     public static final String ACCEPT_LENIENT_DATES = "Validator.AcceptLenientDates";
 
+    /**
+     * Special {@code System} property that, if set to {@code true}, will
+     * disable logging from {@code DefaultSecurityConfiguration.logToStdout()}
+     * methods, which is called from various {@code logSpecial()} methods.
+     * @see org.owasp.esapi.reference.DefaultSecurityConfiguration#logToStdout(String msg, Throwable t)
+     * @see org.owasp.esapi.reference.DefaultSecurityConfiguration#logToStdout(String msg)
+     */
+    public static final String DISCARD_LOGSPECIAL = "org.owasp.esapi.logSpecial.discard";
+
+    // We assume that this does not change in the middle of processing the
+    // ESAPI.properties files and thus only fetch its value once.
+    private static final String logSpecialValue = System.getProperty(DISCARD_LOGSPECIAL, "false");
 
 
     /**
@@ -702,34 +714,64 @@ private Properties loadConfigurationFromClasspath(String fileName) throws Illega
 		return result;
 	}
 
+    /**
+     * Log to standard output (i.e., {@code System.out}. This method is
+     * synchronized to reduce the possibility of interleaving the message
+     * output (since the {@code System.out} {@code PrintStream} is buffered)
+     * it invoked from multiple threads. Output is discarded if the
+     * {@code System} property "org.owasp.esapi.logSpecial.discard" is set to
+     * {@code true}.
+     *
+     * @param msg   Message to be logged.
+     * @param t     Associated exception that was caught. The class name and
+     *              exception message is also logged.
+     * @see #logToStdout(String msg)
+     */
+    public final synchronized static void logToStdout(String msg, Throwable t) {
+     // Note that this class was made final because it is called from this class'
+     // CTOR and we want to prohibit someone from <i>easily</i> doing sneaky
+     // things like subclassing this class and inserting a malicious code as a
+     // shim. Of course, really in hindsight, this entire class should have been
+     // declared 'final', but doing so at this point would likely break someone's
+     // code, including possibly some of our own test code. But since this is a
+     // new method, we can get away with it here.
+        boolean discard = logSpecialValue.trim().equalsIgnoreCase("true");
+        if ( discard ) {
+            return; // Output is discarded!
+        }
+        if ( t == null ) {
+            System.out.println("ESAPI: " + msg);
+        } else {
+            System.out.println("ESAPI: " + msg +
+                               ". Caught " + t.getClass().getName() +
+                               "; exception message was: " + t);
+        }
+    }
+    
     /**
      * Used to log errors to the console during the loading of the properties file itself. Can't use
      * standard logging in this case, since the Logger may not be initialized yet. Output is sent to
-     * {@code PrintStream} {@code System.out}.
+     * {@code PrintStream} {@code System.out}.  Output is discarded if the {@code System} property
+     * "org.owasp.esapi.logSpecial.discard" is set to {@code true}.
      *
      * @param message The message to send to the console.
      * @param e The error that occurred. (This value printed via {@code e.toString()}.)
      */
     private void logSpecial(String message, Throwable e) {
-    	StringBuffer msg = new StringBuffer(message);
-    	if (e != null) {
-    		msg.append(" Exception was: ").append( e.toString() );
-    	}
-		System.out.println( msg.toString() );
-		// if ( e != null) e.printStackTrace();		// TODO ??? Do we want this?
+        logToStdout(message, e);
     }
 
     /**
      * Used to log errors to the console during the loading of the properties file itself. Can't use
      * standard logging in this case, since the Logger may not be initialized yet. Output is sent to
-     * {@code PrintStream} {@code System.out}.
+     * {@code PrintStream} {@code System.out}.  Output is discarded if the {@code System} property
+     * "org.owasp.esapi.logSpecial.discard" is set to {@code true}.
      *
      * @param message The message to send to the console.
      */
     private void logSpecial(String message) {
-		System.out.println(message);
+		logToStdout(message, null);
     }
-    
     /**
 	 * {@inheritDoc}
 	 */