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