/*
 * 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.marshall;

import static java.util.Collections.*;
import static org.apache.juneau.commons.function.Suppliers.*;
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 java.util.*;
import java.util.function.*;

import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.conversion.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.reflect.*;

/**
 * A one-time-use non-thread-safe object that's meant to be used once and then thrown away.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='warn'>This class is not typically thread safe.
 * </ul>
 *
 */
@SuppressWarnings({
   "java:S1192" // Duplicated literals (argument/property names) read more clearly inline than as constants
})
public abstract class ContextSession {

   /**
    * Builder class.
    */
   @SuppressWarnings({
      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
   })
   public abstract static class Builder<SELF extends Builder<SELF>> {

      /**
       * Returns this object cast to the self (CRTP) type.
       *
       * @return This object.
       */
      @SuppressWarnings({
         "unchecked" // CRTP self-type cast is safe by construction.
      })
      protected final SELF self() {
         return (SELF)this;
      }

      private Boolean debug;
      private boolean unmodifiable;
      private final Context ctx;
      private final Memoizer<LinkedHashMap<String,Object>> properties;

      /**
       * Convenience method for converting values using {@link BasicConverter}.
       *
       * @param <T> The target type.
       * @param value The value to convert.
       *    <br>Can be <jk>null</jk> (returns <jk>null</jk>).
       * @param type The target class.
       * @return The converted value, or <jk>null</jk> if the input value was <jk>null</jk>.
       */
      protected static <T> T cvt(Object value, Class<T> type) {
         return BasicConverter.INSTANCE.to(value, null, null, type);
      }

      /**
       * Constructor.
       *
       * @param ctx The context creating this session.
       *    <br>Cannot be <jk>null</jk>.
       */
      protected Builder(Context ctx) {
         this.ctx = reqnn("ctx", ctx);
         this.properties = memoizer(LinkedHashMap::new);
      }

      /**
       * Applies a consumer to this builder if it's the specified type.
       *
       * @param <T> The expected type.
       * @param type The expected type.
       *    <br>Cannot be <jk>null</jk>.
       * @param apply   The consumer to apply.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public <T> SELF apply(Class<T> type, Consumer<T> apply) {
         if (reqnn("type", type).isInstance(this))
            reqnn("apply", apply).accept(type.cast(this));
         return self();
      }

      /**
       * Build the object.
       *
       * @return The built object.
       */
      public abstract ContextSession build();

      /**
       * Debug mode.
       *
       * <p>
       * Enables the following additional information during parsing:
       * <ul>
       *    <li> When bean setters throws exceptions, the exception includes the object stack information in order to determine how that method was invoked.
       * </ul>
       *
       * <p>
       * If not specified, defaults to {@link Context.Builder#debug()}.
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='ja'>{@link MarshalledConfig#debug()}
       *    <li class='jm'>{@link Context.Builder#debug()}
       *
       * @param value
       *    The new value for this property.
       *    <br>If <jk>null</jk>, defaults to {@link Context#isDebug()}.
       * @return This object.
       */
      public SELF debug(Boolean value) {
         debug = value;
         return self();
      }

      /**
       * Session properties.
       *
       * <p>
       * Session properties are generic key-value pairs that can be passed through the session and made
       * available to any customized serializers/parsers or swaps.
       *
       * @param value
       *    The new value for this property.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF properties(Map<String,Object> value) {
         reqnn("value", value);
         properties.reset();
         value.forEach(this::property);
         return self();
      }

      /**
       * Adds a property to this session.
       *
       * <p>
       * If the key matches a known session property (e.g. <js>"debug"</js> or <js>"ContextSession.debug"</js>),
       * the value is converted via {@link BasicConverter} and routed to the corresponding typed setter.
       * Unknown keys are stored in the raw session properties map.
       *
       * @param key The property key.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The property value.
       *    <br>Can be <jk>null</jk> (resets typed properties to their default; removes raw properties).
       * @return This object.
       */
      public SELF property(String key, Object value) {
         reqnn("key", key);
         switch (key) {
            case "debug", "ContextSession.debug":
               return debug(cvt(value, Boolean.class));
            default:
               var map = properties.get();
               if (value == null) {
                  map.remove(key);
               } else {
                  map.put(key, value);
               }
               return self();
         }
      }

      /**
       * Create an unmodifiable session.
       *
       * <p>
       * The created ContextSession object will be unmodifiable which makes it suitable for caching and reuse.
       *
       * @return This object.
       */
      public SELF unmodifiable() {
         unmodifiable = true;
         return self();
      }
   }

   private final boolean debug;
   private final boolean unmodifiable;
   private final Context ctx;
   private final Map<String,Object> properties;
   private List<String> warnings;   // Any warnings encountered.

   /**
    * Default constructor.
    *
    * @param builder The builder for this object.
    *    <br>Cannot be <jk>null</jk>.
    */
   protected ContextSession(Builder<?> builder) {
      reqnn("builder", builder);
      ctx = builder.ctx;
      debug = o(builder.debug).orElse(ctx.isDebug());
      unmodifiable = builder.unmodifiable;
      var sp = builder.properties.get();
      if (unmodifiable) {
         properties = sp.isEmpty() ? Collections.emptyMap() : u(sp);
      } else {
         properties = sp;
      }
   }

   /**
    * Logs a warning message.
    *
    * @param msg The warning message.
    *    <br>Cannot be <jk>null</jk>.
    * @param args Optional {@link String#format(String, Object...) String.format}-style arguments.
    *    <br>Cannot be <jk>null</jk> (individual values may be <jk>null</jk>).
    */
   public void addWarning(String msg, Object...args) {
      reqnn("msg", msg, "args", args);
      if (unmodifiable)
         return;
      if (warnings == null)
         warnings = ll();
      warnings.add((warnings.size() + 1) + ": " + f(msg, args));
   }

   /**
    * Throws a {@link BeanRuntimeException} if any warnings occurred in this session and debug is enabled.
    */
   public void checkForWarnings() {
      if (debug && ! getWarnings().isEmpty())
         throw brex("Warnings occurred in session: \n" + join(getWarnings(), "\n"));
   }

   /**
    * Returns the context that created this session.
    *
    * @return The context that created this session.
    */
   public Context getContext() { return ctx; }

   /**
    * Returns the session properties on this session.
    *
    * @return The session properties on this session.  Never <jk>null</jk>.
    */
   public final Map<String,Object> getSessionProperties() { return properties; }

   /**
    * Returns the warnings that occurred in this session.
    *
    * @return The warnings that occurred in this session, or an empty list if no warnings occurred.
    */
   public final List<String> getWarnings() { return warnings == null ? emptyList() : warnings; }

   /**
    * Debug mode enabled.
    *
    * @see Context.Builder#debug()
    * @return
    *    <jk>true</jk> if debug mode is enabled.
    */
   public boolean isDebug() { return debug; }

   @Override /* Overridden from Object */
   public String toString() {
      return r(properties());
   }

   /**
    * Returns the properties on this bean as a map for debugging.
    *
    * @return The properties on this bean as a map for debugging.
    */
   protected FluentMap<String,Object> properties() {
      return filteredBeanPropertyMap()
         .a("debug", debug);
   }
}