libjava/java/util/logging/Level.java

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