模块  java.logging
软件包  java.util.logging

Class LogManager

  • public class LogManagerextends Object
    有一个全局LogManager对象，用于维护有关Loggers和日志服务的一组共享状态。

    这个LogManager对象：

    • 管理Logger对象的分层命名空间。 所有命名的记录器都存储在此命名空间中。
    • 管理一组日志记录控制属性。 这些是简单的键值对，处理程序和其他日志记录对象可以使用它们进行自我配置。

    可以使用LogManager.getLogManager（）检索全局LogManager对象。 LogManager对象是在类初始化期间创建的，随后无法更改。

    在启动时，使用java.util.logging.manager系统属性找到LogManager类。

    LogManager配置

    在LogManager初始化期间，LogManager通过readConfiguration()方法初始化日志记录配置。 默认情况下，使用LogManager默认配置。 LogManager读取的日志记录配置必须采用properties file格式。

    LogManager定义了两个可选的系统属性，允许控制初始配置，如readConfiguration()方法中所指定：

    • “java.util.logging.config.class”
    • “java.util.logging.config.file”

    可以在命令行上将这两个系统属性指定为“java”命令，或者作为传递给JNI_CreateJavaVM的系统属性定义。

    记录器和处理程序的properties将具有以处理程序或记录器的点分隔名称开头的名称。
    全局日志记录属性可能包括：

    • 属性“处理程序”。 这为处理程序类定义了一个以空格或逗号分隔的类名列表，以便在根Logger（名为“”的Logger）上加载和注册为处理程序。 每个类名必须是具有默认构造函数的Handler类。 请注意，这些处理程序可能会在首次使用时延迟创建。
    • 属性“<logger> .handlers”。 这为处理程序类定义了一个以空格或逗号分隔的类名列表，以便加载和注册为指定记录程序的处理程序。 每个类名必须是具有默认构造函数的Handler类。 请注意，这些处理程序可能会在首次使用时延迟创建。
    • 属性“<logger> .handlers.ensureCloseOnReset”。 这定义了一个布尔值。 如果未定义“<logger> .handlers”或为空，则忽略此属性。 否则默认为true 。 当值为true ，保证在reset()关闭与记录器关联的处理程序并关闭。 可以通过在配置中显式设置“<logger> .handlers.ensureCloseOnReset = false”来关闭此功能。 请注意，关闭此属性会导致引入资源泄漏的风险，因为在调用reset()之前，记录器可能会收集垃圾，从而阻止其处理程序在reset()上关闭。 在这种情况下，应用程序有责任确保在记录器被垃圾收集之前关闭处理程序。
    • 属性“<logger> .useParentHandlers”。 这定义了一个布尔值。 默认情况下，除了处理日志消息本身之外，每个记录器都会调用其父记录，这通常也会导致消息由根记录器处理。 将此属性设置为false时，需要为此记录器配置Handler，否则不会传递任何记录消息。
    • 属性“config”。 此属性旨在允许运行任意配置代码。 该属性定义了一个以空格或逗号分隔的类名列表。 将为每个命名类创建一个新实例。 每个类的默认构造函数可以执行任意代码来更新日志记录配置，例如设置记录器级别，添加处理程序，添加过滤器等。

    请注意，在任何用户类路径之前，首先在系统类路径上搜索在LogManager配置期间加载的所有类。 这包括LogManager类，任何配置类和任何处理程序类。

    记录器根据点分隔名称组织成命名层次结构。 因此“abc”是“ab”的孩子，但“a.b1”和a.b2“是同龄人。

    名称以“.level”结尾的所有属性都假定为Loggers定义日志级别。 因此，“foo.level”为命名层次结构中的任何子项定义了一个名为“foo”和（递归）的记录器的日志级别。 日志级别按属性文件中定义的顺序应用。 因此，树中子节点的级别设置应该在其父级的设置之后进行。 属性名称“.level”可用于设置树根的级别。

    LogManager对象上的所有方法都是多线程安全的。

    从以下版本开始：
    1.4

    • 构造方法详细信息

      • LogManager

        protected LogManager()
        受保护的构造函数。 这是受保护的，因此容器应用程序（例如J2EE容器）可以对该对象进行子类化。 它是非公共的，因为只有一个LogManager对象，其值通过调用LogManager.getLogManager来检索。

    • 方法详细信息

      • getLogManager

        public static LogManager getLogManager()
        返回全局LogManager对象。
        结果
        全局LogManager对象

      • addLogger

        public boolean addLogger​(Logger logger)
        添加命名记录器。 如果已经注册了具有相同名称的记录器，则不执行任何操作并返回false。

        Logger工厂方法调用此方法来注册每个新创建的Logger。

        应用程序应保留自己对Logger对象的引用，以避免被垃圾回收。 LogManager可能只保留弱引用。

        参数
        logger - 新的记录器。
        结果
        如果参数记录器已成功注册，则返回true;如果已存在该名称的记录器，则返回false。
        异常
        NullPointerException - 如果记录器名称为null。

      • getLogger

        public Logger getLogger​(String name)
        查找命名记录器的方法。

        请注意，由于不受信任的代码可能会创建具有任意名称的记录器，因此不应依赖此方法来查找用于安全敏感日志记录的记录器。 同样重要的是要注意，如果没有对Logger的强引用，则可以随时对与字符串name相关联的Logger进行垃圾收集。 此方法的调用方必须检查null的返回值，以便正确处理Logger已被垃圾回收的情况。

        参数
        name - 记录器的名称
        结果
        匹配记录器，如果没有找到则为null

      • getLoggerNames

        public Enumeration<String> getLoggerNames()
        获取已知记录器名称的枚举。

        注意：可以在加载新类时动态添加记录器。 此方法仅报告当前已注册的记录器。 同样重要的是要注意，此方法仅返回Logger的名称，而不是Logger本身的强引用。 返回的String不会阻止Logger被垃圾回收。 特别是，如果返回的名称传递给LogManager.getLogger() ，则调用者必须检查LogManager.getLogger()的返回值LogManager.getLogger()为null，以正确处理自此方法返回其名称以来垃圾收集的情况。

        结果
        记录器名称字符串的枚举

      • readConfiguration

        public void readConfiguration()                       throws IOException,                              SecurityException
        读取并初始化日志记录配置。

        如果设置了“java.util.logging.config.class”系统属性，则将属性值视为类名。 将加载给定的类，将实例化一个对象，并且该对象的构造函数负责读取初始配置。 （该对象可以使用其他系统属性来控制其配置。）备用配置类可以使用readConfiguration(InputStream)在LogManager中定义属性。

        如果未设置“java.util.logging.config.class”系统属性，则此方法将从属性文件中读取初始配置，并调用readConfiguration(InputStream)方法初始化配置。 “java.util.logging.config.file”系统属性可用于指定将作为初始配置读取的属性文件; 如果未设置，则使用LogManager默认配置。 通常从Java安装目录中的属性文件“ conf/logging.properties ”加载默认配置。

        读取属性后将调用任何registered configuration listener 。

        API Note:
        此readConfiguration方法仅应用于在LogManager初始化期间初始化配置或与“java.util.logging.config.class”属性一起使用。 在创建记录器后调用此方法，并且未设置“java.util.logging.config.class”系统属性时，所有现有记录器将为reset 。 然后，在新配置流中指定了level属性的任何现有记录器将是指定日志级别的set 。

        要正确更新日志记录配置，请改用updateConfiguration(java.util.function.Function)或updateConfiguration(java.io.InputStream, java.util.function.Function)方法。

        异常
        SecurityException - 如果存在安全管理器且调用者没有LoggingPermission（“control”）。
        IOException - 如果读取配置存在IO问题。

      • updateConfiguration

        public void updateConfiguration​(Function<String,​BiFunction<String,​String,​String>> mapper)                         throws IOException
        更新日志记录配置。

        如果设置了“java.util.logging.config.file”系统属性，则属性值指定要作为新配置读取的属性文件。 否则，使用LogManager默认配置。
        通常从Java安装目录中的属性文件“ conf/logging.properties ”加载默认配置。

        此方法读取新配置并调用updateConfiguration(ins, mapper)方法来更新配置。

        API Note:
        此方法通过读取属性文件更新日志记录配置，并忽略“java.util.logging.config.class”系统属性。 “java.util.logging.config.class”属性仅由readConfiguration()方法用于将自定义配置类作为初始配置加载。
        参数
        mapper - 一个功能接口，它接受配置密钥k并返回一个函数f（o，n），其返回值将应用于结果配置。 函数f可以返回null以指示属性k将不被添加到结果配置中。
        如果mapper为null然后(k) -> ((o, n) -> n)假设。
        对于每个k ，将使用与旧配置中的k相关联的值（即o ）以及与新配置中的k相关联的值（即n ）来调用映射函数f 。
        o或n的值为null表示相应配置中的k没有值。
        异常
        SecurityException - 如果存在安全管理器且调用者没有LoggingPermission（“control”），或者没有设置配置所需的权限（例如，为FileHandlers等指定的打开文件...）
        NullPointerException - 如果 mapper在调用时返回 null函数。
        IOException - 如果从日志记录配置文件中读取时出现问题。
        从以下版本开始：
        9
        另请参见：
        updateConfiguration(java.io.InputStream, java.util.function.Function)

      • updateConfiguration

        public void updateConfiguration​(InputStream ins,                                Function<String,​BiFunction<String,​String,​String>> mapper)                         throws IOException
        更新日志记录配置。

        对于existing configuration中的每个配置键和给定的输入流配置，调用给定的mapper函数以从配置键映射到函数f（o，n） ，该函数获取旧值和新值并返回结果值要在结果配置中应用，如下表所示。

        令k为旧配置或新配置中的配置密钥， o为旧值（即旧配置中与k相关联的值）， n为新值（即新配置中与k关联的值），以及f是mapper.apply( k )返回的函数：则v = f（o，n）是结果值。 如果v不是null ，则将值v的属性k添加到结果配置中。 否则，将省略。
        可以将null值传递给函数f以指示相应的配置没有配置密钥k 。 函数f可以返回null以指示在结果配置中将不存在与k相关联的值。

        如果mapper是null ，则v将设置为n 。

        LogManager properties将使用生成的配置中的结果值进行更新。

        配置成功更新后，将调用已注册的configuration listeners 。

        Updating configuration properties Property Resulting Behavior <logger>.level
        • If the resulting configuration defines a level for a logger and if the resulting level is different than the level specified in the the old configuration, or not specified in the old configuration, then if the logger exists or if children for that logger exist, the level for that logger will be updated, and the change propagated to any existing logger children. This may cause the logger to be created, if necessary.
        • If the old configuration defined a level for a logger, and the resulting configuration doesn't, then this change will not be propagated to existing loggers, if any. To completely replace a configuration - the caller should therefore call reset to empty the current configuration, before calling updateConfiguration.
        <logger>.useParentHandlers
        • If either the resulting or the old value for the useParentHandlers property is not null, then if the logger exists or if children for that logger exist, that logger will be updated to the resulting value. The value of the useParentHandlers property is the value specified in the configuration; if not specified, the default is true.
        <logger>.handlers
        • If the resulting configuration defines a list of handlers for a logger, and if the resulting list is different than the list specified in the old configuration for that logger (that could be empty), then if the logger exists or its children exist, the handlers associated with that logger are closed and removed and the new handlers will be created per the resulting configuration and added to that logger, creating that logger if necessary.
        • If the old configuration defined some handlers for a logger, and the resulting configuration doesn't, if that logger exists, its handlers will be removed and closed.
        • Changing the list of handlers on an existing logger will cause all its previous handlers to be removed and closed, regardless of whether they had been created from the configuration or programmatically. The old handlers will be replaced by new handlers, if any.
        <handler-name>.*
        • Properties configured/changed on handler classes will only affect newly created handlers. If a node is configured with the same list of handlers in the old and the resulting configuration, then these handlers will remain unchanged.
        config and any other property
        • The resulting value for these property will be stored in the LogManager properties, but updateConfiguration will not parse or process their values.

        示例映射器函数：

        • 使用新配置替换所有日志记录属性：

          (k) -> ((o, n) -> n) ：

          这相当于传递null mapper参数。
        • 合并新配置和旧配置，如果新配置中存在k ，则使用新值：

          (k) -> ((o, n) -> n == null ? o : n) ：

          好像合并两个集合如下： result.putAll(oldc); result.putAll(newc) 。
        • 合并新配置和旧配置，如果旧配置中存在k ，则使用旧值：

          (k) -> ((o, n) -> o == null ? n : o) ：

          好像合并两个集合如下： result.putAll(newc); result.putAll(oldc) 。
        • 使用除handler处理程序属性之外的新配置替换所有属性，以配置不是root logger的Logger处理程序： 
            (k) -> k.endsWith(".handlers")       ? ((o, n) -> (o == null ? n : o))       : ((o, n) -> n)

        要完全重新初始化配置，应用程序可以先调用reset完全删除旧的配置，其次为updateConfiguration初始化新配置。

        参数
        ins - 从中读取属性的流
        mapper - 一个功能接口，它接受配置密钥k并返回一个函数f（o，n），其返回值将应用于结果配置。 函数f可以返回null以指示属性k将不被添加到结果配置中。
        如果mapper为null然后(k) -> ((o, n) -> n)假设。
        对于每个k ，将使用与旧配置中的k相关联的值（即o ）以及与新配置中的k相关联的值（即n ）来调用映射函数f 。
        o或n的值为null表示相应配置中的k没有值。
        异常
        SecurityException - 如果存在安全管理器且调用者没有LoggingPermission（“control”），或者没有设置配置所需的权限（例如，为FileHandlers指定的打开文件）
        NullPointerException - 如果 ins为null或 mapper在调用时返回null函数。
        IOException - 如果从流中读取时出现问题，或者给定的流不是properties file格式。
        从以下版本开始：
        9

      • getProperty

        public String getProperty​(String name)
        获取日志记录属性的值。 如果未找到该属性，则该方法返回null。
        参数
        name - 房产名称
        结果
        适当的价值

      • checkAccess

        public void checkAccess()                 throws SecurityException
        检查当前上下文是否可信，以修改日志记录配置。 这需要LoggingPermission（“control”）。

        如果检查失败，我们抛出SecurityException，否则我们正常返回。

        异常
        SecurityException - 如果存在安全管理器且调用者没有LoggingPermission（“control”）。

      • addConfigurationListener

        public LogManager addConfigurationListener​(Runnable listener)
        添加每次读取日志记录配置时要调用的配置侦听器。 如果监听器已经注册，则该方法不执行任何操作。

        使用此方法的调用上下文限制的权限调用侦听器。 未指定调用侦听器的顺序。

        建议侦听器不要抛出错误或异常。 如果侦听器以未被捕获的错误或异常终止，则在调用所有侦听器之后，第一个异常将传播到调用程序readConfiguration() （或readConfiguration(java.io.InputStream) ）。

        Implementation Note:
        如果多个侦听器因未捕获的错误或异常而终止，则实现可能会将其他错误或异常记录为 suppressed exceptions 。
        参数
        listener - 配置更改后将调用的配置侦听器。
        结果
        这个LogManager。
        异常
        SecurityException - 如果存在安全管理器且调用者没有LoggingPermission（“control”）。
        NullPointerException - 如果侦听器为null。
        从以下版本开始：
        9

      • removeConfigurationListener

        public void removeConfigurationListener​(Runnable listener)
        删除以前注册的配置侦听器。 如果未找到侦听器，则以静默方式返回。
        参数
        listener - 要删除的配置侦听器。
        异常
        NullPointerException - 如果侦听器为null。
        SecurityException - 如果存在安全管理器且调用者没有LoggingPermission（“control”）。
        从以下版本开始：
        9