From 257bf867267c29e8760e65ce6ae15ea80272b870 Mon Sep 17 00:00:00 2001
From: Michael Ow <mow@svn.icu-project.org>
Date: Thu, 13 Aug 2009 19:12:20 +0000
Subject: [PATCH] ICU-6710 Add description to ICULogger and implement in
 TimeZone.

X-SVN-Rev: 26492
---
 .../core/src/com/ibm/icu/impl/ICULogger.java  | 35 ++++++++++++++++++-
 .../core/src/com/ibm/icu/util/TimeZone.java   | 11 ++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/impl/ICULogger.java b/icu4j/main/classes/core/src/com/ibm/icu/impl/ICULogger.java
index 98dcd57f8a5..300983e3ddc 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/impl/ICULogger.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/impl/ICULogger.java
@@ -10,6 +10,8 @@ import java.util.logging.ConsoleHandler;
 import java.util.logging.Logger;
 import java.util.logging.Level;
 
+import com.ibm.icu.util.TimeZone;
+
 /**
  *
  * Extends the Java Logger class adding a method to turn off/on logging.
@@ -23,7 +25,38 @@ import java.util.logging.Level;
  * To use logging, the system property "icu4j.debug.logging" must be set to "on" or "all",
  * otherwise the static ICULogger object will be null. This will help lower any unneccessary
  * resource usage when logging is not desired.
- * 
+ * <P>
+ * <strong>Examples</strong>:<P>
+ * Usage in code
+ * <blockquote>
+ * <pre>
+ * public class Class {
+ *     // Create logger object (usually with the class name)
+ *     public static ICULogger ClassLogger = ICULogger.getICULogger(Class.class.getName());
+ *     
+ *     // Method that will use logger.
+ *     public boolean hasSomething(Object obj) {
+ *         if (obj == null) {
+ *              // Log that obj is null.
+ *              // Note: Good to check for null and if logging is turned on to minimize resource usage when logging is not needed.
+ *              if (ClassLogger != null && ClassLogger.isLoggingOn()) {
+ *                  ClassLogger.warning("obj is null so false was returned by default.");
+ *              }
+ *             return false;
+ *         }
+ *         
+ *         ...
+ *         
+ *     }
+ * }
+ * </pre>
+ * </blockquote>
+ * Turning on logging (using the default settings)
+ * <blockquote>
+ * <pre>
+ * java -Dicu4j.debug.logging=all program
+ * </pre>
+ * </blockquote>
  * @author       Michael Ow
  * @draft ICU 4.4
  */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/util/TimeZone.java b/icu4j/main/classes/core/src/com/ibm/icu/util/TimeZone.java
index a9d47c210fe..fc3cd145b32 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/util/TimeZone.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/util/TimeZone.java
@@ -20,6 +20,7 @@ import com.ibm.icu.impl.SimpleCache;
 import com.ibm.icu.impl.TimeZoneAdapter;
 import com.ibm.icu.impl.ZoneMeta;
 import com.ibm.icu.text.SimpleDateFormat;
+import com.ibm.icu.impl.ICULogger;
 
 /**
  * <code>TimeZone</code> represents a time zone offset, and also figures out daylight
@@ -99,6 +100,12 @@ import com.ibm.icu.text.SimpleDateFormat;
  * @stable ICU 2.0
  */
 abstract public class TimeZone implements Serializable, Cloneable {
+    /**
+     * A logger for TimeZone. Will be null if logging is not on by way of system property: "icu4j.debug.logging"
+     * @draft ICU 4.4
+     */
+    public static ICULogger TimeZoneLogger = ICULogger.getICULogger(TimeZone.class.getName());
+
     // using serialver from jdk1.4.2_05
     private static final long serialVersionUID = -744942128318337471L;
 
@@ -600,6 +607,10 @@ abstract public class TimeZone implements Serializable, Cloneable {
                 result = ZoneMeta.getCustomTimeZone(ID);
             }
             if (result == null) {
+                /* Log that timezone is using GMT if logging is on. */
+                if (TimeZoneLogger != null && TimeZoneLogger.isLoggingOn()) {
+                    TimeZoneLogger.warning("\"" +ID + "\" is a bogus id so timezone is falling back to GMT.");
+                }
                 result = ZoneMeta.getGMT();
             }
         }