Module  java.logging
软件包  java.util.logging

Class LogManager


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

    这个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将具有以处理程序或记录器的点分隔名称开头的名称。
    全局日志记录属性可能包括：

    • 一个财产“处理者”。 这定义了一个空格或逗号分隔的类名列表，用于处理程序类，以加载和注册为根记录器（名为“”的记录器）上的处理程序。 每个类名必须是具有默认构造函数的Handler类。 请注意，这些处理程序可能会在第一次使用时被懒惰地创建。
    • 属性“<logger> .handlers”。 这定义了处理程序类的空格或逗号分隔的类名列表，以加载和注册为指定的记录器的处理程序。 每个类名必须是具有默认构造函数的Handler类。 请注意，这些处理程序可能会在第一次使用时被懒惰地创建。
    • 属性“<logger> .handlers.ensureCloseOnReset”。 这定义了一个布尔值。 如果“<logger> .handlers”未定义或为空，则此属性将被忽略。 否则默认为true 。 当值为true ，与记录器关联的处理程序保证在reset()关闭并关闭。 这可以通过在配置中显式设置“<logger> .handlers.ensureCloseOnReset = false”来关闭。 请注意，关闭此属性会导致引入资源泄漏的风险，因为记录器可能会在reset()被调用之前收集垃圾，从而防止其处理程序关闭reset() 。 在这种情况下，应用程序有责任确保处理程序在记录器被垃圾回收之前关闭。
    • 属性“<logger> .useParentHandlers”。 这定义了一个布尔值。 默认情况下，每个记录器除了处理日志消息本身之外都调用其父进程，这通常导致消息由根记录器处理。 将此属性设置为false时，需要为此记录器配置处理程序，否则不会传送日志记录消息。
    • 属性“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对象的引用，以避免它被垃圾回收。 LogManager可能只保留弱引用。

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

      • getLogger

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

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

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

      • getLoggerNames

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

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

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

      • 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 。 那么具有在新配置流中指定的级别属性的所有现有记录器将为指定日志级别的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 ，映射函数f将使用与旧配置（即o ）中的k相关联的值和与新配置（即n ）中的k相关联的值来调用。
        o or n的值为null ，表示相应配置中的k没有值。
        异常
        SecurityException - 如果安全管理器存在，并且调用者没有LoggingPermission（“控制”），或者没有设置配置所需的权限（例如，为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) 。
        • 使用新配置替换所有属性，除了处理程序属性以配置不是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 ，映射函数f将使用与旧配置（即o ）中的k相关联的值和与新配置（即n ）中的k相关联的值来调用。
        o or n的值为null ，表示对应的配置中k不存在任何值。
        异常
        SecurityException - 如果安全管理器存在，并且调用者没有LoggingPermission（“控制”），或者没有设置配置所需的权限（例如打开为FileHandler指定的文件）
        NullPointerException - 如果 ins为空，或者如果 mapper在调用时返回空函数。
        IOException - 如果从流读取有问题，或给定的流不是在properties file格式。
        从以下版本开始：
        9

      • getProperty

        public String getProperty​(String name)
        获取日志记录属性的值。 如果找不到该属性，该方法返回null。
        参数
        name - 物业名称
        结果
        属性值

      • checkAccess

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

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

        异常
        SecurityException - 如果安全管理器存在，并且主叫方没有LoggingPermission（“控制”）。

      • addConfigurationListener

        public LogManager addConfigurationListener​(Runnable listener)
        添加每次读取日志配置时调用的配置监听器。 如果监听器已经注册，该方法什么也不做。

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

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

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

      • removeConfigurationListener

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