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

import java.lang.reflect.*;

import org.apache.juneau.commons.conversion.*;
import org.apache.juneau.marshall.*;

/**
 * Generic object converter implementation.
 *
 * <p>
 * A simple implementation of the {@link Converter} interface that delegates to the default
 * {@link MarshallingContext} session for type conversion.
 *
 * <p>
 * This converter provides a convenient way to convert objects between different types using
 * the same conversion logic that's used throughout the Juneau framework.
 *
 * <h5 class='section'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Convert a string to an integer</jc>
 *    Integer <jv>result</jv> = GenericConverter.INSTANCE.convertTo(Integer.<jk>class</jk>, <js>"123"</js>);
 *    <jc>// result = 123</jc>
 *
 *    <jc>// Convert a map to a bean</jc>
 *    MyBean <jv>bean</jv> = GenericConverter.INSTANCE.convertTo(MyBean.<jk>class</jk>, <jv>map</jv>);
 * </p>
 *
 * <h5 class='section'>Thread Safety:</h5>
 * <p>
 * This class is thread-safe. The singleton instance can be safely shared across multiple threads.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='jm'>{@link Converter}
 *    <li class='jm'>{@link MarshallingContext#DEFAULT_SESSION}
 *    <li class='jm'>{@link MarshallingSession#convertToType(Object, Class)}
 * </ul>
 */
@SuppressWarnings({
   "java:S6541", // Stateless converter, singleton for convenience
   "java:S6548" // Singleton pattern is intentional; INSTANCE is a stateless, thread-safe shared converter
})
public class MarshallingContextConverter implements Converter {

   /**
    * Singleton instance of the generic converter.
    *
    * <p>
    * This instance can be safely shared across multiple threads and reused for all conversion operations.
    */
   public static final MarshallingContextConverter INSTANCE = new MarshallingContextConverter();

   /**
    * Constructor.
    */
   private MarshallingContextConverter() {}

   /**
    * Converts the specified object to the specified type.
    *
    * <p>
    * This method delegates to the default {@link MarshallingContext} session for the actual conversion logic.
    * It supports all the same conversion types that are supported by the framework's bean conversion system.
    *
    * <p>
    * Supported conversions include:
    * <ul>
    *    <li>Primitive types and their wrapper classes
    *    <li>String to Number conversions
    *    <li>Map to Bean conversions
    *    <li>Collection to Array conversions
    *    <li>Enum conversions
    *    <li>Object swap conversions
    *    <li>And many more...
    * </ul>
    * @param o The object to convert.
    * @param type The target class type.
    *
    * @param <T> The target type to convert to.
    * @return The converted object, or <jk>null</jk> if the input object is <jk>null</jk>.
    * @throws InvalidDataConversionException If the object cannot be converted to the specified type.
    */
   @Override
   public <T> T to(Object o, Class<T> type) {
      return MarshallingContext.DEFAULT_SESSION.convertToType(o, type);
   }

   /**
    * Converts the specified object to the specified parameterized type.
    *
    * <p>
    * This method delegates to the default {@link MarshallingContext} session for the actual conversion logic,
    * supporting complex parameterized types such as collections and maps.
    *
    * @param o The object to convert.
    * @param mainType The main type to convert to.
    * @param args The type parameters of the main type.
    * @param <T> The target type to convert to.
    * @return The converted object, or <jk>null</jk> if the input object is <jk>null</jk>.
    * @throws InvalidDataConversionException If the object cannot be converted to the specified type.
    */
   @Override
   public <T> T to(Object o, Type mainType, Type... args) {
      return MarshallingContext.DEFAULT_SESSION.convertToType(o, mainType, args);
   }

   /**
    * Converts the specified object to the specified type, using the given outer instance for
    * non-static inner class construction.
    *
    * @param o The object to convert.
    * @param memberOf The outer instance for non-static inner class construction, or <jk>null</jk> if the target is
    *    not a non-static inner member class.
    * @param session The converter session, or <jk>null</jk> (ignored either way; this implementation does not use a
    *    converter session).
    * @param type The target class type.
    * @param <T> The target type to convert to.
    * @return The converted object, or <jk>null</jk> if the input object is <jk>null</jk>.
    * @throws InvalidDataConversionException If the object cannot be converted to the specified type.
    */
   @Override
   public <T> T to(Object o, Object memberOf, ConverterSession session, Class<T> type) {
      return MarshallingContext.DEFAULT_SESSION.convertToMemberType(memberOf, o, type);
   }

   /**
    * Converts the specified object to the specified parameterized type, using the given outer instance for
    * non-static inner class construction.
    *
    * @param o The object to convert.
    * @param memberOf The outer instance for non-static inner class construction, or <jk>null</jk> if the target is
    *    not a non-static inner member class.
    * @param session The converter session, or <jk>null</jk> (ignored either way; this implementation does not use a
    *    converter session).
    * @param mainType The main type to convert to.
    * @param args The type parameters of the main type.
    * @param <T> The target type to convert to.
    * @return The converted object, or <jk>null</jk> if the input object is <jk>null</jk>.
    * @throws InvalidDataConversionException If the object cannot be converted to the specified type.
    */
   @SuppressWarnings({
      "unchecked" // Cast is safe: type parameter verified by caller context.
   })
   @Override
   public <T> T to(Object o, Object memberOf, ConverterSession session, Type mainType, Type... args) {
      var rawType = (Class<T>) (mainType instanceof ParameterizedType mainType2 ? mainType2.getRawType() : (Class<?>) mainType);
      return MarshallingContext.DEFAULT_SESSION.convertToMemberType(memberOf, o, rawType);
   }
}