jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/impl/ICULogger.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 2009-2010, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 package com.ibm.icu.impl;\r
   8 \r
   9 import java.util.logging.ConsoleHandler;\r
  10 import java.util.logging.Level;\r
  11 import java.util.logging.Logger;\r
  12 \r
  13 /**\r
  14  *\r
  15  * Extends the Java Logger class adding a method to turn off/on logging.\r
  16  * Classes where logging is wanted contains a static ICULogger object\r
  17  * with logging turned off by default unless the system property \r
  18  * "icu4j.debug.logging" is set to "all"\r
  19  * \r
  20  * If "icu4j.debug.logging" is not set to "all", then the individual loggers needs\r
  21  * to be turned on manually. (e.g. TimeZone.TimeZoneLogger.turnLoggingOn())\r
  22  * <p>\r
  23  * To use logging, the system property "icu4j.debug.logging" must be set to "on" or "all",\r
  24  * otherwise the static ICULogger object will be null. This will help lower any unneccessary\r
  25  * resource usage when logging is not desired.\r
  26  * <P>\r
  27  * <strong>Examples</strong>:<P>\r
  28  * Usage in code\r
  29  * <blockquote>\r
  30  * <pre>\r
  31  * public class Class {\r
  32  *     // Create logger object (usually with the class name)\r
  33  *     public static ICULogger ClassLogger = ICULogger.getICULogger(Class.class.getName());\r
  34  *     \r
  35  *     // Method that will use logger.\r
  36  *     public boolean hasSomething(Object obj) {\r
  37  *         if (obj == null) {\r
  38  *              // Log that obj is null.\r
  39  *              // Note: Good to check for null and if logging is turned on to minimize resource usage when logging is not needed.\r
  40  *              if (ClassLogger != null && ClassLogger.isLoggingOn()) {\r
  41  *                  ClassLogger.warning("obj is null so false was returned by default.");\r
  42  *              }\r
  43  *             return false;\r
  44  *         }\r
  45  *         \r
  46  *         ...\r
  47  *         \r
  48  *     }\r
  49  * }\r
  50  * </pre>\r
  51  * </blockquote>\r
  52  * Turning on logging (using the default settings)\r
  53  * <blockquote>\r
  54  * <pre>\r
  55  * java -Dicu4j.debug.logging=all program\r
  56  * </pre>\r
  57  * </blockquote>\r
  58  */\r
  59 \r
  60 public class ICULogger extends Logger {\r
  61     private static enum LOGGER_STATUS { ON, OFF, NULL };\r
  62     private static final String GLOBAL_FLAG_TURN_ON_LOGGING = "all";\r
  63     private static final String SYSTEM_PROP_LOGGER = "icu4j.debug.logging";\r
  64     \r
  65     private LOGGER_STATUS currentStatus;\r
  66     \r
  67     /**\r
  68      * ICULogger constructor that calls the parent constructor with the desired parameters.\r
  69      */\r
  70     private ICULogger(String name, String resourceBundleName) {\r
  71         super(name, resourceBundleName);\r
  72     }\r
  73     \r
  74     /**\r
  75      * Set the status to either on or off. Set the level of the logger to INFO.\r
  76      */\r
  77     private void setStatus(LOGGER_STATUS newStatus) {\r
  78         if (currentStatus != newStatus) {\r
  79             /* Default to level INFO */\r
  80             if (currentStatus == LOGGER_STATUS.OFF && newStatus == LOGGER_STATUS.ON) {\r
  81                 this.setLevel(Level.INFO);\r
  82             }\r
  83             \r
  84             currentStatus = newStatus;\r
  85             \r
  86             if (currentStatus == LOGGER_STATUS.OFF){\r
  87                 this.setLevel(Level.OFF);\r
  88             }\r
  89         }\r
  90     }\r
  91     \r
  92     /**\r
  93      * Check the system property SYSTEM_PROP_LOGGER to see if it is set.\r
  94      * return true if it is otherwise return false.\r
  95      */\r
  96     private static LOGGER_STATUS checkGlobalLoggingFlag() {\r
  97         try {\r
  98             String prop = System.getProperty(SYSTEM_PROP_LOGGER);\r
  99 \r
 100             if (prop != null) {\r
 101                 if (prop.equals(GLOBAL_FLAG_TURN_ON_LOGGING)) {\r
 102                     return LOGGER_STATUS.ON;\r
 103                 }\r
 104                 return LOGGER_STATUS.OFF;\r
 105             }\r
 106         } catch (SecurityException e) {\r
 107             // Ignore the security exception and fall-through\r
 108         }\r
 109 \r
 110         return LOGGER_STATUS.NULL;\r
 111     }\r
 112     \r
 113     /**\r
 114      * Instantiates a new ICULogger object with logging turned off by default.\r
 115      *\r
 116      * @param name to be use by the logger (usually is the class name)\r
 117      * @return a new ICULogger object\r
 118      * @draft ICU 4.4\r
 119      * @provisional This API might change or be removed in a future release.\r
 120      */\r
 121     public static ICULogger getICULogger(String name) {\r
 122         return getICULogger(name, null);\r
 123     }\r
 124     \r
 125     /**\r
 126      * Instantiates a new ICULogger object with logging turned off by default\r
 127      * unless the system property "icu4j.debug.logging" is set to "all"\r
 128      *\r
 129      * @param name to be use by the logger (usually is the class name)\r
 130      * @param resourceBundleName name to localize messages (can be null)\r
 131      * @return a new ICULogger object\r
 132      * @draft ICU 4.4\r
 133      * @provisional This API might change or be removed in a future release.\r
 134      */\r
 135     public static ICULogger getICULogger(String name, String resourceBundleName) {\r
 136         LOGGER_STATUS flag = checkGlobalLoggingFlag();\r
 137         if (flag != LOGGER_STATUS.NULL) {\r
 138             ICULogger logger = new ICULogger(name, resourceBundleName);\r
 139             \r
 140             /* Add a default handler to logger*/\r
 141             logger.addHandler(new ConsoleHandler());\r
 142             \r
 143             /* Turn off logging by default unless SYSTEM_PROP_LOGGER property is set to "all" */\r
 144             if (flag == LOGGER_STATUS.ON) {\r
 145                 logger.turnOnLogging();\r
 146             } else {\r
 147                 logger.turnOffLogging();\r
 148             }\r
 149             \r
 150             return logger;\r
 151         }\r
 152         return null;\r
 153     }\r
 154     \r
 155     /**\r
 156      * Determined if logging is turned on or off. The return value is true if logging is on.\r
 157      *\r
 158      * @return whether logging is turned on or off.\r
 159      * @draft ICU 4.4\r
 160      * @provisional This API might change or be removed in a future release.\r
 161      */\r
 162     public boolean isLoggingOn() {\r
 163         if (currentStatus == LOGGER_STATUS.ON) {\r
 164             return true;\r
 165         } else {\r
 166             return false;\r
 167         }\r
 168     }\r
 169     \r
 170     /**\r
 171      * Turn logging on.\r
 172      *\r
 173      * @draft ICU 4.4\r
 174      * @provisional This API might change or be removed in a future release.\r
 175      */\r
 176     public void turnOnLogging() {\r
 177         setStatus(LOGGER_STATUS.ON);\r
 178     }\r
 179     \r
 180     /**\r
 181      * Turn logging off.\r
 182      *\r
 183      * @draft ICU 4.4\r
 184      * @provisional This API might change or be removed in a future release.\r
 185      */\r
 186     public void turnOffLogging() {\r
 187         setStatus(LOGGER_STATUS.OFF);\r
 188     }\r
 189     \r
 190 }\r