annotate src/java.logging/share/classes/java/util/logging/package.html @ 12677:a4299d47bd00

8134984: Text files should end in exactly one newline Summary: automated fixup of newlines at end-of-file via the usual perl one-liner Reviewed-by: chegar, sherman
author martin
date Wed, 02 Sep 2015 14:11:50 -0700
parents b1a68681ccac
children e8ee0b0489eb
rev   line source
duke@0 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
duke@0 2 <html>
duke@0 3 <head>
duke@0 4 <!--
ohair@2362 5 Copyright (c) 2001, 2006, Oracle and/or its affiliates. All rights reserved.
duke@0 7
duke@0 8 This code is free software; you can redistribute it and/or modify it
duke@0 9 under the terms of the GNU General Public License version 2 only, as
ohair@2362 10 published by the Free Software Foundation. Oracle designates this
duke@0 11 particular file as subject to the "Classpath" exception as provided
ohair@2362 12 by Oracle in the LICENSE file that accompanied this code.
duke@0 13
duke@0 14 This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 17 version 2 for more details (a copy is included in the LICENSE file that
duke@0 18 accompanied this code).
duke@0 19
duke@0 20 You should have received a copy of the GNU General Public License version
duke@0 21 2 along with this work; if not, write to the Free Software Foundation,
duke@0 22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 23
ohair@2365 24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@2365 25 or visit if you need additional information or have any
ohair@2365 26 questions.
duke@0 27 -->
duke@0 28
duke@0 29 </head>
duke@0 30 <body bgcolor="white">
duke@0 31 <P>
duke@0 32 Provides the classes and interfaces of
darcy@12004 33 the Java&trade; 2 platform's core logging facilities.
duke@0 34 The central goal of the logging APIs is to support maintaining and servicing
duke@0 35 software at customer sites.
duke@0 36
duke@0 37 <P>
duke@0 38 There are four main target uses of the logs:
duke@0 39 </P>
duke@0 40
duke@0 41 <OL>
duke@0 42 <LI> <I>Problem diagnosis by end users and system administrators</I>.
duke@0 43 This consists of simple logging of common problems that can be fixed
duke@0 44 or tracked locally, such as running out of resources, security failures,
duke@0 45 and simple configuration errors.
duke@0 46
duke@0 47 <LI> <I>Problem diagnosis by field service engineers</I>. The logging information
duke@0 48 used by field service engineers may be considerably more complex and
duke@0 49 verbose than that required by system administrators. Typically such information
duke@0 50 will require extra logging within particular subsystems.
duke@0 51
duke@0 52 <LI> <I>Problem diagnosis by the development organization</I>.
duke@0 53 When a problem occurs in the field, it may be necessary to return the captured logging
duke@0 54 information to the original development team for diagnosis. This logging
duke@0 55 information may be extremely detailed and fairly inscrutable. Such information might include
yan@9876 56 detailed tracing on the internal execution of particular subsystems.
duke@0 57
duke@0 58 <LI> <I>Problem diagnosis by developers</I>. The Logging APIs may also be
duke@0 59 used to help debug an application under development. This may
duke@0 60 include logging information generated by the target application
yan@9876 61 as well as logging information generated by lower-level libraries.
duke@0 62 Note however that while this use is perfectly reasonable,
duke@0 63 the logging APIs are not intended to replace the normal debugging
duke@0 64 and profiling tools that may already exist in the development environment.
duke@0 65 </OL>
duke@0 66
yan@9876 67 <p>
duke@0 68 The key elements of this package include:
duke@0 69 <UL>
duke@0 70 <LI> <I>Logger</I>: The main entity on which applications make
duke@0 71 logging calls. A Logger object is used to log messages
duke@0 72 for a specific system or application
duke@0 73 component.
duke@0 74 <LI> <I>LogRecord</I>: Used to pass logging requests between the logging
duke@0 75 framework and individual log handlers.
duke@0 76 <LI> <I>Handler</I>: Exports LogRecord objects to a variety of destinations
duke@0 77 including memory, output streams, consoles, files, and sockets.
duke@0 78 A variety of Handler subclasses exist for this purpose. Additional Handlers
duke@0 79 may be developed by third parties and delivered on top of the core platform.
duke@0 80 <LI> <I>Level</I>: Defines a set of standard logging levels that can be used
duke@0 81 to control logging output. Programs can be configured to output logging
duke@0 82 for some levels while ignoring output for others.
duke@0 83 <LI> <I>Filter</I>: Provides fine-grained control over what gets logged,
duke@0 84 beyond the control provided by log levels. The logging APIs support a general-purpose
duke@0 85 filter mechanism that allows application code to attach arbitrary filters to
duke@0 86 control logging output.
duke@0 87
duke@0 88 <LI> <I>Formatter</I>: Provides support for formatting LogRecord objects. This
duke@0 89 package includes two formatters, SimpleFormatter and
duke@0 90 XMLFormatter, for formatting log records in plain text
duke@0 91 or XML respectively. As with Handlers, additional Formatters
duke@0 92 may be developed by third parties.
duke@0 93 </UL>
duke@0 94 <P>
duke@0 95 The Logging APIs offer both static and dynamic configuration control.
duke@0 96 Static control enables field service staff to set up a particular configuration and then re-launch the
duke@0 97 application with the new logging settings. Dynamic control allows for updates to the
duke@0 98 logging configuration within a currently running program. The APIs also allow for logging to be
duke@0 99 enabled or disabled for different functional areas of the system. For example,
duke@0 100 a field service engineer might be interested in tracing all AWT events, but might have no interest in
duke@0 101 socket events or memory management.
duke@0 102 </P>
duke@0 103
duke@0 104 <h2>Null Pointers</h2>
duke@0 105 <p>
duke@0 106 In general, unless otherwise noted in the javadoc, methods and
duke@0 107 constructors will throw NullPointerException if passed a null argument.
duke@0 108 The one broad exception to this rule is that the logging convenience
duke@0 109 methods in the Logger class (the config, entering, exiting, fine, finer, finest,
duke@0 110 log, logp, logrb, severe, throwing, and warning methods)
duke@0 111 will accept null values
duke@0 112 for all arguments except for the initial Level argument (if any).
yan@9876 113
duke@0 114 <H2>Related Documentation</H2>
duke@0 115 <P>
duke@0 116 For an overview of control flow,
duke@0 117 please refer to the
duke@0 118 <a href="../../../../technotes/guides/logging/overview.html">
duke@0 119 Java Logging Overview</a>.
duke@0 120 </P>
duke@0 121
duke@0 122 <!-- Put @see and @since tags down here. -->
duke@0 123
duke@0 124 @since 1.4
duke@0 125
duke@0 126
duke@0 127 </body>
duke@0 128 </html>