1 /*

     2  * Copyright (c) 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 package jdk.internal.net.http.common;

    27 

    28 import java.util.Objects;

    29 import java.util.ResourceBundle;

    30 import java.util.function.Supplier;

    31 

    32 /**

    33  * An internal {@code System.Logger} that is used for internal

    34  * debugging purposes in the {@link java.net.http} module.

    35  * <p>

    36  * Though not enforced, this interface is designed for emitting

    37  * debug messages with Level.DEBUG, when system assertions are

    38  * turned on.

    39  * <p>

    40  * It defines {@code log} methods that default to {@code Level.DEBUG}

    41  * and always return {@code true}, so that they can be called in

    42  * assert statements like:

    43  * <pre>{@code assert debug.log("some %s with %d %s", message(), one(), params());}</pre>

    44  *

    45  * @implSpec

    46  * This interface is implemented by loggers returned by

    47  * {@link Utils#getDebugLogger(Supplier, boolean)},

    48  * {@link Utils#getWebSocketLogger(Supplier, boolean)}and

    49  * {@link Utils#getHpackLogger(Supplier, boolean)}.

    50  * It is not designed to be implemented by any other

    51  * loggers. Do not use outside of this module.

    52  */

    53 public interface Logger extends System.Logger {

    54     /**

    55      * Tells whether this logger is on.

    56      * @implSpec The default implementation for this method calls

    57      * {@code this.isLoggable(Level.DEBUG);}

    58      */

    59     public default boolean isOn() {

    60         return isLoggable(Level.DEBUG);

    61     }

    62 

    63     /**

    64      * Logs a message.

    65      *

    66      * @implSpec The default implementation for this method calls

    67      * {@code this.log(Level.DEBUG, msg);}

    68      *

    69      * @param msg the string message (or a key in the message catalog, if

    70      * this logger is a {@link

    71      * System.LoggerFinder#getLocalizedLogger(java.lang.String,

    72      * java.util.ResourceBundle, java.lang.Module) localized logger});

    73      * can be {@code null}.

    74      *

    75      * @return Always return true.

    76      */

    77     public default boolean log(String msg) {

    78         log(Level.DEBUG, msg);

    79         return true;

    80     }

    81 

    82     /**

    83      * Logs a lazily supplied message.

    84      *

    85      * @implSpec The default implementation for this method calls

    86      * {@code this.log(Level.DEBUG, msgSupplier);}

    87      *

    88      * @param msgSupplier a supplier function that produces a message.

    89      *

    90      * @throws NullPointerException if {@code msgSupplier} is {@code null}.

    91      *

    92      * @return Always return true.

    93      */

    94     public default boolean log(Supplier<String> msgSupplier) {

    95         log(Level.DEBUG, msgSupplier);

    96         return true;

    97     }

    98 

    99     /**

   100      * Logs a message produced from the given object.

   101      *

   102      * @implSpec The default implementation for this method calls

   103      * {@code this.log(Level.DEBUG, obj);}

   104      *

   105      * @param obj the object to log.

   106      *

   107      * @throws NullPointerException if {@code obj} is {@code null}.

   108      *

   109      * @return Always return true.

   110      */

   111     public default boolean log(Object obj) {

   112         log(Level.DEBUG,  obj);

   113         return true;

   114     }

   115 

   116     /**

   117      * Logs a message associated with a given throwable.

   118      *

   119      * @implSpec The default implementation for this method calls

   120      * {@code this.log(Level.DEBUG, msg, thrown);}

   121      *

   122      * @param msg the string message (or a key in the message catalog, if

   123      * this logger is a {@link

   124      * System.LoggerFinder#getLocalizedLogger(java.lang.String,

   125      * java.util.ResourceBundle, java.lang.Module) localized logger});

   126      * can be {@code null}.

   127      * @param thrown a {@code Throwable} associated with the log message;

   128      *        can be {@code null}.

   129      *

   130      * @return Always return true.

   131      */

   132     public default boolean log(String msg, Throwable thrown) {

   133         this.log(Level.DEBUG, msg, thrown);

   134         return true;

   135     }

   136 

   137     /**

   138      * Logs a lazily supplied message associated with a given throwable.

   139      *

   140      * @implSpec The default implementation for this method calls

   141      * {@code this.log(Level.DEBUG, msgSupplier, thrown);}

   142      *

   143      * @param msgSupplier a supplier function that produces a message.

   144      * @param thrown a {@code Throwable} associated with log message;

   145      *               can be {@code null}.

   146      *

   147      * @throws NullPointerException if {@code msgSupplier} is {@code null}.

   148      *

   149      * @return Always return true.

   150      */

   151     public default boolean log(Supplier<String> msgSupplier, Throwable thrown) {

   152         log(Level.DEBUG, msgSupplier, thrown);

   153         return true;

   154     }

   155 

   156     /**

   157      * Logs a message with an optional list of parameters.

   158      *

   159      * @implSpec The default implementation for this method calls

   160      * {@code this.log(Level.DEBUG, format, params);}

   161      *

   162      * @param format the string message format in

   163      * {@link String#format(String, Object...)} or {@link

   164      * java.text.MessageFormat} format, (or a key in the message

   165      * catalog, if this logger is a {@link

   166      * System.LoggerFinder#getLocalizedLogger(java.lang.String,

   167      * java.util.ResourceBundle, java.lang.Module) localized logger});

   168      * can be {@code null}.

   169      * @param params an optional list of parameters to the message (may be

   170      * none).

   171      *

   172      * @return Always return true.

   173      */

   174     public default boolean log(String format, Object... params) {

   175         log(Level.DEBUG, format, params);

   176         return true;

   177     }

   178 

   179 }