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