/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.commons.logging;

import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;

import java.text.*;
import java.util.*;
import java.util.Formatter;
import java.util.function.*;
import java.util.logging.*;

/**
 * LogRecord that supports lazy message formatting.
 *
 * <p>
 * This class extends {@link java.util.logging.LogRecord java.util.logging.LogRecord} and overrides {@link #getMessage()} to use
 * {@link org.apache.juneau.commons.utils.StringUtils#format(String, Object...)} (printf-style <js>"%s"</js>/<js>"%d"</js>) for
 * lazy formatting. The message is only formatted when {@link #getMessage()} is actually called.
 *
 * <h5 class='section'>Usage:</h5>
 * <p>
 * This class is used internally by {@link RichLogger} when logging formatted messages.
 * The formatted message is only computed when the LogRecord's message is actually
 * accessed (e.g., by a Handler or Formatter).
 * </p>
 *
 * <h5 class='section'>Formatting contract:</h5>
 * <p>
 * Juneau {@link RichLogger} patterns are <b>printf-style</b> (rendered here via {@link org.apache.juneau.commons.utils.StringUtils#format(String, Object...)}).
 * Because this override returns the already-substituted message, downstream {@link java.util.logging.Handler Handlers} and
 * {@link java.util.logging.Formatter Formatters} that call {@link #getMessage()} see fully-rendered text and never re-apply
 * formatting — so the printf-vs-MessageFormat choice is purely internal. The JDK's {@link java.text.MessageFormat}
 * parameter contract of {@link java.util.logging.LogRecord} only resurfaces if a record is serialized and consumed as a
 * plain {@link java.util.logging.LogRecord} by a non-Juneau handler; such a consumer would apply MessageFormat to the raw
 * <c>{0}</c> pattern, so printf patterns are not intended for that scenario.
 * </p>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='jc'>{@link RichLogger}
 *    <li class='jc'>{@link org.apache.juneau.commons.utils.StringUtils#format(String, Object...)}
 *    <li class='jc'>{@link java.util.logging.LogRecord}
 * </ul>
 */
@SuppressWarnings({
   "java:S100", // Method names match java.util.logging.LogRecord for API compatibility
   "java:S115", // Constants use UPPER_snakeCase convention
   "java:S1192", // String literals intentionally duplicated for clarity
   "java:S2143", // Date required for java.util.logging compatibility and Formatter %t conversions; not a behavior-preserving java.time swap.
   "java:S2176" // Class name intentionally matches java.util.logging.LogRecord; extends it to enrich logging with Juneau-specific fields
})
public class LogRecord extends java.util.logging.LogRecord {

   private static final long serialVersionUID = 1L;
   private final transient MessageGenerator generator;

   /**
    * Constructor.
    *
    * @param loggerName The logger name.  Can be <jk>null</jk>.
    * @param level The log level.  Must not be <jk>null</jk>.
    * @param msg The message pattern (will be used as-is if args is null or empty).
    * @param parameters The format arguments, or <jk>null</jk> if none.
    * @param throwable The throwable, or <jk>null</jk> if none.
    */
   public LogRecord(String loggerName, Level level, String msg, Object[] parameters, Throwable throwable) {
      this(loggerName, level, msg, parameters, throwable, MessageGenerator.PRINTF);
   }

   /**
    * Constructor.
    *
    * @param loggerName The logger name.  Can be <jk>null</jk>.
    * @param level The log level.  Must not be <jk>null</jk>.
    * @param msg The message pattern (will be used as-is if args is null or empty).
    * @param parameters The format arguments, or <jk>null</jk> if none.
    * @param throwable The throwable, or <jk>null</jk> if none.
    * @param generator The message generator.
    */
   public LogRecord(String loggerName, Level level, String msg, Object[] parameters, Throwable throwable, MessageGenerator generator) {
      super(level, msg);
      setLoggerName(loggerName);
      setParameters(isNotEmptyArray(parameters) ? parameters : null);
      setThrown(throwable);
      this.generator = generator == null ? MessageGenerator.PRINTF : generator;
   }

   /**
    * Returns the log message, formatting it lazily if needed.
    *
    * <p>
    * If parameters were set via {@link #setParameters(Object[])}, the message is formatted
    * using {@link org.apache.juneau.commons.utils.StringUtils#format(String, Object...)} on first access.
    *
    * @return The log message, formatted if parameters are present.
    */
   @Override
   public String getMessage() {
      var m = super.getMessage();
      var p = getParameters();
      if (isEmptyArray(p))
         return m;
      var messageGenerator = generator == null ? MessageGenerator.PRINTF : generator;
      return safeOptCatch(() -> messageGenerator.format(m, p), x -> m).orElse(m);
   }

   /**
    * Formats this log record as a string using the specified format pattern.
    *
    * <p>
    * Similar to how {@link SimpleFormatter} formats log records, this method
    * allows you to specify a custom format string with placeholders that are replaced with
    * actual values from the log record.
    *
    * <p>
    * The format string supports both named placeholders (e.g., <js>"{date}"</js>) and
    * {@link java.util.Formatter Formatter}-style format specifiers (e.g., <js>"%1$tc"</js>).
    * Named placeholders are replaced first, then the resulting string is formatted using
    * {@link java.util.Formatter Formatter} with the following arguments:
    * <ol>
    *    <li><c>date</c> - The date/time as a {@link Date} object
    *    <li><c>logger</c> - The logger name
    *    <li><c>level</c> - The log level
    *    <li><c>message</c> - The formatted log message
    *    <li><c>thrown</c> - The throwable object (if any)
    * </ol>
    *
    * <h5 class='section'>Named Placeholders:</h5>
    * <ul>
    *    <li><js>"{date}"</js> - The date/time formatted using {@link SimpleFormatter SimpleFormatter}'s default date format
    *    <li><js>"{timestamp}"</js> - The date/time formatted as ISO-8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
    *    <li><js>"{logger}"</js> - The logger name
    *    <li><js>"{level}"</js> - The log level name
    *    <li><js>"{msg}"</js> - The log message (formatted if parameters are present)
    *    <li><js>"{thread}"</js> - The thread ID
    *    <li><js>"{threadid}"</js> - The thread ID (alias for {thread})
    *    <li><js>"{exception}"</js> - The exception message (if thrown)
    *    <li><js>"{thrown}"</js> - The throwable object (if thrown)
    * </ul>
    *
    * <h5 class='section'>Formatter-Style Format Specifiers:</h5>
    * <p>
    * You can use {@link java.util.Formatter Formatter}-style format specifiers directly in the format string.
    * The arguments are passed in the same order as {@link java.util.logging.SimpleFormatter SimpleFormatter}:
    * </p>
    * <ul>
    *    <li><js>"%1$s"</js> or <js>"%1$tc"</js> - The date/time (argument 1)
    *    <li><js>"%2$s"</js> - The logger name (argument 2)
    *    <li><js>"%3$s"</js> - The log level (argument 3)
    *    <li><js>"%4$s"</js> - The log message (argument 4)
    *    <li><js>"%5$s"</js> - The throwable and its backtrace (argument 5)
    * </ul>
    *
    * <p>
    * For date/time formatting, you can use date/time conversion characters with argument 1:
    * </p>
    * <ul>
    *    <li><js>"%1$tc"</js> - Complete date and time (e.g., "Tue Mar 22 13:11:31 PDT 2011")
    *    <li><js>"%1$tb"</js> - Month abbreviation (e.g., "Mar")
    *    <li><js>"%1$td"</js> - Day of month (01-31)
    *    <li><js>"%1$tY"</js> - Year (4 digits)
    *    <li><js>"%1$tH"</js> - Hour (00-23)
    *    <li><js>"%1$tM"</js> - Minute (00-59)
    *    <li><js>"%1$tS"</js> - Second (00-59)
    *    <li><js>"%1$tL"</js> - Milliseconds (000-999)
    *    <li><js>"%1$tN"</js> - Nanoseconds (000000000-999999999, since JDK 9)
    *    <li><js>"%1$Tp"</js> - AM/PM marker (uppercase)
    *    <li><js>"%1$tp"</js> - AM/PM marker (lowercase)
    * </ul>
    *
    * <p>
    * The format string can also contain <js>"%n"</js> for newlines.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    LogRecord <jv>record</jv> = <jk>new</jk> LogRecord(Level.INFO, <js>"User {0} logged in"</js>, <js>"John"</js>);
    *
    *    <jc>// Using named placeholders</jc>
    *    String <jv>formatted1</jv> = <jv>record</jv>.formatted(<js>"[{timestamp} {level}] {msg}"</js>);
    *    <jc>// Result: "[2025-01-22T07:42:45.123-0500 INFO] User John logged in"</jc>
    *
    *    <jc>// Using Formatter-style specifiers</jc>
    *    String <jv>formatted2</jv> = <jv>record</jv>.formatted(<js>"%3$s: %4$s [%1$tc]%n"</js>);
    *    <jc>// Result: "INFO: User John logged in [Tue Jan 22 07:42:45 PST 2025]"</jc>
    *
    *    <jc>// Mixed named placeholders and Formatter specifiers</jc>
    *    String <jv>formatted3</jv> = <jv>record</jv>.formatted(<js>"%1$tb %1$td, %1$tY {level}: {msg}%n"</js>);
    *    <jc>// Result: "Jan 22, 2025 INFO: User John logged in"</jc>
    * </p>
    *
    * @param format The format string with placeholders and/or Formatter-style format specifiers.
    * @return The formatted string.
    * @see SimpleFormatter
    * @see Formatter
    */
   public String formatted(String format) {
      return formatted(this, format);
   }

   /**
    * Formats a JUL log record with the same placeholders as {@link #formatted(String)}.
    *
    * @param rec The record to format.
    * @param format The format string.
    * @return The formatted string.
    */
   @SuppressWarnings({
      "deprecation" // Date constructor is deprecated but needed for compatibility
   })
   public static String formatted(java.util.logging.LogRecord rec, String format) {
      var date = new Date(rec.getMillis());

      Function<String,Object> resolver = key -> switch (key) {
         case "date" -> "%1$s";
         case "logger" -> "%2$s";
         case "level" -> "%3$s";
         case "msg" -> "%4$s";
         case "thrown" -> "%5$s";
         case "timestamp" -> new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ").format(date);
         case "thread", "threadid" -> s(rec.getThreadID());
         case "exception" -> o(rec.getThrown()).map(x -> x.getMessage()).orElse("");
         default -> "";
      };

      return safeOptCatch(() -> f(formatNamed(format, resolver), date, rec.getLoggerName(), rec.getLevel(), rec.getMessage(), rec.getThrown()), x -> x.getLocalizedMessage()).orElse(null);
   }
}