Package java.util.logging

Class Logger

  • public class Logger
extends Object
    Loggers are used to log records to a variety of destinations such as log files or the console. They use instances of Handler to actually do the destination-specific operations.

    Client applications can get named loggers by calling the getLogger methods. They can also get anonymous loggers by calling the getAnonymousLogger methods. Named loggers are organized in a namespace hierarchy managed by a log manager. The naming convention is usually the Java package naming convention. Anonymous loggers do not belong to any namespace.

    Developers should use named loggers to enable logging to be controlled on a per-Logger granularity. The recommended idiom is to create and assign the logger to a static final field. This ensures that there's always a strong reference to the logger, preventing it from being garbage collected. In particular, LogManager.addLogger(Logger) will not keep your logger live.

    Loggers "inherit" log level setting from their parent if their own level is set to null. This is also true for the resource bundle. The logger's resource bundle is used to localize the log messages if no resource bundle name is given when a log method is called. If getUseParentHandlers() returns true, loggers also inherit their parent's handlers. In this context, "inherit" only means that "behavior" is inherited. The internal field values will not change, for example, getLevel() still returns null.

    When loading a given resource bundle, the logger first tries to use the context ClassLoader. If that fails, it tries the system ClassLoader. And if that still fails, it searches up the class stack and uses each class's ClassLoader to try to locate the resource bundle.

    Some log methods accept log requests that do not specify the source class and source method. In these cases, the logging framework will automatically infer the calling class and method, but this is not guaranteed to be accurate.

    Once a LogRecord object has been passed into the logging framework, it is owned by the logging framework and the client applications should not use it any longer.

    All methods of this class are thread-safe.

    See Also:
    LogManager

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Logger​(String name, String resourceBundleName)
      Constructs a Logger object with the supplied name and resource bundle name; notifiyParentHandlers is set to true.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addHandler​(Handler handler)
      Adds a handler to this logger.
      void config​(String msg)
      Logs a message of level Level.CONFIG; the message is transmitted to all subscribed handlers.
      void entering​(String sourceClass, String sourceMethod)
      Logs a message indicating that a method has been entered.
      void entering​(String sourceClass, String sourceMethod, Object param)
      Logs a message indicating that a method has been entered.
      void entering​(String sourceClass, String sourceMethod, Object[] params)
      Logs a message indicating that a method has been entered.
      void exiting​(String sourceClass, String sourceMethod)
      Logs a message indicating that a method is exited.
      void exiting​(String sourceClass, String sourceMethod, Object result)
      Logs a message indicating that a method is exited.
      void fine​(String msg)
      Logs a message of level Level.FINE; the message is transmitted to all subscribed handlers.
      void finer​(String msg)
      Logs a message of level Level.FINER; the message is transmitted to all subscribed handlers.
      void finest​(String msg)
      Logs a message of level Level.FINEST; the message is transmitted to all subscribed handlers.
      static Logger getAnonymousLogger()
      Gets an anonymous logger to use internally in a thread.
      static Logger getAnonymousLogger​(String resourceBundleName)
      Gets an anonymous logger to use internally in a thread.
      Filter getFilter()
      Gets the filter used by this logger.
      static Logger getGlobal()
      Returns the global Logger.
      Handler[] getHandlers()
      Gets all the handlers associated with this logger.
      Level getLevel()
      Gets the logging level of this logger.
      static Logger getLogger​(String name)
      Gets a named logger.
      static Logger getLogger​(String name, String resourceBundleName)
      Gets a named logger associated with the supplied resource bundle.
      String getName()
      Gets the name of this logger, null for anonymous loggers.
      Logger getParent()
      Gets the nearest parent of this logger in the namespace, a null value will be returned if called on the root logger.
      ResourceBundle getResourceBundle()
      Gets the loaded resource bundle used by this logger to localize logging messages.
      String getResourceBundleName()
      Gets the name of the loaded resource bundle used by this logger to localize logging messages.
      boolean getUseParentHandlers()
      Gets the flag which indicates whether to use the handlers of this logger's parent to publish incoming log records, potentially recursively up the namespace.
      void info​(String msg)
      Logs a message of level Level.INFO; the message is transmitted to all subscribed handlers.
      boolean isLoggable​(Level l)
      Determines whether this logger will actually log messages of the specified level.
      void log​(Level logLevel, String msg)
      Logs a message of the specified level.
      void log​(Level logLevel, String msg, Object param)
      Logs a message of the specified level with the supplied parameter.
      void log​(Level logLevel, String msg, Object[] params)
      Logs a message of the specified level with the supplied parameter array.
      void log​(Level logLevel, String msg, Throwable thrown)
      Logs a message of the specified level with the supplied Throwable object.
      void log​(LogRecord record)
      Logs a given log record.
      void logp​(Level logLevel, String sourceClass, String sourceMethod, String msg)
      Logs a message of the given level with the specified source class name and source method name.
      void logp​(Level logLevel, String sourceClass, String sourceMethod, String msg, Object param)
      Logs a message of the given level with the specified source class name, source method name and parameter.
      void logp​(Level logLevel, String sourceClass, String sourceMethod, String msg, Object[] params)
      Logs a message of the given level with the specified source class name, source method name and parameter array.
      void logp​(Level logLevel, String sourceClass, String sourceMethod, String msg, Throwable thrown)
      Logs a message of the given level with the specified source class name, source method name and Throwable object.
      void logrb​(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg)
      Logs a message of the given level with the specified source class name and source method name, using the given resource bundle to localize the message.
      void logrb​(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg, Object param)
      Logs a message of the given level with the specified source class name, source method name and parameter, using the given resource bundle to localize the message.
      void logrb​(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg, Object[] params)
      Logs a message of the given level with the specified source class name, source method name and parameter array, using the given resource bundle to localize the message.
      void logrb​(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg, Throwable thrown)
      Logs a message of the given level with the specified source class name, source method name and Throwable object, using the given resource bundle to localize the message.
      void removeHandler​(Handler handler)
      Removes a handler from this logger.
      void setFilter​(Filter newFilter)
      Sets the filter used by this logger.
      void setLevel​(Level newLevel)
      Sets the logging level for this logger.
      void setParent​(Logger parent)
      Sets the parent of this logger in the namespace.
      void setUseParentHandlers​(boolean notifyParentHandlers)
      Sets the flag which indicates whether to use the handlers of this logger's parent, potentially recursively up the namespace.
      void severe​(String msg)
      Logs a message of level Level.SEVERE; the message is transmitted to all subscribed handlers.
      void throwing​(String sourceClass, String sourceMethod, Throwable thrown)
      Logs a message indicating that an exception is thrown.
      void warning​(String msg)
      Logs a message of level Level.WARNING; the message is transmitted to all subscribed handlers.

    • Field Detail

      • GLOBAL_LOGGER_NAME

        public static final String GLOBAL_LOGGER_NAME
        The name of the global logger. Before using this, see the discussion of how to use Logger in the class documentation.
        Since:
        1.6
        See Also:
        Constant Field Values

      • global

        @Deprecated
public static final Logger global
        Deprecated.
        This is deadlock-prone. Use Logger.getLogger(Logger.GLOBAL_LOGGER_NAME) as a direct replacement, but read the discussion of how to use Logger in the class documentation.
        The global logger is provided as convenience for casual use.

    • Constructor Detail

      • Logger

        protected Logger​(String name,
                 String resourceBundleName)
        Constructs a Logger object with the supplied name and resource bundle name; notifiyParentHandlers is set to true.

        Notice : Loggers use a naming hierarchy. Thus "z.x.y" is a child of "z.x".

        Parameters:
        name - the name of this logger, may be null for anonymous loggers.
        resourceBundleName - the name of the resource bundle used to localize logging messages, may be null.
        Throws:
        MissingResourceException - if the specified resource bundle can not be loaded.

    • Method Detail

      • getAnonymousLogger

        public static Logger getAnonymousLogger()
        Gets an anonymous logger to use internally in a thread. Anonymous loggers are not registered in the log manager's namespace. No security checks will be performed when updating an anonymous logger's control settings.

        The anonymous loggers' parent is set to be the root logger. This way it inherits the default logging level and handlers from the root logger.

        Returns:
        a new instance of anonymous logger.

      • getAnonymousLogger

        public static Logger getAnonymousLogger​(String resourceBundleName)
        Gets an anonymous logger to use internally in a thread. Anonymous loggers are not registered in the log manager's namespace. No security checks will be performed when updating an anonymous logger's control settings.

        The anonymous loggers' parent is set to be the root logger. This way it inherits default logging level and handlers from the root logger.

        Parameters:
        resourceBundleName - the name of the resource bundle used to localize log messages.
        Returns:
        a new instance of anonymous logger.
        Throws:
        MissingResourceException - if the specified resource bundle can not be loaded.

      • getLogger

        public static Logger getLogger​(String name)
        Gets a named logger. The returned logger may already exist or may be newly created. In the latter case, its level will be set to the configured level according to the LogManager's properties.
        Parameters:
        name - the name of the logger to get, cannot be null.
        Returns:
        a named logger.
        Throws:
        MissingResourceException - If the specified resource bundle can not be loaded.

      • getLogger

        public static Logger getLogger​(String name,
                               String resourceBundleName)
        Gets a named logger associated with the supplied resource bundle. The resource bundle will be used to localize logging messages.
        Parameters:
        name - the name of the logger to get, cannot be null.
        resourceBundleName - the name of the resource bundle, may be null.
        Returns:
        a named logger.
        Throws:
        IllegalArgumentException - if the logger identified by name is associated with a resource bundle and its name is not equal to resourceBundleName.
        MissingResourceException - if the name of the resource bundle cannot be found.

      • getGlobal

        public static Logger getGlobal()
        Returns the global Logger.
        Since:
        1.7

      • addHandler

        public void addHandler​(Handler handler)
        Adds a handler to this logger. The name will be fed with log records received by this logger.
        Parameters:
        handler - the handler object to add, cannot be null.

      • getHandlers

        public Handler[] getHandlers()
        Gets all the handlers associated with this logger.
        Returns:
        an array of all the handlers associated with this logger.

      • removeHandler

        public void removeHandler​(Handler handler)
        Removes a handler from this logger. If the specified handler does not exist then this method has no effect.
        Parameters:
        handler - the handler to be removed.

      • getFilter

        public Filter getFilter()
        Gets the filter used by this logger.
        Returns:
        the filter used by this logger, may be null.

      • setFilter

        public void setFilter​(Filter newFilter)
        Sets the filter used by this logger.
        Parameters:
        newFilter - the filter to set, may be null.

      • getLevel

        public Level getLevel()
        Gets the logging level of this logger. A null level indicates that this logger inherits its parent's level.
        Returns:
        the logging level of this logger.

      • setLevel

        public void setLevel​(Level newLevel)
        Sets the logging level for this logger. A null level indicates that this logger will inherit its parent's level.
        Parameters:
        newLevel - the logging level to set.

      • getUseParentHandlers

        public boolean getUseParentHandlers()
        Gets the flag which indicates whether to use the handlers of this logger's parent to publish incoming log records, potentially recursively up the namespace.
        Returns:
        true if set to use parent's handlers, false otherwise.

      • setUseParentHandlers

        public void setUseParentHandlers​(boolean notifyParentHandlers)
        Sets the flag which indicates whether to use the handlers of this logger's parent, potentially recursively up the namespace.
        Parameters:
        notifyParentHandlers - the new flag indicating whether to use the parent's handlers.

      • getParent

        public Logger getParent()
        Gets the nearest parent of this logger in the namespace, a null value will be returned if called on the root logger.
        Returns:
        the parent of this logger in the namespace.

      • setParent

        public void setParent​(Logger parent)
        Sets the parent of this logger in the namespace. This method should be used by the LogManager object only.
        Parameters:
        parent - the parent logger to set.

      • getName

        public String getName()
        Gets the name of this logger, null for anonymous loggers.
        Returns:
        the name of this logger.

      • getResourceBundle

        public ResourceBundle getResourceBundle()
        Gets the loaded resource bundle used by this logger to localize logging messages. If the value is null, the parent's resource bundle will be inherited.
        Returns:
        the loaded resource bundle used by this logger.

      • getResourceBundleName

        public String getResourceBundleName()
        Gets the name of the loaded resource bundle used by this logger to localize logging messages. If the value is null, the parent's resource bundle name will be inherited.
        Returns:
        the name of the loaded resource bundle used by this logger.

      • isLoggable

        public boolean isLoggable​(Level l)
        Determines whether this logger will actually log messages of the specified level. The effective level used to do the determination may be inherited from its parent. The default level is Level.INFO.
        Parameters:
        l - the level to check.
        Returns:
        true if this logger will actually log this level, otherwise false.

      • entering

        public void entering​(String sourceClass,
                     String sourceMethod)
        Logs a message indicating that a method has been entered. A log record with log level Level.FINER, log message "ENTRY", the specified source class name and source method name is submitted for logging.
        Parameters:
        sourceClass - the calling class name.
        sourceMethod - the method name.

      • entering

        public void entering​(String sourceClass,
                     String sourceMethod,
                     Object param)
        Logs a message indicating that a method has been entered. A log record with log level Level.FINER, log message "ENTRY", the specified source class name, source method name and one parameter is submitted for logging.
        Parameters:
        sourceClass - the source class name.
        sourceMethod - the source method name.
        param - the parameter for the method call.

      • entering

        public void entering​(String sourceClass,
                     String sourceMethod,
                     Object[] params)
        Logs a message indicating that a method has been entered. A log record with log level Level.FINER, log message "ENTRY", the specified source class name, source method name and array of parameters is submitted for logging.
        Parameters:
        sourceClass - the source class name.
        sourceMethod - the source method name.
        params - an array of parameters for the method call.

      • exiting

        public void exiting​(String sourceClass,
                    String sourceMethod)
        Logs a message indicating that a method is exited. A log record with log level Level.FINER, log message "RETURN", the specified source class name and source method name is submitted for logging.
        Parameters:
        sourceClass - the calling class name.
        sourceMethod - the method name.

      • exiting

        public void exiting​(String sourceClass,
                    String sourceMethod,
                    Object result)
        Logs a message indicating that a method is exited. A log record with log level Level.FINER, log message "RETURN", the specified source class name, source method name and return value is submitted for logging.
        Parameters:
        sourceClass - the source class name.
        sourceMethod - the source method name.
        result - the return value of the method call.

      • throwing

        public void throwing​(String sourceClass,
                     String sourceMethod,
                     Throwable thrown)
        Logs a message indicating that an exception is thrown. A log record with log level Level.FINER, log message "THROW", the specified source class name, source method name and the Throwable object is submitted for logging.
        Parameters:
        sourceClass - the source class name.
        sourceMethod - the source method name.
        thrown - the Throwable object.

      • severe

        public void severe​(String msg)
        Logs a message of level Level.SEVERE; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • warning

        public void warning​(String msg)
        Logs a message of level Level.WARNING; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • info

        public void info​(String msg)
        Logs a message of level Level.INFO; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • config

        public void config​(String msg)
        Logs a message of level Level.CONFIG; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • fine

        public void fine​(String msg)
        Logs a message of level Level.FINE; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • finer

        public void finer​(String msg)
        Logs a message of level Level.FINER; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • finest

        public void finest​(String msg)
        Logs a message of level Level.FINEST; the message is transmitted to all subscribed handlers.
        Parameters:
        msg - the message to log.

      • log

        public void log​(Level logLevel,
                String msg)
        Logs a message of the specified level. The message is transmitted to all subscribed handlers.
        Parameters:
        logLevel - the level of the specified message.
        msg - the message to log.

      • log

        public void log​(Level logLevel,
                String msg,
                Object param)
        Logs a message of the specified level with the supplied parameter. The message is then transmitted to all subscribed handlers.
        Parameters:
        logLevel - the level of the given message.
        msg - the message to log.
        param - the parameter associated with the event that is logged.

      • log

        public void log​(Level logLevel,
                String msg,
                Object[] params)
        Logs a message of the specified level with the supplied parameter array. The message is then transmitted to all subscribed handlers.
        Parameters:
        logLevel - the level of the given message
        msg - the message to log.
        params - the parameter array associated with the event that is logged.

      • log

        public void log​(Level logLevel,
                String msg,
                Throwable thrown)
        Logs a message of the specified level with the supplied Throwable object. The message is then transmitted to all subscribed handlers.
        Parameters:
        logLevel - the level of the given message.
        msg - the message to log.
        thrown - the Throwable object associated with the event that is logged.

      • log

        public void log​(LogRecord record)
        Logs a given log record. Only records with a logging level that is equal or greater than this logger's level will be submitted to this logger's handlers for logging. If getUseParentHandlers() returns true, the log record will also be submitted to the handlers of this logger's parent, potentially recursively up the namespace.

        Since all other log methods call this method to actually perform the logging action, subclasses of this class can override this method to catch all logging activities.

        Parameters:
        record - the log record to be logged.

      • logp

        public void logp​(Level logLevel,
                 String sourceClass,
                 String sourceMethod,
                 String msg)
        Logs a message of the given level with the specified source class name and source method name.
        Parameters:
        logLevel - the level of the given message.
        sourceClass - the source class name.
        sourceMethod - the source method name.
        msg - the message to be logged.

      • logp

        public void logp​(Level logLevel,
                 String sourceClass,
                 String sourceMethod,
                 String msg,
                 Object param)
        Logs a message of the given level with the specified source class name, source method name and parameter.
        Parameters:
        logLevel - the level of the given message
        sourceClass - the source class name
        sourceMethod - the source method name
        msg - the message to be logged
        param - the parameter associated with the event that is logged.

      • logp

        public void logp​(Level logLevel,
                 String sourceClass,
                 String sourceMethod,
                 String msg,
                 Object[] params)
        Logs a message of the given level with the specified source class name, source method name and parameter array.
        Parameters:
        logLevel - the level of the given message.
        sourceClass - the source class name.
        sourceMethod - the source method name.
        msg - the message to be logged.
        params - the parameter array associated with the event that is logged.

      • logp

        public void logp​(Level logLevel,
                 String sourceClass,
                 String sourceMethod,
                 String msg,
                 Throwable thrown)
        Logs a message of the given level with the specified source class name, source method name and Throwable object.
        Parameters:
        logLevel - the level of the given message.
        sourceClass - the source class name.
        sourceMethod - the source method name.
        msg - the message to be logged.
        thrown - the Throwable object.

      • logrb

        public void logrb​(Level logLevel,
                  String sourceClass,
                  String sourceMethod,
                  String bundleName,
                  String msg)
        Logs a message of the given level with the specified source class name and source method name, using the given resource bundle to localize the message. If bundleName is null, the empty string or not valid then the message is not localized.
        Parameters:
        logLevel - the level of the given message.
        sourceClass - the source class name.
        sourceMethod - the source method name.
        bundleName - the name of the resource bundle used to localize the message.
        msg - the message to be logged.

      • logrb

        public void logrb​(Level logLevel,
                  String sourceClass,
                  String sourceMethod,
                  String bundleName,
                  String msg,
                  Object param)
        Logs a message of the given level with the specified source class name, source method name and parameter, using the given resource bundle to localize the message. If bundleName is null, the empty string or not valid then the message is not localized.
        Parameters:
        logLevel - the level of the given message.
        sourceClass - the source class name.
        sourceMethod - the source method name.
        bundleName - the name of the resource bundle used to localize the message.
        msg - the message to be logged.
        param - the parameter associated with the event that is logged.

      • logrb

        public void logrb​(Level logLevel,
                  String sourceClass,
                  String sourceMethod,
                  String bundleName,
                  String msg,
                  Object[] params)
        Logs a message of the given level with the specified source class name, source method name and parameter array, using the given resource bundle to localize the message. If bundleName is null, the empty string or not valid then the message is not localized.
        Parameters:
        logLevel - the level of the given message.
        sourceClass - the source class name.
        sourceMethod - the source method name.
        bundleName - the name of the resource bundle used to localize the message.
        msg - the message to be logged.
        params - the parameter array associated with the event that is logged.

      • logrb

        public void logrb​(Level logLevel,
                  String sourceClass,
                  String sourceMethod,
                  String bundleName,
                  String msg,
                  Throwable thrown)
        Logs a message of the given level with the specified source class name, source method name and Throwable object, using the given resource bundle to localize the message. If bundleName is null, the empty string or not valid then the message is not localized.
        Parameters:
        logLevel - the level of the given message
        sourceClass - the source class name
        sourceMethod - the source method name
        bundleName - the name of the resource bundle used to localize the message.
        msg - the message to be logged.
        thrown - the Throwable object.