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

import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;

import java.util.*;

import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.serializer.*;

/**
 * Used to swap out non-serializable objects with serializable replacements during serialization, and vis-versa during
 * parsing.
 *
 * <h5 class='topic'>Description</h5>
 *
 * <p>
 * <c>ObjectSwaps</c> are used to extend the functionality of the serializers and parsers to be able to handle
 * objects that aren't automatically handled by the serializers or parsers.
 * <br>For example, JSON does not have a standard representation for rendering dates.
 * By defining a special {@code Date} swap and associating it with a serializer and parser, you can convert a
 * {@code Date} object to a {@code String} during serialization, and convert that {@code String} object back into a
 * {@code Date} object during parsing.
 *
 * <p>
 * Swaps MUST declare a public no-arg constructor so that the bean context can instantiate them.
 *
 * <p>
 * <c>ObjectSwaps</c> are associated with serializers and parsers through the following:
 * <ul class='javatree'>
 *    <li class='ja'>{@link Swap @Swap}
 *    <li class='jm'>{@link org.apache.juneau.marshall.MarshallingContext.Builder#swaps(Class...) MarshallingContext.Builder#swaps(Class...)}
 * </ul>
 *
 * <p>
 * <c>ObjectSwaps</c> have two parameters:
 * <ol>
 *    <li>{@code <T>} - The normal representation of an object.
 *    <li>{@code <S>} - The swapped representation of an object.
 * </ol>
 * <br>{@link Serializer Serializers} use swaps to convert objects of type T into objects of type S, and on calls to
 * {@link BeanMap#get(Object)}.
 * <br>{@link Parser Parsers} use swaps to convert objects of type S into objects of type T, and on calls to
 * {@link BeanMap#put(String,Object)}.
 *
 * <h5 class='topic'>Swap Class Type {@code <S>}</h5>
 *
 * <p>
 * For normal serialization, the swapped object representation of an object must be an object type that the serializers can natively convert to
 * JSON (or language-specific equivalent).
 * <br>The list of valid transformed types are as follows...
 * <ul>
 *    <li>
 *       {@link String}
 *    <li>
 *       {@link Number}
 *    <li>
 *       {@link Boolean}
 *    <li>
 *       {@link Collection} containing anything on this list.
 *    <li>
 *       {@link Map} containing anything on this list.
 *    <li>
 *       A java bean with properties of anything on this list.
 *    <li>
 *       An array of anything on this list.
 * </ul>
 *
 * <p>
 * For OpenAPI serialization, the valid swapped types also include <code><jk>byte</jk>[]</code> and <c>Calendar</c>.
 *
 * <h5 class='topic'>Normal Class Type {@code <T>}</h5>
 *
 * <p>
 * The normal object representation of an object.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Swaps">Swap</a>

 * </ul>
 *
 * @param <T> The normal form of the class.
 * @param <S> The swapped form of the class.
 */
@SuppressWarnings({
   "java:S112", // throws Exception intentional - callback/lifecycle method for user implementations
   "java:S1452", // Wildcard required - ObjectSwap<T,?>, ClassMeta<?> for fluent API and swap metadata
   "rawtypes", // Raw types necessary for generic type handling
   "unchecked" // Type erasure requires unchecked casts
})
public abstract class ObjectSwap<T,S> {

   /**
    * Represents a non-existent object swap.
    */
   public static final ObjectSwap NULL = new ObjectSwap((Class)null, (Class)null) {};

   private final Class<T> normalClass;
   private final Class<?> swapClass;
   private final ClassInfo normalClassInfo;
   private final ClassInfo swapClassInfo;
   private ClassMeta<?> swapClassMeta;

   // Unfortunately these cannot be made final because we want to allow for ObjectSwaps with no-arg constructors
   // which simplifies declarations.
   private MediaType[] forMediaTypes;
   private String template;

   /**
    * Constructor.
    */
   protected ObjectSwap() {
      var ci = info(this.getClass());
      normalClass = (Class<T>)ci.getParameterType(0, ObjectSwap.class);
      swapClass = ci.getParameterType(1, ObjectSwap.class);
      normalClassInfo = info(normalClass);
      swapClassInfo = info(swapClass);
      forMediaTypes = forMediaTypes();
      template = withTemplate();
   }

   /**
    * Constructor for when the normal and transformed classes are already known.
    *
    * @param normalClass The normal class (cannot be serialized).
    * @param swapClass The transformed class (serializable).
    */
   protected ObjectSwap(Class<T> normalClass, Class<?> swapClass) {
      this.normalClass = normalClass;
      this.swapClass = swapClass;
      normalClassInfo = o(normalClass).map(x -> info(x)).orElse(null);
      swapClassInfo = o(swapClass).map(x -> info(x)).orElse(null);
      this.forMediaTypes = forMediaTypes();
      this.template = withTemplate();
   }

   /**
    * Returns the media types that this swap is applicable to.
    *
    * <p>
    * This method can be overridden to programmatically specify what media types it applies to.
    *
    * <p>
    * This method is the programmatic equivalent to the {@link Swap#mediaTypes() @Swap(mediaTypes)} annotation.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Swaps#per-media-type-swaps">Per-media-type swaps</a>
    * </ul>
    * @return The media types that this swap is applicable to, or <jk>null</jk> if it's applicable for all media types.
    */
   @SuppressWarnings({
      "java:S1168"     // Intentional null = applicable to all media types; callers branch on null (not an empty array).
   })
   public MediaType[] forMediaTypes() {
      return null;
   }

   /**
    * Sets the media types that this swap is associated with.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Swaps#per-media-type-swaps">Per-media-type swaps</a>
    * </ul>
    *
    * @param mediaTypes The media types that this swap is associated with. Can be <jk>null</jk> to make this swap applicable to all media types.
    * @return This object.
    */
   public ObjectSwap<T,?> forMediaTypes(MediaType[] mediaTypes) {
      this.forMediaTypes = mediaTypes;
      return this;
   }

   /**
    * Returns the T class, the normalized form of the class.
    *
    * @return The normal form of this class.
    */
   public ClassInfo getNormalClass() { return normalClassInfo; }

   /**
    * Returns the G class, the generalized form of the class.
    *
    * <p>
    * Subclasses must override this method if the generalized class is {@code Object}, meaning it can produce multiple
    * generalized forms.
    *
    * @return The transformed form of this class.
    */
   public ClassInfo getSwapClass() { return swapClassInfo; }

   /**
    * Returns the {@link ClassMeta} of the transformed class type.
    *
    * <p>
    * This value is cached for quick lookup.
    *
    * @param session
    *    The bean context to use to get the class meta.
    *    This is always going to be the same bean context that created this swap.
    *    Must not be <jk>null</jk> on the first (uncached) call.
    * @return The {@link ClassMeta} of the transformed class type.
    */
   public ClassMeta<?> getSwapClassMeta(MarshallingSession session) {
      if (swapClassMeta == null)
         swapClassMeta = session.getClassMeta(swapClass);
      return swapClassMeta;
   }

   /**
    * Checks if the specified object is an instance of the normal class defined on this swap.
    *
    * @param o The object to check. Can be <jk>null</jk> (returns <jk>false</jk>).
    * @return
    *    <jk>true</jk> if the specified object is a subclass of the normal class defined on this transform.
    *    A <jk>null</jk> value always returns <jk>false</jk>.
    */
   public boolean isNormalObject(Object o) {
      if (o == null)
         return false;
      return normalClassInfo.isAssignableFrom(o.getClass());
   }

   /**
    * Checks if the specified object is an instance of the swap class defined on this swap.
    *
    * @param o The object to check. Can be <jk>null</jk> (returns <jk>false</jk>).
    * @return
    *    <jk>true</jk> if the specified object is a subclass of the transformed class defined on this transform.
    *    A <jk>null</jk> value always returns <jk>false</jk>.
    */
   public boolean isSwappedObject(Object o) {
      if (o == null)
         return false;
      return swapClassInfo.isAssignableFrom(o.getClass());
   }

   /**
    * Returns a number indicating how well this swap matches the specified session.
    *
    * <p>
    * Uses the {@link MediaType#match(MediaType, boolean)} method algorithm to produce a number whereby a
    * larger value indicates a "better match".
    * The idea being that if multiple swaps are associated with a given object, we want to pick the best one.
    *
    * <p>
    * For example, if the session media type is <js>"text/json"</js>, then the match values are shown below:
    *
    * <ul>
    *    <li><js>"text/json"</js> = <c>100,000</c>
    *    <li><js>"&#42;/json"</js> = <c>5,100</c>
    *    <li><js>"&#42;/&#42;"</js> = <c>5,000</c>
    *    <li>No media types specified on swap = <c>1</c>
    *    <li><js>"text/xml"</js> = <c>0</c>
    * </ul>
    *
    * @param session The bean session. Can be <jk>null</jk> (returns <c>0</c>, or <c>1</c> if this swap has no media types configured).
    * @return Zero if swap doesn't match the session, or a positive number if it does.
    */
   public int match(MarshallingSession session) {
      if (forMediaTypes == null)
         return 1;
      int i = 0;
      var mt = session != null ? session.getMediaType() : null;
      if (mt == null)
         return 0;
      if (nn(forMediaTypes))
         for (var mt2 : forMediaTypes)
            i = Math.max(i, mt2.match(mt, false));
      return i;
   }

   /**
    * If this transform is to be used to serialize non-serializable objects, it must implement this method.
    *
    * <p>
    * The object must be converted into one of the following serializable types:
    * <ul class='spaced-list'>
    *    <li>
    *       {@link String}
    *    <li>
    *       {@link Number}
    *    <li>
    *       {@link Boolean}
    *    <li>
    *       {@link Collection} containing anything on this list.
    *    <li>
    *       {@link Map} containing anything on this list.
    *    <li>
    *       A java bean with properties of anything on this list.
    *    <li>
    *       An array of anything on this list.
    * </ul>
    *
    * @param session
    *    The bean session to use to get the class meta.
    *    This is always going to be the same bean context that created this swap.
    * @param o The object to be transformed.
    * @return The transformed object.
    * @throws Exception If a problem occurred trying to convert the output.
    */
   public S swap(MarshallingSession session, T o) throws Exception {
      return swap(session, o, template);
   }

   /**
    * Same as {@link #swap(MarshallingSession, Object)}, but can be used if your swap has a template associated with it.
    *
    * @param session
    *    The bean session to use to get the class meta.
    *    This is always going to be the same bean context that created this swap.
    * @param o The object to be transformed.
    * @param template
    *    The template string associated with this swap.
    * @return The transformed object.
    * @throws Exception If a problem occurred trying to convert the output.
    */
   public S swap(MarshallingSession session, T o, String template) throws Exception {
      throw new SerializeException("Swap method not implemented on ObjectSwap '%s'", cn(this));
   }

   @Override /* Overridden from Object */
   public String toString() {
      return cns(this) + '<' + getNormalClass().getNameSimple() + "," + getSwapClass().getNameSimple() + '>';
   }

   /**
    * If this transform is to be used to reconstitute objects that aren't true Java beans, it must implement this method.
    *
    * @param session
    *    The bean session to use to get the class meta.
    *    This is always going to be the same bean context that created this swap.
    * @param f The transformed object.
    * @param hint
    *    If possible, the parser will try to tell you the object type being created.
    *    For example, on a serialized date, this may tell you that the object being created must be of type
    *    {@code GregorianCalendar}.
    *    <br>This may be <jk>null</jk> if the parser cannot make this determination.
    * @return The narrowed object.
    * @throws Exception If this method is not implemented.
    */
   public T unswap(MarshallingSession session, S f, ClassMeta<?> hint) throws Exception {
      return unswap(session, f, hint, template);
   }

   /**
    * Same as {@link #unswap(MarshallingSession, Object, ClassMeta)}, but can be used if your swap has a template associated with it.
    *
    * @param session
    *    The bean session to use to get the class meta.
    *    This is always going to be the same bean context that created this swap.
    * @param f The transformed object.
    * @param hint
    *    If possible, the parser will try to tell you the object type being created.
    *    For example, on a serialized date, this may tell you that the object being created must be of type
    *    {@code GregorianCalendar}.
    *    <br>This may be <jk>null</jk> if the parser cannot make this determination.
    * @param template
    *    The template string associated with this swap.
    * @return The transformed object.
    * @throws Exception If a problem occurred trying to convert the output.
    */
   public T unswap(MarshallingSession session, S f, ClassMeta<?> hint, String template) throws Exception {
      throw new ParseException("Unswap method not implemented on ObjectSwap '%s'", cn(this));
   }

   /**
    * Returns additional context information for this swap.
    *
    * <p>
    * Typically this is going to be used to specify a template name, such as a FreeMarker template file name.
    *
    * <p>
    * This method can be overridden to programmatically specify a template value.
    *
    * <p>
    * This method is the programmatic equivalent to the {@link Swap#template() @Swap(template)} annotation.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/TemplatedSwaps">Templated Swaps</a>
    * </ul>
    *
    * @return Additional context information, or <jk>null</jk> if not specified.
    */
   public String withTemplate() {
      return null;
   }

   /**
    * Sets the template string on this swap.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/TemplatedSwaps">Templated Swaps</a>
    * </ul>
    *
    * @param template The template string on this swap. Can be <jk>null</jk> to unset the template.
    * @return This object.
    */
   public ObjectSwap<T,?> withTemplate(String template) {
      this.template = template;
      return this;
   }
}