libjava/java/util/logging/Level.java

   1 /* Level.java -- a class for indicating logging levels
   2    Copyright (C) 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.util.logging;
  40
  41 import java.io.Serializable;
  42 import java.util.ResourceBundle;
  43
  44 /**
  45  * A class for indicating logging levels.  A number of commonly used
  46  * levels is pre-defined (such as <code>java.util.logging.Level.INFO</code>),
  47  * and applications should utilize those whenever possible.  For specialized
  48  * purposes, however, applications can sub-class Level in order to define
  49  * custom logging levels.
  50  *
  51  * @author Sascha Brawer (brawer@acm.org)
  52  */
  53 public class Level implements Serializable
  54 {
  55   /* The integer values are the same as in the Sun J2SE 1.4.
  56    * They have been obtained with a test program. In J2SE 1.4.1,
  57    * Sun has amended the API documentation; these values are now
  58    * publicly documented.
  59    */
  60
  61   /**
  62    * The <code>OFF</code> level is used as a threshold for filtering
  63    * log records, meaning that no message should be logged.
  64    *
  65    * @see Logger#setLevel(java.util.logging.Level)
  66    */
  67   public static final Level OFF = new Level ("OFF", Integer.MAX_VALUE);
  68
  69   /**
  70    * Log records whose level is <code>SEVERE</code> indicate a serious
  71    * failure that prevents normal program execution.  Messages at this
  72    * level should be understandable to an inexperienced, non-technical
  73    * end user.  Ideally, they explain in simple words what actions the
  74    * user can take in order to resolve the problem.
  75    */
  76   public static final Level SEVERE = new Level ("SEVERE", 1000);
  77
  78
  79   /**
  80    * Log records whose level is <code>WARNING</code> indicate a
  81    * potential problem that does not prevent normal program execution.
  82    * Messages at this level should be understandable to an
  83    * inexperienced, non-technical end user.  Ideally, they explain in
  84    * simple words what actions the user can take in order to resolve
  85    * the problem.
  86    */
  87   public static final Level WARNING = new Level ("WARNING", 900);
  88
  89
  90   /**
  91    * Log records whose level is <code>INFO</code> are used in purely
  92    * informational situations that do not constitute serious errors or
  93    * potential problems. In the default logging configuration, INFO
  94    * messages will be written to the system console.  For this reason,
  95    * the INFO level should be used only for messages that are
  96    * important to end users and system administrators.  Messages at
  97    * this level should be understandable to an inexperienced,
  98    * non-technical user.
  99    */
 100   public static final Level INFO = new Level ("INFO", 800);
 101
 102
 103   /**
 104    * Log records whose level is <code>CONFIG</code> are used for
 105    * describing the static configuration, for example the windowing
 106    * environment, the operating system version, etc.
 107    */
 108   public static final Level CONFIG = new Level ("CONFIG", 700);
 109
 110
 111   /**
 112    * Log records whose level is <code>FINE</code> are typically used
 113    * for messages that are relevant for developers using
 114    * the component generating log messages.  Examples include minor,
 115    * recoverable failures, or possible inefficiencies.
 116    */
 117   public static final Level FINE = new Level ("FINE", 500);
 118
 119
 120   /**
 121    * Log records whose level is <code>FINER</code> are intended for
 122    * rather detailed tracing, for example entering a method, returning
 123    * from a method, or throwing an exception.
 124    */
 125   public static final Level FINER = new Level ("FINER", 400);
 126
 127
 128   /**
 129    * Log records whose level is <code>FINEST</code> are used for
 130    * highly detailed tracing, for example to indicate that a certain
 131    * point inside the body of a method has been reached.
 132    */
 133   public static final Level FINEST = new Level ("FINEST", 300);
 134
 135
 136   /**
 137    * The <code>ALL</code> level is used as a threshold for filtering
 138    * log records, meaning that every message should be logged.
 139    *
 140    * @see Logger#setLevel(java.util.logging.Level)
 141    */
 142   public static final Level ALL = new Level ("ALL", Integer.MIN_VALUE);
 143
 144
 145   private static final Level[] knownLevels = {
 146     ALL, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, OFF
 147   };
 148
 149
 150   /**
 151    * The name of the Level without localizing it, for example
 152    * "WARNING".
 153    */
 154   private String name;
 155
 156
 157   /**
 158    * The integer value of this <code>Level</code>.
 159    */
 160   private int value;
 161
 162
 163   /**
 164    * The name of the resource bundle used for localizing the level
 165    * name, or <code>null</code> if the name does not undergo
 166    * localization.
 167    */
 168   private String resourceBundleName;
 169
 170
 171   /**
 172    * Creates a logging level given a name and an integer value.
 173    * It rarely is necessary to create custom levels,
 174    * as most applications should be well served with one of the
 175    * standard levels such as <code>Level.CONFIG</code>,
 176    * <code>Level.INFO</code>, or <code>Level.FINE</code>.
 177    *
 178    * @param name the name of the level.
 179    *
 180    * @param value the integer value of the level.  Please note
 181    *     that the Java<small><sup>TM</sup></small>
 182    *     Logging API does not specify integer
 183    *     values for standard levels (such as
 184    *     Level.FINE).  Therefore, a custom
 185    *     level should pass an integer value that
 186    *     is calculated at run-time, e.g.
 187    *     <code>(Level.FINE.intValue() + Level.CONFIG.intValue())
 188    *     / 2</code> for a level between FINE and CONFIG.
 189    */
 190   protected Level(String name, int value)
 191   {
 192     this(name, value, null);
 193   }
 194
 195
 196   /**
 197    * Create a logging level given a name, an integer value and a name
 198    * of a resource bundle for localizing the level name.  It rarely
 199    * is necessary to create custom levels, as most applications
 200    * should be well served with one of the standard levels such as
 201    * <code>Level.CONFIG</code>, <code>Level.INFO</code>, or
 202    * <code>Level.FINE</code>.
 203    *
 204    * @param name the name of the level.
 205    *
 206    * @param value the integer value of the level.  Please note
 207    *        that the Java<small><sup>TM</sup></small>
 208    *        Logging API does not specify integer
 209    *        values for standard levels (such as
 210    *        Level.FINE).  Therefore, a custom
 211    *        level should pass an integer value that
 212    *        is calculated at run-time, e.g.
 213    *        <code>(Level.FINE.intValue() + Level.CONFIG.intValue())
 214    *        / 2</code> for a level between FINE and CONFIG.
 215    *
 216    * @param resourceBundleName the name of a resource bundle
 217    *       for localizing the level name, or <code>null</code>
 218    *       if the name does not need to be localized.
 219    */
 220   protected Level(String name, int value, String resourceBundleName)
 221   {
 222     this.name = name;
 223     this.value = value;
 224     this.resourceBundleName = resourceBundleName;
 225   }
 226
 227
 228   static final long serialVersionUID = -8176160795706313070L;
 229
 230
 231   /**
 232    * Checks whether the Level has the same intValue as one of the
 233    * pre-defined levels.  If so, the pre-defined level object is
 234    * returned.
 235    *
 236    * <br/>Since the resource bundle name is not taken into
 237    * consideration, it is possible to resolve Level objects that have
 238    * been de-serialized by another implementation, even if the other
 239    * implementation uses a different resource bundle for localizing
 240    * the names of pre-defined levels.
 241    */
 242   private Object readResolve()
 243   {
 244     for (int i = 0; i < knownLevels.length; i++)
 245       if (value == knownLevels[i].intValue())
 246         return knownLevels[i];
 247
 248     return this;
 249   }
 250
 251
 252   /**
 253    * Returns the name of the resource bundle used for localizing the
 254    * level name.
 255    *
 256    * @return the name of the resource bundle used for localizing the
 257    * level name, or <code>null</code> if the name does not undergo
 258    * localization.
 259    */
 260   public String getResourceBundleName()
 261   {
 262     return resourceBundleName;
 263   }
 264
 265
 266   /**
 267    * Returns the name of the Level without localizing it, for example
 268    * "WARNING".
 269    */
 270   public String getName()
 271   {
 272     return name;
 273   }
 274
 275
 276   /**
 277    * Returns the name of the Level after localizing it, for example
 278    * "WARNUNG".
 279    */
 280   public String getLocalizedName()
 281   {
 282     String localizedName = null;
 283
 284     if (resourceBundleName != null)
 285     {
 286       try
 287       {
 288         ResourceBundle b = ResourceBundle.getBundle(resourceBundleName);
 289         localizedName = b.getString(name);
 290       }
 291       catch (Exception _)
 292       {
 293       }
 294     }
 295
 296     if (localizedName != null)
 297       return localizedName;
 298     else
 299       return name;
 300   }
 301
 302
 303   /**
 304    * Returns the name of the Level without localizing it, for example
 305    * "WARNING".
 306    */
 307   public final String toString()
 308   {
 309     return getName();
 310   }
 311
 312
 313   /**
 314    * Returns the integer value of the Level.
 315    */
 316   public final int intValue()
 317   {
 318     return value;
 319   }
 320
 321
 322   /**
 323    * Returns one of the standard Levels given either its name or its
 324    * integer value.  Custom subclasses of Level will not be returned
 325    * by this method.
 326    *
 327    * @throws IllegalArgumentException if <code>name</code> is neither
 328    * the name nor the integer value of one of the pre-defined standard
 329    * logging levels.
 330    *
 331    * @throws NullPointerException if <code>name</code> is null.
 332    *
 333    */
 334   public static Level parse(String name)
 335     throws IllegalArgumentException
 336   {
 337     /* This will throw a NullPointerException if name is null,
 338      * as required by the API specification.
 339      */
 340     name = name.intern();
 341
 342     for (int i = 0; i < knownLevels.length; i++)
 343     {
 344       if (name == knownLevels[i].name)
 345         return knownLevels[i];
 346     }
 347
 348     try
 349     {
 350       int num = Integer.parseInt(name);
 351       for (int i = 0; i < knownLevels.length; i++)
 352         if (num == knownLevels[i].value)
 353           return knownLevels[i];
 354     }
 355     catch (NumberFormatException _)
 356     {
 357     }
 358
 359     String msg = "Not the name of a standard logging level: \"" + name + "\"";
 360     throw new IllegalArgumentException(msg);
 361   }
 362
 363
 364   /**
 365    * Checks whether this Level's integer value is equal to that of
 366    * another object.
 367    *
 368    * @return <code>true</code> if <code>other</code> is an instance of
 369    *     <code>java.util.logging.Level</code> and has the same integer
 370    * value, <code>false</code> otherwise.
 371    */
 372   public boolean equals(Object other)
 373   {
 374     if (!(other instanceof Level))
 375       return false;
 376
 377     return value == ((Level) other).value;
 378   }
 379
 380
 381   /**
 382    * Returns a hash code for this Level which is based on its numeric
 383    * value.
 384    */
 385   public int hashCode()
 386   {
 387     return value;
 388   }
 389
 390
 391   /**
 392    * Determines whether or not this Level is one of the standard
 393    * levels specified in the Logging API.
 394    *
 395    * <p>This method is package-private because it is not part
 396    * of the logging API specification.  However, an XMLFormatter
 397    * is supposed to emit the numeric value for a custom log
 398    * level, but the name for a pre-defined level. It seems
 399    * cleaner to put this method to Level than to write some
 400    * procedural code for XMLFormatter.
 401    *
 402    * @return <code>true</code> if this Level is a standard level,
 403    *         <code>false</code> otherwise.
 404    */
 405   final boolean isStandardLevel()
 406   {
 407     for (int i = 0; i < knownLevels.length; i++)
 408       if (knownLevels[i] == this)
 409         return true;
 410
 411     return false;
 412   }
 413 }
 414