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