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;