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

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

import java.lang.reflect.*;
import java.util.*;

import org.apache.juneau.commons.inject.*;

/**
 * Utility class providing convenient static methods for creating reflection info objects.
 *
 * <p>
 * This class provides static factory methods that convert standard Java reflection objects
 * ({@link Class}, {@link Method}, {@link Field}, {@link Constructor}) to their corresponding
 * info wrapper objects ({@link ClassInfo}, {@link MethodInfo}, {@link FieldInfo}, {@link ConstructorInfo}).
 *
 * <h5 class='section'>Features:</h5>
 * <ul class='spaced-list'>
 *    <li>Convenient factory methods - convert reflection objects to info wrappers
 *    <li>Null-safe - methods handle <jk>null</jk> inputs gracefully
 *    <li>Unified API - consistent method naming across all reflection types
 * </ul>
 *
 * <h5 class='section'>Use Cases:</h5>
 * <ul class='spaced-list'>
 *    <li>Converting reflection objects to info wrappers in a consistent way
 *    <li>Simplifying code that works with both reflection and info objects
 *    <li>Providing a centralized location for reflection-to-info conversions
 * </ul>
 *
 * <h5 class='section'>Usage:</h5>
 * <p class='bjava'>
 *    <jc>// Convert Class to ClassInfo</jc>
 *    ClassInfo <jv>ci</jv> = ReflectionUtils.<jsm>info</jsm>(MyClass.<jk>class</jk>);
 *
 *    <jc>// Convert Method to MethodInfo</jc>
 *    Method <jv>m</jv> = MyClass.<jk>class</jk>.getMethod(<js>"myMethod"</js>);
 *    MethodInfo <jv>mi</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>m</jv>);
 *
 *    <jc>// Convert Field to FieldInfo</jc>
 *    Field <jv>f</jv> = MyClass.<jk>class</jk>.getField(<js>"myField"</js>);
 *    FieldInfo <jv>fi</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>f</jv>);
 *
 *    <jc>// Convert Constructor to ConstructorInfo</jc>
 *    Constructor&lt;?&gt; <jv>c</jv> = MyClass.<jk>class</jk>.getConstructor();
 *    ConstructorInfo <jv>ci2</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>c</jv>);
 * </p>
 *
 * <h5 class='section'>Null Handling:</h5>
 * <p>
 * All methods in this class handle <jk>null</jk> inputs gracefully, returning <jk>null</jk> if the
 * input is <jk>null</jk>. This makes it safe to use in scenarios where reflection objects may be <jk>null</jk>.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='jc'>{@link ClassInfo} - Class introspection wrapper
 *    <li class='jc'>{@link MethodInfo} - Method introspection wrapper
 *    <li class='jc'>{@link FieldInfo} - Field introspection wrapper
 *    <li class='jc'>{@link ConstructorInfo} - Constructor introspection wrapper
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauCommonsReflection">Reflection Package</a>
 * </ul>
 */
public class ReflectionUtils {

   /**
    * Prevents instantiation.
    */
   private ReflectionUtils() {}

   /**
    * Returns the {@link ClassInfoTyped} wrapper for the specified class.
    *
    * @param <T> The class type.
    * @param o The class to wrap. Can be <jk>null</jk>.
    * @return The {@link ClassInfoTyped} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
    */
   public static final <T> ClassInfoTyped<T> info(Class<T> o) {
      return ClassInfo.of(o);
   }

   /**
    * Returns the {@link ConstructorInfo} wrapper for the specified constructor.
    *
    * @param o The constructor to wrap. Can be <jk>null</jk>.
    * @return The {@link ConstructorInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
    */
   public static final ConstructorInfo info(Constructor<?> o) {
      return ConstructorInfo.of(o);
   }

   /**
    * Returns the {@link FieldInfo} wrapper for the specified field.
    *
    * @param o The field to wrap. Can be <jk>null</jk>.
    * @return The {@link FieldInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
    */
   public static final FieldInfo info(Field o) {
      return FieldInfo.of(o);
   }

   /**
    * Returns the {@link MethodInfo} wrapper for the specified method.
    *
    * @param o The method to wrap. Can be <jk>null</jk>.
    * @return The {@link MethodInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
    */
   public static final MethodInfo info(Method o) {
      return MethodInfo.of(o);
   }

   /**
    * Returns the {@link ClassInfo} wrapper for the class of the specified object.
    *
    * @param o The object whose class to wrap. Can be <jk>null</jk>.
    * @return The {@link ClassInfo} wrapper for the object's class, or <jk>null</jk> if the input is <jk>null</jk>.
    */
   public static final ClassInfo info(Object o) {
      return ClassInfo.of(o);
   }

   /**
    * Converts a class to an enum class, suppressing rawtypes warnings.
    *
    * <p>
    * This utility method wraps {@link Class#asSubclass(Class)} for enum classes and suppresses
    * the rawtypes warning that occurs when converting to {@code Class<? extends Enum>} for use
    * with methods like {@link EnumSet#allOf(Class)}.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Instead of:</jc>
    *    <ja>@SuppressWarnings</ja>(<js>"rawtypes"</js>)
    *    Class&lt;? <jk>extends</jk> Enum&gt; <jv>enumClass</jv> = <jv>clazz</jv>.asSubclass(Enum.<jk>class</jk>);
    *
    *    <jc>// Use:</jc>
    *    Class&lt;? <jk>extends</jk> Enum&gt; <jv>enumClass</jv> = ReflectionUtils.<jsm>asEnumClass</jsm>(<jv>clazz</jv>);
    * </p>
    *
    * @param clazz The class to convert. Must be an enum class. Must not be <jk>null</jk>.
    * @return The enum class as a raw type suitable for use with {@link EnumSet#allOf(Class)}.
    * @throws ClassCastException if the class is not an enum class.
    */
   @SuppressWarnings({
      "rawtypes" // Raw types necessary for enum class return
   })
   public static Class<? extends Enum> asEnumClass(Class<?> clazz) {
      return clazz.asSubclass(Enum.class);
   }

   /**
    * Resolves and creates a collection, array, or map containing all beans of the element type from the bean store.
    *
    * <p>
    * This is a helper method used internally by {@link ParameterInfo} and {@link FieldInfo} for resolving collection values.
    *
    * @param elementType The element type (for arrays/collections) or value type (for maps).
    * @param beanStore The bean store to retrieve beans from.
    * @param targetType The target collection type (must be a collection type).
    * @return The collection, array, or map containing all beans of the element type, or <jk>null</jk> if not a supported collection type.
    */
   static Object resolveCollectionValue(Class<?> elementType, BeanStore beanStore, ClassInfo targetType) {
      if (elementType == null || ! targetType.isInjectCollectionType())
         return null;

      // Get all beans of the element type
      var beans = beanStore.getBeansOfType(elementType);

      // Handle Map<String,T> - getBeansOfType already returns Map<String,T>
      var inner = o(targetType.inner()).orElse(Object.class);
      if (Map.class.isAssignableFrom(inner)) {
         // Verify it's Map<String,T> by checking the parameterized type
         Type parameterizedType = targetType.innerType();
         if (parameterizedType instanceof ParameterizedType parameterizedType2) {
            var typeArgs = parameterizedType2.getActualTypeArguments();
            if (typeArgs.length >= 2 && typeArgs[0] == String.class) {
               return new LinkedHashMap<>(beans);
            }
         }
         return null;
      }

      var values = new ArrayList<>(beans.values());

      // Convert to appropriate collection/array type
      if (targetType.isArray()) {
         var array = Array.newInstance(elementType, values.size());
         for (var i = 0; i < values.size(); i++)
            Array.set(array, i, values.get(i));
         return array;
      }

      if (eq(inner, Set.class)) {
         return new LinkedHashSet<>(values);
      } else if (eq(inner, List.class)) {
         return values;
      }

      // Defensive check: return null if inner is null or not a supported collection type.
      return null;
   }
}