1 /*
   2  * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util.logging;
  27 import java.lang.ref.Reference;
  28 import java.lang.ref.ReferenceQueue;
  29 import java.lang.ref.WeakReference;
  30 import java.lang.reflect.Module;
  31 import java.util.ArrayList;
  32 import java.util.Collections;
  33 import java.util.HashMap;
  34 import java.util.List;
  35 import java.util.Locale;
  36 import java.util.Map;
  37 import java.util.Optional;
  38 import java.util.ResourceBundle;
  39 import java.util.function.Function;
  40 import java.util.stream.Stream;
  41 
  42 /**
  43  * The Level class defines a set of standard logging levels that
  44  * can be used to control logging output.  The logging Level objects
  45  * are ordered and are specified by ordered integers.  Enabling logging
  46  * at a given level also enables logging at all higher levels.
  47  * <p>
  48  * Clients should normally use the predefined Level constants such
  49  * as Level.SEVERE.
  50  * <p>
  51  * The levels in descending order are:
  52  * <ul>
  53  * <li>SEVERE (highest value)
  54  * <li>WARNING
  55  * <li>INFO
  56  * <li>CONFIG
  57  * <li>FINE
  58  * <li>FINER
  59  * <li>FINEST  (lowest value)
  60  * </ul>
  61  * In addition there is a level OFF that can be used to turn
  62  * off logging, and a level ALL that can be used to enable
  63  * logging of all messages.
  64  * <p>
  65  * It is possible for third parties to define additional logging
  66  * levels by subclassing Level.  In such cases subclasses should
  67  * take care to chose unique integer level values and to ensure that
  68  * they maintain the Object uniqueness property across serialization
  69  * by defining a suitable readResolve method.
  70  *
  71  * @since 1.4
  72  */
  73 
  74 public class Level implements java.io.Serializable {
  75     private static final String defaultBundle = "sun.util.logging.resources.logging";
  76 
  77     /**
  78      * @serial  The non-localized name of the level.
  79      */
  80     private final String name;
  81 
  82     /**
  83      * @serial  The integer value of the level.
  84      */
  85     private final int value;
  86 
  87     /**
  88      * @serial The resource bundle name to be used in localizing the level name.
  89      */
  90     private final String resourceBundleName;
  91 
  92     // localized level name
  93     private transient String localizedLevelName;
  94     private transient Locale cachedLocale;
  95 
  96     /**
  97      * OFF is a special level that can be used to turn off logging.
  98      * This level is initialized to <CODE>Integer.MAX_VALUE</CODE>.
  99      */
 100     public static final Level OFF = new Level("OFF",Integer.MAX_VALUE, defaultBundle);
 101 
 102     /**
 103      * SEVERE is a message level indicating a serious failure.
 104      * <p>
 105      * In general SEVERE messages should describe events that are
 106      * of considerable importance and which will prevent normal
 107      * program execution.   They should be reasonably intelligible
 108      * to end users and to system administrators.
 109      * This level is initialized to <CODE>1000</CODE>.
 110      */
 111     public static final Level SEVERE = new Level("SEVERE",1000, defaultBundle);
 112 
 113     /**
 114      * WARNING is a message level indicating a potential problem.
 115      * <p>
 116      * In general WARNING messages should describe events that will
 117      * be of interest to end users or system managers, or which
 118      * indicate potential problems.
 119      * This level is initialized to <CODE>900</CODE>.
 120      */
 121     public static final Level WARNING = new Level("WARNING", 900, defaultBundle);
 122 
 123     /**
 124      * INFO is a message level for informational messages.
 125      * <p>
 126      * Typically INFO messages will be written to the console
 127      * or its equivalent.  So the INFO level should only be
 128      * used for reasonably significant messages that will
 129      * make sense to end users and system administrators.
 130      * This level is initialized to <CODE>800</CODE>.
 131      */
 132     public static final Level INFO = new Level("INFO", 800, defaultBundle);
 133 
 134     /**
 135      * CONFIG is a message level for static configuration messages.
 136      * <p>
 137      * CONFIG messages are intended to provide a variety of static
 138      * configuration information, to assist in debugging problems
 139      * that may be associated with particular configurations.
 140      * For example, CONFIG message might include the CPU type,
 141      * the graphics depth, the GUI look-and-feel, etc.
 142      * This level is initialized to <CODE>700</CODE>.
 143      */
 144     public static final Level CONFIG = new Level("CONFIG", 700, defaultBundle);
 145 
 146     /**
 147      * FINE is a message level providing tracing information.
 148      * <p>
 149      * All of FINE, FINER, and FINEST are intended for relatively
 150      * detailed tracing.  The exact meaning of the three levels will
 151      * vary between subsystems, but in general, FINEST should be used
 152      * for the most voluminous detailed output, FINER for somewhat
 153      * less detailed output, and FINE for the  lowest volume (and
 154      * most important) messages.
 155      * <p>
 156      * In general the FINE level should be used for information
 157      * that will be broadly interesting to developers who do not have
 158      * a specialized interest in the specific subsystem.
 159      * <p>
 160      * FINE messages might include things like minor (recoverable)
 161      * failures.  Issues indicating potential performance problems
 162      * are also worth logging as FINE.
 163      * This level is initialized to <CODE>500</CODE>.
 164      */
 165     public static final Level FINE = new Level("FINE", 500, defaultBundle);
 166 
 167     /**
 168      * FINER indicates a fairly detailed tracing message.
 169      * By default logging calls for entering, returning, or throwing
 170      * an exception are traced at this level.
 171      * This level is initialized to <CODE>400</CODE>.
 172      */
 173     public static final Level FINER = new Level("FINER", 400, defaultBundle);
 174 
 175     /**
 176      * FINEST indicates a highly detailed tracing message.
 177      * This level is initialized to <CODE>300</CODE>.
 178      */
 179     public static final Level FINEST = new Level("FINEST", 300, defaultBundle);
 180 
 181     /**
 182      * ALL indicates that all messages should be logged.
 183      * This level is initialized to <CODE>Integer.MIN_VALUE</CODE>.
 184      */
 185     public static final Level ALL = new Level("ALL", Integer.MIN_VALUE, defaultBundle);
 186 
 187     /**
 188      * Create a named Level with a given integer value.
 189      * <p>
 190      * Note that this constructor is "protected" to allow subclassing.
 191      * In general clients of logging should use one of the constant Level
 192      * objects such as SEVERE or FINEST.  However, if clients need to
 193      * add new logging levels, they may subclass Level and define new
 194      * constants.
 195      * @param name  the name of the Level, for example "SEVERE".
 196      * @param value an integer value for the level.
 197      * @throws NullPointerException if the name is null
 198      */
 199     protected Level(String name, int value) {
 200         this(name, value, null);
 201     }
 202 
 203     /**
 204      * Create a named Level with a given integer value and a
 205      * given localization resource name.
 206      *
 207      * @param name  the name of the Level, for example "SEVERE".
 208      * @param value an integer value for the level.
 209      * @param resourceBundleName name of a resource bundle to use in
 210      *    localizing the given name. If the resourceBundleName is null
 211      *    or an empty string, it is ignored.
 212      * @throws NullPointerException if the name is null
 213      */
 214     protected Level(String name, int value, String resourceBundleName) {
 215         this(name, value, resourceBundleName, true);
 216     }
 217 
 218     // private constructor to specify whether this instance should be added
 219     // to the KnownLevel list from which Level.parse method does its look up
 220     private Level(String name, int value, String resourceBundleName, boolean visible) {
 221         if (name == null) {
 222             throw new NullPointerException();
 223         }
 224         this.name = name;
 225         this.value = value;
 226         this.resourceBundleName = resourceBundleName;
 227         this.localizedLevelName = resourceBundleName == null ? name : null;
 228         this.cachedLocale = null;
 229         if (visible) {
 230             KnownLevel.add(this);
 231         }
 232     }
 233 
 234     /**
 235      * Return the level's localization resource bundle name, or
 236      * null if no localization bundle is defined.
 237      *
 238      * @return localization resource bundle name
 239      */
 240     public String getResourceBundleName() {
 241         return resourceBundleName;
 242     }
 243 
 244     /**
 245      * Return the non-localized string name of the Level.
 246      *
 247      * @return non-localized name
 248      */
 249     public String getName() {
 250         return name;
 251     }
 252 
 253     /**
 254      * Return the localized string name of the Level, for
 255      * the current default locale.
 256      * <p>
 257      * If no localization information is available, the
 258      * non-localized name is returned.
 259      *
 260      * @return localized name
 261      */
 262     public String getLocalizedName() {
 263         return getLocalizedLevelName();
 264     }
 265 
 266     // package-private getLevelName() is used by the implementation
 267     // instead of getName() to avoid calling the subclass's version
 268     final String getLevelName() {
 269         return this.name;
 270     }
 271 
 272     private String computeLocalizedLevelName(Locale newLocale) {
 273         // Resource bundle should be loaded from the defining module
 274         // or its defining class loader, if it's unnamed module,
 275         // of this Level instance that can be a custom Level subclass;
 276         Module module = this.getClass().getModule();
 277         ResourceBundle rb = ResourceBundle.getBundle(resourceBundleName,
 278                 newLocale, module);
 279 
 280         final String localizedName = rb.getString(name);
 281         final boolean isDefaultBundle = defaultBundle.equals(resourceBundleName);
 282         if (!isDefaultBundle) return localizedName;
 283 
 284         // This is a trick to determine whether the name has been translated
 285         // or not. If it has not been translated, we need to use Locale.ROOT
 286         // when calling toUpperCase().
 287         final Locale rbLocale = rb.getLocale();
 288         final Locale locale =
 289                 Locale.ROOT.equals(rbLocale)
 290                 || name.equals(localizedName.toUpperCase(Locale.ROOT))
 291                 ? Locale.ROOT : rbLocale;
 292 
 293         // ALL CAPS in a resource bundle's message indicates no translation
 294         // needed per Oracle translation guideline.  To workaround this
 295         // in Oracle JDK implementation, convert the localized level name
 296         // to uppercase for compatibility reason.
 297         return Locale.ROOT.equals(locale) ? name : localizedName.toUpperCase(locale);
 298     }
 299 
 300     // Avoid looking up the localizedLevelName twice if we already
 301     // have it.
 302     final String getCachedLocalizedLevelName() {
 303 
 304         if (localizedLevelName != null) {
 305             if (cachedLocale != null) {
 306                 if (cachedLocale.equals(Locale.getDefault())) {
 307                     // OK: our cached value was looked up with the same
 308                     //     locale. We can use it.
 309                     return localizedLevelName;
 310                 }
 311             }
 312         }
 313 
 314         if (resourceBundleName == null) {
 315             // No resource bundle: just use the name.
 316             return name;
 317         }
 318 
 319         // We need to compute the localized name.
 320         // Either because it's the first time, or because our cached
 321         // value is for a different locale. Just return null.
 322         return null;
 323     }
 324 
 325     final synchronized String getLocalizedLevelName() {
 326 
 327         // See if we have a cached localized name
 328         final String cachedLocalizedName = getCachedLocalizedLevelName();
 329         if (cachedLocalizedName != null) {
 330             return cachedLocalizedName;
 331         }
 332 
 333         // No cached localized name or cache invalid.
 334         // Need to compute the localized name.
 335         final Locale newLocale = Locale.getDefault();
 336         try {
 337             localizedLevelName = computeLocalizedLevelName(newLocale);
 338         } catch (Exception ex) {
 339             localizedLevelName = name;
 340         }
 341         cachedLocale = newLocale;
 342         return localizedLevelName;
 343     }
 344 
 345     // Returns a mirrored Level object that matches the given name as
 346     // specified in the Level.parse method.  Returns null if not found.
 347     //
 348     // It returns the same Level object as the one returned by Level.parse
 349     // method if the given name is a non-localized name or integer.
 350     //
 351     // If the name is a localized name, findLevel and parse method may
 352     // return a different level value if there is a custom Level subclass
 353     // that overrides Level.getLocalizedName() to return a different string
 354     // than what's returned by the default implementation.
 355     //
 356     static Level findLevel(String name) {
 357         if (name == null) {
 358             throw new NullPointerException();
 359         }
 360 
 361         Optional<Level> level;
 362 
 363         // Look for a known Level with the given non-localized name.
 364         level = KnownLevel.findByName(name, KnownLevel::mirrored);
 365         if (level.isPresent()) {
 366             return level.get();
 367         }
 368 
 369         // Now, check if the given name is an integer.  If so,
 370         // first look for a Level with the given value and then
 371         // if necessary create one.
 372         try {
 373             int x = Integer.parseInt(name);
 374             level = KnownLevel.findByValue(x, KnownLevel::mirrored);
 375             if (!level.isPresent()) {
 376                 // add new Level
 377                 Level levelObject = new Level(name, x);
 378                 return KnownLevel.findByValue(x, KnownLevel::mirrored).get();
 379             }

 380         } catch (NumberFormatException ex) {
 381             // Not an integer.
 382             // Drop through.
 383         }
 384 
 385         level = KnownLevel.findByLocalizedLevelName(name,
 386                 KnownLevel::mirrored);
 387         if (level.isPresent()) {
 388             return level.get();
 389         }
 390 
 391         return null;
 392     }
 393 
 394     /**
 395      * Returns a string representation of this Level.
 396      *
 397      * @return the non-localized name of the Level, for example "INFO".
 398      */
 399     @Override
 400     public final String toString() {
 401         return name;
 402     }
 403 
 404     /**
 405      * Get the integer value for this level.  This integer value
 406      * can be used for efficient ordering comparisons between
 407      * Level objects.
 408      * @return the integer value for this level.
 409      */
 410     public final int intValue() {
 411         return value;
 412     }
 413 
 414     private static final long serialVersionUID = -8176160795706313070L;
 415 
 416     // Serialization magic to prevent "doppelgangers".
 417     // This is a performance optimization.
 418     private Object readResolve() {
 419         Optional<Level> level = KnownLevel.matches(this);
 420         if (level.isPresent()) {
 421             return level.get();
 422         }

 423         // Woops.  Whoever sent us this object knows
 424         // about a new log level.  Add it to our list.
 425         return new Level(this.name, this.value, this.resourceBundleName);

 426     }
 427 
 428     /**
 429      * Parse a level name string into a Level.
 430      * <p>
 431      * The argument string may consist of either a level name
 432      * or an integer value.
 433      * <p>
 434      * For example:
 435      * <ul>
 436      * <li>     "SEVERE"
 437      * <li>     "1000"
 438      * </ul>
 439      *
 440      * @param  name   string to be parsed
 441      * @throws NullPointerException if the name is null
 442      * @throws IllegalArgumentException if the value is not valid.
 443      * Valid values are integers between <CODE>Integer.MIN_VALUE</CODE>
 444      * and <CODE>Integer.MAX_VALUE</CODE>, and all known level names.
 445      * Known names are the levels defined by this class (e.g., <CODE>FINE</CODE>,
 446      * <CODE>FINER</CODE>, <CODE>FINEST</CODE>), or created by this class with
 447      * appropriate package access, or new levels defined or created
 448      * by subclasses.
 449      *
 450      * @return The parsed value. Passing an integer that corresponds to a known name
 451      * (e.g., 700) will return the associated name (e.g., <CODE>CONFIG</CODE>).
 452      * Passing an integer that does not (e.g., 1) will return a new level name
 453      * initialized to that value.
 454      */
 455     public static synchronized Level parse(String name) throws IllegalArgumentException {
 456         // Check that name is not null.
 457         name.length();
 458 
 459         Optional<Level> level;
 460 
 461         // Look for a known Level with the given non-localized name.
 462         level = KnownLevel.findByName(name, KnownLevel::referent);
 463         if (level.isPresent()) {
 464             return level.get();
 465         }
 466 
 467         // Now, check if the given name is an integer.  If so,
 468         // first look for a Level with the given value and then
 469         // if necessary create one.
 470         try {
 471             int x = Integer.parseInt(name);
 472             level = KnownLevel.findByValue(x, KnownLevel::referent);
 473             if (level.isPresent()) {
 474                 return level.get();


 475             }
 476             // add new Level.
 477             Level levelObject = new Level(name, x);
 478             return KnownLevel.findByValue(x, KnownLevel::referent).get();
 479         } catch (NumberFormatException ex) {
 480             // Not an integer.
 481             // Drop through.
 482         }
 483 
 484         // Finally, look for a known level with the given localized name,
 485         // in the current default locale.
 486         // This is relatively expensive, but not excessively so.
 487         level = KnownLevel.findByLocalizedLevelName(name, KnownLevel::referent);
 488         if (level .isPresent()) {
 489             return level.get();
 490         }
 491 
 492         // OK, we've tried everything and failed
 493         throw new IllegalArgumentException("Bad level \"" + name + "\"");
 494     }
 495 
 496     /**
 497      * Compare two objects for value equality.
 498      * @return true if and only if the two objects have the same level value.
 499      */
 500     @Override
 501     public boolean equals(Object ox) {
 502         try {
 503             Level lx = (Level)ox;
 504             return (lx.value == this.value);
 505         } catch (Exception ex) {
 506             return false;
 507         }
 508     }
 509 
 510     /**
 511      * Generate a hashcode.
 512      * @return a hashcode based on the level value
 513      */
 514     @Override
 515     public int hashCode() {
 516         return this.value;
 517     }
 518 
 519     // KnownLevel class maintains the global list of all known levels.
 520     // The API allows multiple custom Level instances of the same name/value
 521     // be created. This class provides convenient methods to find a level
 522     // by a given name, by a given value, or by a given localized name.
 523     //
 524     // KnownLevel wraps the following Level objects:
 525     // 1. levelObject:   standard Level object or custom Level object
 526     // 2. mirroredLevel: Level object representing the level specified in the
 527     //                   logging configuration.
 528     //
 529     // Level.getName, Level.getLocalizedName, Level.getResourceBundleName methods
 530     // are non-final but the name and resource bundle name are parameters to
 531     // the Level constructor.  Use the mirroredLevel object instead of the
 532     // levelObject to prevent the logging framework to execute foreign code
 533     // implemented by untrusted Level subclass.
 534     //
 535     // Implementation Notes:
 536     // If Level.getName, Level.getLocalizedName, Level.getResourceBundleName methods
 537     // were final, the following KnownLevel implementation can be removed.
 538     // Future API change should take this into consideration.
 539     static final class KnownLevel extends WeakReference<Level> {
 540         private static Map<String, List<KnownLevel>> nameToLevels = new HashMap<>();
 541         private static Map<Integer, List<KnownLevel>> intToLevels = new HashMap<>();
 542         private static final ReferenceQueue<Level> QUEUE = new ReferenceQueue<>();
 543 
 544         final Level mirroredLevel;   // mirror of the custom Level
 545         KnownLevel(Level l) {
 546             super(l, QUEUE);
 547             if (l.getClass() == Level.class) {
 548                 this.mirroredLevel = l;
 549             } else {
 550                 // this mirrored level object is hidden
 551                 this.mirroredLevel = new Level(l.name, l.value,
 552                         l.resourceBundleName, false);
 553             }
 554         }
 555 
 556         Stream<Level> mirrored() {
 557             return Stream.of(mirroredLevel);
 558         }
 559 
 560         Stream<Level> referent() {
 561             final Level ref = get();
 562             return ref == null ? Stream.empty() : Stream.of(ref);
 563         }
 564 
 565         private void remove() {
 566             Optional.ofNullable(nameToLevels.get(mirroredLevel.name))
 567                     .ifPresent((x) -> x.remove(this));
 568             Optional.ofNullable(intToLevels.get(mirroredLevel.value))
 569                     .ifPresent((x) -> x.remove(this));
 570         }
 571 
 572         // Remove all stale KnownLevel instances
 573         static synchronized void purge() {
 574             Reference<? extends Level> ref;
 575             while ((ref = QUEUE.poll()) != null) {
 576                 if (ref instanceof KnownLevel) {
 577                     ((KnownLevel)ref).remove();
 578                 }
 579             }
 580         }
 581 
 582         static synchronized void add(Level l) {
 583             purge();
 584             // the mirroredLevel object is always added to the list
 585             // before the custom Level instance
 586             KnownLevel o = new KnownLevel(l);
 587             List<KnownLevel> list = nameToLevels.get(l.name);
 588             if (list == null) {
 589                 list = new ArrayList<>();
 590                 nameToLevels.put(l.name, list);
 591             }
 592             list.add(o);
 593 
 594             list = intToLevels.get(l.value);
 595             if (list == null) {
 596                 list = new ArrayList<>();
 597                 intToLevels.put(l.value, list);
 598             }
 599             list.add(o);
 600         }
 601 
 602         // Returns a KnownLevel with the given non-localized name.
 603         static synchronized Optional<Level> findByName(String name,
 604                 Function<KnownLevel, Stream<Level>> selector) {
 605             purge();
 606             return nameToLevels.getOrDefault(name, Collections.emptyList())
 607                         .stream()
 608                         .flatMap(selector)
 609                         .findFirst();
 610         }
 611 
 612         // Returns a KnownLevel with the given value.
 613         static synchronized Optional<Level> findByValue(int value,
 614                 Function<KnownLevel, Stream<Level>> selector) {
 615             purge();
 616             return intToLevels.getOrDefault(value, Collections.emptyList())
 617                         .stream()
 618                         .flatMap(selector)
 619                         .findFirst();
 620         }
 621 
 622         // Returns a KnownLevel with the given localized name matching
 623         // by calling the Level.getLocalizedLevelName() method (i.e. found
 624         // from the resourceBundle associated with the Level object).
 625         // This method does not call Level.getLocalizedName() that may
 626         // be overridden in a subclass implementation
 627         static synchronized Optional<Level> findByLocalizedLevelName(String name,
 628                 Function<KnownLevel, Stream<Level>> selector) {
 629             purge();
 630             return nameToLevels.values()
 631                     .stream()
 632                     .flatMap(List::stream)
 633                     .flatMap(selector)
 634                     .filter(lo -> name.equals(lo.getLocalizedLevelName()))
 635                     .findFirst();

 636         }
 637 
 638         static synchronized Optional<Level> matches(Level l) {
 639             purge();
 640             List<KnownLevel> list = nameToLevels.get(l.name);
 641             if (list != null) {
 642                 for (KnownLevel ref : list) {
 643                     Level levelObject = ref.get();
 644                     if (levelObject == null) continue;
 645                     Level other = ref.mirroredLevel;
 646                     if (l.value == other.value &&
 647                            (l.resourceBundleName == other.resourceBundleName ||
 648                                (l.resourceBundleName != null &&
 649                                 l.resourceBundleName.equals(other.resourceBundleName)))) {
 650                         return Optional.of(levelObject);
 651                     }
 652                 }
 653             }
 654             return Optional.empty();
 655         }
 656     }
 657 
 658 }
--- EOF ---