sample/java.util.logging.LogManager.txt

   1 *java.util.logging.LogManager* *LogManager* There is a single global LogManager
   2
   3 public class LogManager
   4   extends    |java.lang.Object|
   5
   6 |java.util.logging.LogManager_Description|
   7 |java.util.logging.LogManager_Fields|
   8 |java.util.logging.LogManager_Constructors|
   9 |java.util.logging.LogManager_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.logging.LogManager_Fields*
  14 |java.lang.String_java.util.logging.LogManager.LOGGING_MXBEAN_NAME|
  15
  16 *java.util.logging.LogManager_Constructors*
  17 |java.util.logging.LogManager()|Protected constructor.
  18
  19 *java.util.logging.LogManager_Methods*
  20 |java.util.logging.LogManager.addLogger(Logger)|Add a named logger.
  21 |java.util.logging.LogManager.addPropertyChangeListener(PropertyChangeListener)|
  22 |java.util.logging.LogManager.checkAccess()|Check that the current context is t
  23 |java.util.logging.LogManager.getLogger(String)|Method to find a named logger.
  24 |java.util.logging.LogManager.getLoggerNames()|Get an enumeration of known logg
  25 |java.util.logging.LogManager.getLoggingMXBean()|Returns LoggingMXBean for mana
  26 |java.util.logging.LogManager.getLogManager()|Return the global LogManager obje
  27 |java.util.logging.LogManager.getProperty(String)|Get the value of a logging pr
  28 |java.util.logging.LogManager.readConfiguration()|Reinitialize the logging prop
  29 |java.util.logging.LogManager.readConfiguration(InputStream)|Reinitialize the l
  30 |java.util.logging.LogManager.removePropertyChangeListener(PropertyChangeListener)|
  31 |java.util.logging.LogManager.reset()|Reset the logging configuration.
  32
  33 *java.util.logging.LogManager_Description*
  34
  35 There is a single global LogManager object that is used to maintain a set of
  36 shared state about Loggers and log services.
  37
  38 This LogManager object:
  39
  40 Manages a hierarchical namespace of Logger objects. All named Loggers are
  41 stored in this namespace. Manages a set of logging control properties. These
  42 are simple key-value pairs that can be used by Handlers and other logging
  43 objects to configure themselves.
  44
  45 The global LogManager object can be retrieved using LogManager.getLogManager().
  46 The LogManager object is created during class initialization and cannot
  47 subsequently be changed.
  48
  49 At startup the LogManager class is located using the java.util.logging.manager
  50 system property.
  51
  52 By default, the LogManager reads its initial configuration from a properties
  53 file "lib/logging.properties" in the JRE directory. If you edit that property
  54 file you can change the default logging configuration for all uses of that JRE.
  55
  56 In addition, the LogManager uses two optional system properties that allow more
  57 control over reading the initial configuration:
  58
  59 "java.util.logging.config.class" "java.util.logging.config.file"
  60
  61 These two properties may be set via the Preferences API, or as command line
  62 property definitions to the "java" command, or as system property definitions
  63 passed to JNI_CreateJavaVM.
  64
  65 If the "java.util.logging.config.class" property is set, then the property
  66 value is treated as a class name. The given class will be loaded, an object
  67 will be instantiated, and that object's constructor is responsible for reading
  68 in the initial configuration. (That object may use other system properties to
  69 control its configuration.) The alternate configuration class can use
  70 readConfiguration(InputStream) to define properties in the LogManager.
  71
  72 If "java.util.logging.config.class" property is not set, then the
  73 "java.util.logging.config.file" system property can be used to specify a
  74 properties file (in java.util.Properties format). The initial logging
  75 configuration will be read from this file.
  76
  77 If neither of these properties is defined then, as described above, the
  78 LogManager will read its initial configuration from a properties file
  79 "lib/logging.properties" in the JRE directory.
  80
  81 The properties for loggers and Handlers will have names starting with the
  82 dot-separated name for the handler or logger.
  83
  84 The global logging properties may include:
  85
  86 A property "handlers". This defines a whitespace separated list of class names
  87 for handler classes to load and register as handlers on the root Logger (the
  88 Logger named ""). Each class name must be for a Handler class which has a
  89 default constructor. Note that these Handlers may be created lazily, when they
  90 are first used.
  91
  92 A property "<logger>.handlers". This defines a whitespace or comma separated
  93 list of class names for handlers classes to load and register as handlers to
  94 the specified logger. Each class name must be for a Handler class which has a
  95 default constructor. Note that these Handlers may be created lazily, when they
  96 are first used.
  97
  98 A property "<logger>.useParentHandlers". This defines a boolean value. By
  99 default every logger calls its parent in addition to handling the logging
 100 message itself, this often result in messages being handled by the root logger
 101 as well. When setting this property to false a Handler needs to be configured
 102 for this logger otherwise no logging messages are delivered.
 103
 104 A property "config". This property is intended to allow arbitrary configuration
 105 code to be run. The property defines a whitespace separated list of class
 106 names. A new instance will be created for each named class. The default
 107 constructor of each class may execute arbitrary code to update the logging
 108 configuration, such as setting logger levels, adding handlers, adding filters,
 109 etc.
 110
 111 Note that all classes loaded during LogManager configuration are first searched
 112 on the system class path before any user class path. That includes the
 113 LogManager class, any config classes, and any handler classes.
 114
 115 Loggers are organized into a naming hierarchy based on their dot separated
 116 names. Thus "a.b.c" is a child of "a.b", but "a.b1" and a.b2" are peers.
 117
 118 All properties whose names end with ".level" are assumed to define log levels
 119 for Loggers. Thus "foo.level" defines a log level for the logger called "foo"
 120 and (recursively) for any of its children in the naming hierarchy. Log Levels
 121 are applied in the order they are defined in the properties file. Thus level
 122 settings for child nodes in the tree should come after settings for their
 123 parents. The property name ".level" can be used to set the level for the root
 124 of the tree.
 125
 126 All methods on the LogManager object are multi-thread safe.
 127
 128
 129 *java.lang.String_java.util.logging.LogManager.LOGGING_MXBEAN_NAME*
 130
 131 There is a single global LogManager object that is used to maintain a set of
 132 shared state about Loggers and log services.
 133
 134 This LogManager object:
 135
 136 Manages a hierarchical namespace of Logger objects. All named Loggers are
 137 stored in this namespace. Manages a set of logging control properties. These
 138 are simple key-value pairs that can be used by Handlers and other logging
 139 objects to configure themselves.
 140
 141 The global LogManager object can be retrieved using LogManager.getLogManager().
 142 The LogManager object is created during class initialization and cannot
 143 subsequently be changed.
 144
 145 At startup the LogManager class is located using the java.util.logging.manager
 146 system property.
 147
 148 By default, the LogManager reads its initial configuration from a properties
 149 file "lib/logging.properties" in the JRE directory. If you edit that property
 150 file you can change the default logging configuration for all uses of that JRE.
 151
 152 In addition, the LogManager uses two optional system properties that allow more
 153 control over reading the initial configuration:
 154
 155 "java.util.logging.config.class" "java.util.logging.config.file"
 156
 157 These two properties may be set via the Preferences API, or as command line
 158 property definitions to the "java" command, or as system property definitions
 159 passed to JNI_CreateJavaVM.
 160
 161 If the "java.util.logging.config.class" property is set, then the property
 162 value is treated as a class name. The given class will be loaded, an object
 163 will be instantiated, and that object's constructor is responsible for reading
 164 in the initial configuration. (That object may use other system properties to
 165 control its configuration.) The alternate configuration class can use
 166 readConfiguration(InputStream) to define properties in the LogManager.
 167
 168 If "java.util.logging.config.class" property is not set, then the
 169 "java.util.logging.config.file" system property can be used to specify a
 170 properties file (in java.util.Properties format). The initial logging
 171 configuration will be read from this file.
 172
 173 If neither of these properties is defined then, as described above, the
 174 LogManager will read its initial configuration from a properties file
 175 "lib/logging.properties" in the JRE directory.
 176
 177 The properties for loggers and Handlers will have names starting with the
 178 dot-separated name for the handler or logger.
 179
 180 The global logging properties may include:
 181
 182 A property "handlers". This defines a whitespace separated list of class names
 183 for handler classes to load and register as handlers on the root Logger (the
 184 Logger named ""). Each class name must be for a Handler class which has a
 185 default constructor. Note that these Handlers may be created lazily, when they
 186 are first used.
 187
 188 A property "<logger>.handlers". This defines a whitespace or comma separated
 189 list of class names for handlers classes to load and register as handlers to
 190 the specified logger. Each class name must be for a Handler class which has a
 191 default constructor. Note that these Handlers may be created lazily, when they
 192 are first used.
 193
 194 A property "<logger>.useParentHandlers". This defines a boolean value. By
 195 default every logger calls its parent in addition to handling the logging
 196 message itself, this often result in messages being handled by the root logger
 197 as well. When setting this property to false a Handler needs to be configured
 198 for this logger otherwise no logging messages are delivered.
 199
 200 A property "config". This property is intended to allow arbitrary configuration
 201 code to be run. The property defines a whitespace separated list of class
 202 names. A new instance will be created for each named class. The default
 203 constructor of each class may execute arbitrary code to update the logging
 204 configuration, such as setting logger levels, adding handlers, adding filters,
 205 etc.
 206
 207 Note that all classes loaded during LogManager configuration are first searched
 208 on the system class path before any user class path. That includes the
 209 LogManager class, any config classes, and any handler classes.
 210
 211 Loggers are organized into a naming hierarchy based on their dot separated
 212 names. Thus "a.b.c" is a child of "a.b", but "a.b1" and a.b2" are peers.
 213
 214 All properties whose names end with ".level" are assumed to define log levels
 215 for Loggers. Thus "foo.level" defines a log level for the logger called "foo"
 216 and (recursively) for any of its children in the naming hierarchy. Log Levels
 217 are applied in the order they are defined in the properties file. Thus level
 218 settings for child nodes in the tree should come after settings for their
 219 parents. The property name ".level" can be used to set the level for the root
 220 of the tree.
 221
 222 All methods on the LogManager object are multi-thread safe.
 223
 224
 225
 226 *java.util.logging.LogManager()*
 227
 228 protected LogManager()
 229
 230 Protected constructor. This is protected so that container applications (such
 231 as J2EE containers) can subclass the object. It is non-public as it is intended
 232 that there only be one LogManager object, whose value is retrieved by calling
 233 Logmanager.getLogManager.
 234
 235
 236 *java.util.logging.LogManager.addLogger(Logger)*
 237
 238 public synchronized boolean addLogger(java.util.logging.Logger logger)
 239
 240 Add a named logger. This does nothing and returns false if a logger with the
 241 same name is already registered.
 242
 243 The Logger factory methods call this method to register each newly created
 244 Logger.
 245
 246 The application should retain its own reference to the Logger object to avoid
 247 it being garbage collected. The LogManager may only retain a weak reference.
 248
 249     logger - the new logger.
 250
 251     Returns: true if the argument logger was registered successfully, false if a logger of
 252              that name already exists.
 253 *java.util.logging.LogManager.addPropertyChangeListener(PropertyChangeListener)*
 254
 255 public void addPropertyChangeListener(java.beans.PropertyChangeListener l)
 256   throws |java.lang.SecurityException|
 257
 258 Adds an event listener to be invoked when the logging properties are re-read.
 259 Adding multiple instances of the same event Listener results in multiple
 260 entries in the property event listener table.
 261
 262     l - event listener
 263
 264 *java.util.logging.LogManager.checkAccess()*
 265
 266 public void checkAccess()
 267   throws |java.lang.SecurityException|
 268
 269 Check that the current context is trusted to modify the logging configuration.
 270 This requires LoggingPermission("control").
 271
 272 If the check fails we throw a SecurityException, otherwise we return normally.
 273
 274
 275 *java.util.logging.LogManager.getLogger(String)*
 276
 277 public synchronized |java.util.logging.Logger| getLogger(java.lang.String name)
 278
 279 Method to find a named logger.
 280
 281 Note that since untrusted code may create loggers with arbitrary names this
 282 method should not be relied on to find Loggers for security sensitive logging.
 283
 284     name - name of the logger
 285
 286     Returns: matching logger or null if none is found
 287 *java.util.logging.LogManager.getLoggerNames()*
 288
 289 public synchronized |java.util.Enumeration| getLoggerNames()
 290
 291 Get an enumeration of known logger names.
 292
 293 Note: Loggers may be added dynamically as new classes are loaded. This method
 294 only reports on the loggers that are currently registered.
 295
 296
 297     Returns: enumeration of logger name strings
 298 *java.util.logging.LogManager.getLoggingMXBean()*
 299
 300 public static synchronized |java.util.logging.LoggingMXBean| getLoggingMXBean()
 301
 302 Returns LoggingMXBean for managing loggers. The LoggingMXBean can also obtained
 303 from the platform
 304 <tt>MBeanServer</tt>(|java.lang.management.ManagementFactory|) method.
 305
 306
 307     Returns: a {@link LoggingMXBean} object.
 308 *java.util.logging.LogManager.getLogManager()*
 309
 310 public static |java.util.logging.LogManager| getLogManager()
 311
 312 Return the global LogManager object.
 313
 314
 315 *java.util.logging.LogManager.getProperty(String)*
 316
 317 public |java.lang.String| getProperty(java.lang.String name)
 318
 319 Get the value of a logging property. The method returns null if the property is
 320 not found.
 321
 322     name - property name
 323
 324     Returns: property value
 325 *java.util.logging.LogManager.readConfiguration()*
 326
 327 public void readConfiguration()
 328   throws |java.io.IOException|
 329          |java.lang.SecurityException|
 330
 331 Reinitialize the logging properties and reread the logging configuration.
 332
 333 The same rules are used for locating the configuration properties as are used
 334 at startup. So normally the logging properties will be re-read from the same
 335 file that was used at startup.
 336
 337 Any log level definitions in the new configuration file will be applied using
 338 Logger.setLevel(), if the target Logger exists.
 339
 340 A PropertyChangeEvent will be fired after the properties are read.
 341
 342
 343 *java.util.logging.LogManager.readConfiguration(InputStream)*
 344
 345 public void readConfiguration(java.io.InputStream ins)
 346   throws |java.io.IOException|
 347          |java.lang.SecurityException|
 348
 349 Reinitialize the logging properties and reread the logging configuration from
 350 the given stream, which should be in java.util.Properties format. A
 351 PropertyChangeEvent will be fired after the properties are read.
 352
 353 Any log level definitions in the new configuration file will be applied using
 354 Logger.setLevel(), if the target Logger exists.
 355
 356     ins - stream to read properties from
 357
 358 *java.util.logging.LogManager.removePropertyChangeListener(PropertyChangeListener)*
 359
 360 public void removePropertyChangeListener(java.beans.PropertyChangeListener l)
 361   throws |java.lang.SecurityException|
 362
 363 Removes an event listener for property change events. If the same listener
 364 instance has been added to the listener table through multiple invocations of
 365 addPropertyChangeListener, then an equivalent number of
 366 removePropertyChangeListener invocations are required to remove all instances
 367 of that listener from the listener table.
 368
 369 Returns silently if the given listener is not found.
 370
 371     l - event listener (can be null)
 372
 373 *java.util.logging.LogManager.reset()*
 374
 375 public void reset()
 376   throws |java.lang.SecurityException|
 377
 378 Reset the logging configuration.
 379
 380 For all named loggers, the reset operation removes and closes all Handlers and
 381 (except for the root logger) sets the level to null. The root logger's level is
 382 set to Level.INFO.
 383
 384
 385