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  * {@extLink logging_overview Java Logging Overview}
 114  * </P>
 115  *
 116  * @since 1.4
 117  */
 118 package java.util.logging;