* Clients should normally use the predefined Level constants such * as Level.SEVERE. *
* The levels in descending order are: *
* It is possible for third parties to define additional logging
* levels by subclassing Level. In such cases subclasses should
* take care to chose unique integer level values and to ensure that
* they maintain the Object uniqueness property across serialization
* by defining a suitable readResolve method.
*
* @since 1.4
*/
public class Level implements java.io.Serializable {
private static final String defaultBundle = "sun.util.logging.resources.logging";
/**
* @serial The non-localized name of the level.
*/
private final String name;
/**
* @serial The integer value of the level.
*/
private final int value;
/**
* @serial The resource bundle name to be used in localizing the level name.
*/
private final String resourceBundleName;
// localized level name
private transient String localizedLevelName;
private transient Locale cachedLocale;
/**
* OFF is a special level that can be used to turn off logging.
* This level is initialized to Integer.MAX_VALUE.
*/
public static final Level OFF = new Level("OFF",Integer.MAX_VALUE, defaultBundle);
/**
* SEVERE is a message level indicating a serious failure.
*
* In general SEVERE messages should describe events that are
* of considerable importance and which will prevent normal
* program execution. They should be reasonably intelligible
* to end users and to system administrators.
* This level is initialized to 1000.
*/
public static final Level SEVERE = new Level("SEVERE",1000, defaultBundle);
/**
* WARNING is a message level indicating a potential problem.
*
* In general WARNING messages should describe events that will
* be of interest to end users or system managers, or which
* indicate potential problems.
* This level is initialized to 900.
*/
public static final Level WARNING = new Level("WARNING", 900, defaultBundle);
/**
* INFO is a message level for informational messages.
*
* Typically INFO messages will be written to the console
* or its equivalent. So the INFO level should only be
* used for reasonably significant messages that will
* make sense to end users and system administrators.
* This level is initialized to 800.
*/
public static final Level INFO = new Level("INFO", 800, defaultBundle);
/**
* CONFIG is a message level for static configuration messages.
*
* CONFIG messages are intended to provide a variety of static
* configuration information, to assist in debugging problems
* that may be associated with particular configurations.
* For example, CONFIG message might include the CPU type,
* the graphics depth, the GUI look-and-feel, etc.
* This level is initialized to 700.
*/
public static final Level CONFIG = new Level("CONFIG", 700, defaultBundle);
/**
* FINE is a message level providing tracing information.
*
* All of FINE, FINER, and FINEST are intended for relatively * detailed tracing. The exact meaning of the three levels will * vary between subsystems, but in general, FINEST should be used * for the most voluminous detailed output, FINER for somewhat * less detailed output, and FINE for the lowest volume (and * most important) messages. *
* In general the FINE level should be used for information * that will be broadly interesting to developers who do not have * a specialized interest in the specific subsystem. *
* FINE messages might include things like minor (recoverable)
* failures. Issues indicating potential performance problems
* are also worth logging as FINE.
* This level is initialized to 500.
*/
public static final Level FINE = new Level("FINE", 500, defaultBundle);
/**
* FINER indicates a fairly detailed tracing message.
* By default logging calls for entering, returning, or throwing
* an exception are traced at this level.
* This level is initialized to 400.
*/
public static final Level FINER = new Level("FINER", 400, defaultBundle);
/**
* FINEST indicates a highly detailed tracing message.
* This level is initialized to 300.
*/
public static final Level FINEST = new Level("FINEST", 300, defaultBundle);
/**
* ALL indicates that all messages should be logged.
* This level is initialized to Integer.MIN_VALUE.
*/
public static final Level ALL = new Level("ALL", Integer.MIN_VALUE, defaultBundle);
/**
* Create a named Level with a given integer value.
*
* Note that this constructor is "protected" to allow subclassing. * In general clients of logging should use one of the constant Level * objects such as SEVERE or FINEST. However, if clients need to * add new logging levels, they may subclass Level and define new * constants. * @param name the name of the Level, for example "SEVERE". * @param value an integer value for the level. * @throws NullPointerException if the name is null */ protected Level(String name, int value) { this(name, value, null); } /** * Create a named Level with a given integer value and a * given localization resource name. * * @param name the name of the Level, for example "SEVERE". * @param value an integer value for the level. * @param resourceBundleName name of a resource bundle to use in * localizing the given name. If the resourceBundleName is null * or an empty string, it is ignored. * @throws NullPointerException if the name is null */ protected Level(String name, int value, String resourceBundleName) { this(name, value, resourceBundleName, true); } // private constructor to specify whether this instance should be added // to the KnownLevel list from which Level.parse method does its look up private Level(String name, int value, String resourceBundleName, boolean visible) { if (name == null) { throw new NullPointerException(); } this.name = name; this.value = value; this.resourceBundleName = resourceBundleName; this.localizedLevelName = resourceBundleName == null ? name : null; this.cachedLocale = null; if (visible) { KnownLevel.add(this); } } /** * Return the level's localization resource bundle name, or * null if no localization bundle is defined. * * @return localization resource bundle name */ public String getResourceBundleName() { return resourceBundleName; } /** * Return the non-localized string name of the Level. * * @return non-localized name */ public String getName() { return name; } /** * Return the localized string name of the Level, for * the current default locale. *
* If no localization information is available, the * non-localized name is returned. * * @return localized name */ public String getLocalizedName() { return getLocalizedLevelName(); } // package-private getLevelName() is used by the implementation // instead of getName() to avoid calling the subclass's version final String getLevelName() { return this.name; } private String computeLocalizedLevelName(Locale newLocale) { // Resource bundle should be loaded from the defining module // or its defining class loader, if it's unnamed module, // of this Level instance that can be a custom Level subclass; Module module = this.getClass().getModule(); ResourceBundle rb = ResourceBundle.getBundle(resourceBundleName, newLocale, module); final String localizedName = rb.getString(name); final boolean isDefaultBundle = defaultBundle.equals(resourceBundleName); if (!isDefaultBundle) return localizedName; // This is a trick to determine whether the name has been translated // or not. If it has not been translated, we need to use Locale.ROOT // when calling toUpperCase(). final Locale rbLocale = rb.getLocale(); final Locale locale = Locale.ROOT.equals(rbLocale) || name.equals(localizedName.toUpperCase(Locale.ROOT)) ? Locale.ROOT : rbLocale; // ALL CAPS in a resource bundle's message indicates no translation // needed per Oracle translation guideline. To workaround this // in Oracle JDK implementation, convert the localized level name // to uppercase for compatibility reason. return Locale.ROOT.equals(locale) ? name : localizedName.toUpperCase(locale); } // Avoid looking up the localizedLevelName twice if we already // have it. final String getCachedLocalizedLevelName() { if (localizedLevelName != null) { if (cachedLocale != null) { if (cachedLocale.equals(Locale.getDefault())) { // OK: our cached value was looked up with the same // locale. We can use it. return localizedLevelName; } } } if (resourceBundleName == null) { // No resource bundle: just use the name. return name; } // We need to compute the localized name. // Either because it's the first time, or because our cached // value is for a different locale. Just return null. return null; } final synchronized String getLocalizedLevelName() { // See if we have a cached localized name final String cachedLocalizedName = getCachedLocalizedLevelName(); if (cachedLocalizedName != null) { return cachedLocalizedName; } // No cached localized name or cache invalid. // Need to compute the localized name. final Locale newLocale = Locale.getDefault(); try { localizedLevelName = computeLocalizedLevelName(newLocale); } catch (Exception ex) { localizedLevelName = name; } cachedLocale = newLocale; return localizedLevelName; } // Returns a mirrored Level object that matches the given name as // specified in the Level.parse method. Returns null if not found. // // It returns the same Level object as the one returned by Level.parse // method if the given name is a non-localized name or integer. // // If the name is a localized name, findLevel and parse method may // return a different level value if there is a custom Level subclass // that overrides Level.getLocalizedName() to return a different string // than what's returned by the default implementation. // static Level findLevel(String name) { if (name == null) { throw new NullPointerException(); } KnownLevel level; // Look for a known Level with the given non-localized name. level = KnownLevel.findByName(name); if (level != null) { return level.mirroredLevel; } // Now, check if the given name is an integer. If so, // first look for a Level with the given value and then // if necessary create one. try { int x = Integer.parseInt(name); level = KnownLevel.findByValue(x); if (level == null) { // add new Level Level levelObject = new Level(name, x); level = KnownLevel.findByValue(x); } return level.mirroredLevel; } catch (NumberFormatException ex) { // Not an integer. // Drop through. } level = KnownLevel.findByLocalizedLevelName(name); if (level != null) { return level.mirroredLevel; } return null; } /** * Returns a string representation of this Level. * * @return the non-localized name of the Level, for example "INFO". */ @Override public final String toString() { return name; } /** * Get the integer value for this level. This integer value * can be used for efficient ordering comparisons between * Level objects. * @return the integer value for this level. */ public final int intValue() { return value; } private static final long serialVersionUID = -8176160795706313070L; // Serialization magic to prevent "doppelgangers". // This is a performance optimization. private Object readResolve() { Level level; KnownLevel ref; do { ref = KnownLevel.matches(this); level = KnownLevel.levelObject(ref); if (level != null) return level; } while (ref != null); // Woops. Whoever sent us this object knows // about a new log level. Add it to our list. level = new Level(this.name, this.value, this.resourceBundleName); return level; } /** * Parse a level name string into a Level. *
* The argument string may consist of either a level name * or an integer value. *
* For example: *
Integer.MIN_VALUE
* and Integer.MAX_VALUE, and all known level names.
* Known names are the levels defined by this class (e.g., FINE,
* FINER, FINEST), or created by this class with
* appropriate package access, or new levels defined or created
* by subclasses.
*
* @return The parsed value. Passing an integer that corresponds to a known name
* (e.g., 700) will return the associated name (e.g., CONFIG).
* Passing an integer that does not (e.g., 1) will return a new level name
* initialized to that value.
*/
public static synchronized Level parse(String name) throws IllegalArgumentException {
// Check that name is not null.
name.length();
KnownLevel ref;
Level level;
// Look for a known Level with the given non-localized name.
do {
ref = KnownLevel.findByName(name);
level = KnownLevel.levelObject(ref);
if (level != null) return level;
} while (ref != null);
// Now, check if the given name is an integer. If so,
// first look for a Level with the given value and then
// if necessary create one.
try {
int x = Integer.parseInt(name);
do {
ref = KnownLevel.findByValue(x);
level = KnownLevel.levelObject(ref);
if (level != null) return level;
} while (ref != null);
// add new Level.
Level levelObject = new Level(name, x);
ref = KnownLevel.findByValue(x);
return KnownLevel.levelObject(ref);
} catch (NumberFormatException ex) {
// Not an integer.
// Drop through.
}
// Finally, look for a known level with the given localized name,
// in the current default locale.
// This is relatively expensive, but not excessively so.
do {
ref = KnownLevel.findByLocalizedLevelName(name);
level = KnownLevel.levelObject(ref);
if (level != null) return level;
} while (ref != null);
// OK, we've tried everything and failed
throw new IllegalArgumentException("Bad level \"" + name + "\"");
}
/**
* Compare two objects for value equality.
* @return true if and only if the two objects have the same level value.
*/
@Override
public boolean equals(Object ox) {
try {
Level lx = (Level)ox;
return (lx.value == this.value);
} catch (Exception ex) {
return false;
}
}
/**
* Generate a hashcode.
* @return a hashcode based on the level value
*/
@Override
public int hashCode() {
return this.value;
}
// KnownLevel class maintains the global list of all known levels.
// The API allows multiple custom Level instances of the same name/value
// be created. This class provides convenient methods to find a level
// by a given name, by a given value, or by a given localized name.
//
// KnownLevel wraps the following Level objects:
// 1. levelObject: standard Level object or custom Level object
// 2. mirroredLevel: Level object representing the level specified in the
// logging configuration.
//
// Level.getName, Level.getLocalizedName, Level.getResourceBundleName methods
// are non-final but the name and resource bundle name are parameters to
// the Level constructor. Use the mirroredLevel object instead of the
// levelObject to prevent the logging framework to execute foreign code
// implemented by untrusted Level subclass.
//
// Implementation Notes:
// If Level.getName, Level.getLocalizedName, Level.getResourceBundleName methods
// were final, the following KnownLevel implementation can be removed.
// Future API change should take this into consideration.
static final class KnownLevel extends WeakReference