Refinement of handler search on exit. Add javadoc and cleanupt

Author: CarolynRountree

core/pom.xml

@@ -40,6 +40,24 @@
             <artifactId>junit</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.easymock</groupId>
+            <artifactId>easymock</artifactId>
+            <version>3.6</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.powermock</groupId>
+            <artifactId>powermock-api-easymock</artifactId>
+            <version>1.6.6</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.powermock</groupId>
+            <artifactId>powermock-module-junit4</artifactId>
+            <version>1.6.6</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

core/src/main/java/oracle/weblogic/deploy/logging/PlatformLogger.java

@@ -4,7 +4,11 @@
  */
 package oracle.weblogic.deploy.logging;
 
+import java.util.ArrayList;
+import java.util.Enumeration;
+import java.util.List;
 import java.util.logging.Level;
+import java.util.logging.LogManager;
 import java.util.logging.LogRecord;
 import java.util.logging.Logger;
 
@@ -526,6 +530,23 @@ public void warning(String msg, Throwable thrown) {
         logger.logp(Level.WARNING, details.clazz, details.method, msg, thrown);
     }
 
+    /**
+     * Return a list of the current loggers.
+     *
+     * @return List of Logger from the Log Manager
+     */
+    public static List<Logger> getLoggers() {
+        LogManager manager = LogManager.getLogManager();
+        Enumeration<String> e = manager.getLoggerNames();
+        List<Logger> topList = new ArrayList<>();
+        while (e.hasMoreElements()) {
+            String loggerName = e.nextElement();
+            Logger logger = manager.getLogger(loggerName);
+            topList.add(logger);
+        }
+        return topList;
+    }
+
     /**
      * Obtains caller details, class name and method, to be provided to the actual Logger. This
      * code is adapted from ODLLogRecord, which should yield consistency in reporting using

core/src/main/java/oracle/weblogic/deploy/logging/SummaryHandler.java

@@ -1,11 +1,34 @@
+/*
+ * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+ * The Universal Permissive License (UPL), Version 1.0
+ */
 package oracle.weblogic.deploy.logging;
 
-import java.text.MessageFormat;
-import java.util.*;
-import java.util.logging.*;
-import java.util.logging.Formatter;
-
-
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Properties;
+import java.util.logging.ConsoleHandler;
+import java.util.logging.Handler;
+import java.util.logging.Level;
+import java.util.logging.LogManager;
+import java.util.logging.LogRecord;
+import java.util.logging.MemoryHandler;
+
+
+/**
+ * This class save the log records logged by the tool at Info level or greater. The WLSDeployExit exit method will
+ * call this Handler to publish the messages, along with the total of the log records, by Level category.
+ *
+ * The WLSDeployCustomizeLoggingConfig adds the properties from this class' getHandlerProperties() to the
+ * log manager logger properties and adds the handler to the root WLSDEPLOY Logger. See the class for information
+ * on how to inject this handler into the wlsdeploy root logger.
+ *
+ * Before the tool exit, if specified by the caller, a recap of the saved logs is displayed to the console.
+ * A final total of the records logged by the tool for the Level categories indicated above is displayed to the console.
+ *
+ * @see WLSDeployCustomizeLoggingConfig
+ * @see oracle.weblogic.deploy.util.WLSDeployExit
+ */
 public class SummaryHandler extends MemoryHandler implements WLSDeployLogEndHandler {
     private static final String CLASS = SummaryHandler.class.getName();
     private static final String LEVEL_PROPERTY = "level";
@@ -16,13 +39,16 @@ public class SummaryHandler extends MemoryHandler implements WLSDeployLogEndHand
     private static final String LINE_SEPARATION = System.lineSeparator();
 
     private PlatformLogger LOGGER = WLSDeployLogFactory.getLogger("wlsdeploy.exit");
-    private boolean online = false;
+    private boolean recap = false;
     private int bufferSize;
 
     private Handler target;
     private List<LevelHandler> handlers = new ArrayList<>();
     private boolean closed = false;
 
+    /**
+     * This default constructor is populated with the handler properties loaded by the WLSDeployCustomizeLoggingConfig.
+     */
     public SummaryHandler() {
         super();
         configure();
@@ -31,9 +57,14 @@ public SummaryHandler() {
         addLevelHandler(Level.INFO);
         addLevelHandler(Level.WARNING);
         addLevelHandler(Level.SEVERE);
-        System.out.println("*** summary handler");
     }
 
+    /**
+     * Tally and save the log record if it matches one of the category Level handlers. Once the summary has completed,
+     * all further log records will be ignored.
+     *
+     * @param record to tally and save in handler with matching Level category
+     */
     @Override
     public synchronized void publish(LogRecord record) {
         // after close, take yourself out of the mix. The stored up log messages are going to go to the
@@ -45,9 +76,11 @@ public synchronized void publish(LogRecord record) {
         }
     }
 
+    /**
+     * The Summary Handler will publish the recaps and total. The log records are discarded and the total reset.
+     */
     @Override
     public synchronized void push() {
-        System.out.println("i am in push ");
         String METHOD = "push";
         LOGGER.entering(CLASS, METHOD);
         closed = true;
@@ -58,7 +91,7 @@ public synchronized void push() {
             int count = handler.pushSection();
             super.push();
             if (count >= 0) {
-                fmt.format("  %1$s : %2$,5d", handler.getLevel().getName(), count);
+                fmt.format("    %1$s : %2$,5d", handler.getLevel().getName(), count);
             }
         }
 
@@ -76,17 +109,34 @@ public void close() throws SecurityException {
         super.close();
     }
 
-    public void setOnline(boolean isOnline) {
-        online = isOnline;
+    /**
+     * Specify if the log records should be displayed to the console before the tool exit.
+     *
+     * @param recap if true a recap of the log records will be performed
+     */
+    public void setRecap(boolean recap) {
+        this.recap = recap;
     }
 
-    public boolean isOnline() {
-        return online;
+    /**
+     * Return whether the log records should be displayed to the console.
+     *
+     * @return true if a recap of the log records is specified
+     */
+    public boolean isRecap() {
+        return recap;
     }
 
+    /**
+     * This method is called by the tool to complete the SummaryHandler, and display the recap and total information
+     * to the console. The log records are only displayed to the console if the tool was run in online mode.
+     * This compensates for wlst writing spurious blank lines to the console during online mode.
+     *
+     * @param onlineMode if true, a recap of the log records will be displayed
+     */
     @Override
-    public void logEnd(boolean online) {
-        setOnline(online);
+    public void logEnd(boolean onlineMode) {
+        setRecap(onlineMode);
         push();
     }
 
@@ -100,26 +150,20 @@ public static Properties getHandlerProperties() {
         Properties properties = new Properties();
         properties.setProperty(LEVEL_PROPERTY, Level.INFO.getName());
         properties.setProperty(TARGET_PROPERTY, WLSDeployLoggingConsoleHandler.class.getName());
-        properties.setProperty(FORMATTER_PROPERTY, SummaryFormatter.class.getName());
+        properties.setProperty(FORMATTER_PROPERTY, WLSDeployLogFormatter.class.getName());
         return properties;
     }
 
-    public class SummaryFormatter extends Formatter {
-        public synchronized String format(LogRecord logRecord) {
-            // for now, only format the message in summary - maybe add logger name or other later
-            return formatMessage(logRecord);
-        }
-    }
-
     private void addLevelHandler(Level level) {
-        LevelHandler handler = null;
+        LevelHandler handler;
         if (getLevel().intValue() <= level.intValue()) {
             handler = new LevelHandler(target, bufferSize, level);
-            handler.setLevel(level);
-            handler.setFilter(getFilter());
-            //handler.setFormatter(new SummaryFormatter());
-            handlers.add(handler);
+        } else {
+            handler = new NoActionHandler(target, bufferSize, level);
         }
+        handler.setLevel(level);
+        handler.setFilter(getFilter());
+        handlers.add(handler);
     }
 
     private class LevelHandler extends MemoryHandler {
@@ -140,12 +184,14 @@ public synchronized void publish(LogRecord record) {
         }
 
         public synchronized int pushSection() {
-            if (isOnline()) {
+            if (isRecap()) {
                 logStart();
                 super.push();
                 logEnd();
             }
-            return getTotalRecords();
+            int result = totalRecords;
+            totalRecords = 0;
+            return result;
         }
 
         int getTotalRecords() {

core/src/main/java/oracle/weblogic/deploy/logging/WLSDeployCustomizeLoggingConfig.java

@@ -1,3 +1,7 @@
+/*
+ * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+ * The Universal Permissive License (UPL), Version 1.0
+ */
 package oracle.weblogic.deploy.logging;
 
 import oracle.weblogic.deploy.util.StringUtils;
@@ -7,11 +11,41 @@
 import java.util.*;
 import java.util.logging.Handler;
 
+/**
+ * Use this class to add custom handlers to the root WLSDEPLOY logger. The WLSDeployLoggingConfig
+ * loads the properties to the LogManager. .
+ *
+ * <p>You must add this class to the -Djava.util.logging.config.class parameter before the tool JVM is started.
+ * To inject one or more handlers into the WLSDEPLOY logger, you may either add the comma separated list to the
+ * logger.properties file as <WLSDEPLOY_LOGGER_NAME>.handlers=<list>, or set the list on the environment variable
+ * WLSDEPLOY_LOG_HANDLERS_ENV_VARIABLE. The property in the logging.properties file takes precedence
+ * over the environment variable.
+ *
+ * <p>This class will check each handler in the list to see if it has implemented the WLSDEPLOY_HANDLER_METHOD. This method
+ * returns a handler's properties. Any property that already exists in the logging.properties will be discarded -
+ * as logging.properties takes precedence. Any property that does not start with the handler class name will
+ * be rejected. This class' ONLY purpose is to dynamically add a handler and/or its properties to the
+ * WLSDEPLOY root logger.
+ *
+ * <p>The WLSDEPLOY logger is instantiated by WLSDeployLoggingConfig (and thus, the handlers are
+ * instantiated). The WLSDEPLOY logger's parameters are not inherited by a child logger unless the
+ * parameter instances already exist before the child logger is added.
+ */
 public class WLSDeployCustomizeLoggingConfig extends WLSDeployLoggingConfig {
 
     private static final String WLSDEPLOY_HANDLER_PROP = WLSDEPLOY_LOGGER_NAME + ".handlers";
     private static final String WLSDEPLOY_HANDLER_METHOD = "getHandlerProperties";
 
+    /**
+     * Check the logging.properties file for a "WLSDEPLOY".handlers property. If the property does not exist,
+     * check to see if the WLSDEPLOY_LOG_HANDLERS_ENV_VARIABLE environment variable has been set.
+     *
+     * <p>Check each handler to see if has implemented the WLSDEPLOY_HANDLER_METHOD. A property
+     * returned from the method is added to the provided properties if the property does not exist in the list.
+     *
+     * @param programName name of the tool calling this method
+     * @param logProps properties comprised by the WLSDeployLoggingConfig class as the base list
+     */
     @Override
     public void customizeLoggingProperties(String programName, Properties logProps) {
         List<Class<?>> classList  = new ArrayList<>();
@@ -39,6 +73,7 @@ private static Set<String> findExtraHandlers(Properties logProps) {
         }
         return handlers;
     }
+
     private static Class<?> getHandlerClass(String handlerName) {
         String message = null;
         Class<?> handler = null;
@@ -62,8 +97,6 @@ private static void addHandlerProperties(Properties logProps, Class<?> clazz) {
         Properties props = null;
         // a forEach would be good here!
         String clazzName = clazz.getName();
-        // make sure some formatter is set
-        //logProps.setProperty(clazzName + HANDLER_FORMATTER_PROP, LOG_FORMATTER);
         Set<String> propSet = logProps.stringPropertyNames();
         try {
             // only look in this class

core/src/main/java/oracle/weblogic/deploy/logging/WLSDeployLogEndHandler.java

@@ -5,15 +5,24 @@
 package oracle.weblogic.deploy.logging;
 
 /**
- * This interface should be used by a Log Handler that wishes to perform some action or clean-up
- * before ending within a weblogic deploy tool. A class that implements this interface should include
+ * This interface should be used by a Logger Handler that wishes to perform some action or clean-up
+ * before the wlsdeploy tool exits. A class that implements this interface should include
  * the appropriate wrap-up action in the logEnd method.
  *
- * The corresponding WLSDeployExit will look through the Handlers on the LogManager and call the logEnd
- * method if the interface is implemented.
+ * <p>If the tool calls the WLSDeployExit.exit(), that method will search the Handlers on all WLSDEPLOY
+ * loggers. If a handler implements this interface, the logEnd method is called. The handlers' methods are called
+ * in parent / child order. If the same handler instance is found on more than one logger, the handler is only called
+ * once, with parent / child order insured for all.
+ *
+ * @see oracle.weblogic.deploy.util.WLSDeployExit
  */
 public interface WLSDeployLogEndHandler {
 
+    /**
+     * The handler performs any wrap-up action.
+     *
+     * @param online true if the tool is running in online mode.
+     */
     void logEnd(boolean online);
 
 }