/*
 *  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.causeway.commons.internal.reflection;

import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.lang.reflect.TypeVariable;
import java.lang.reflect.WildcardType;
import java.util.stream.Stream;

import org.jspecify.annotations.Nullable;

import org.apache.causeway.commons.collections.Can;
import org.apache.causeway.commons.internal.base._NullSafe;

import org.jspecify.annotations.NonNull;

/**
 * <h1>- internal use only -</h1>
 * <p>
 * <b>WARNING</b>: Do <b>NOT</b> use any of the classes provided by this package! <br/>
 * These may be changed or removed without notice!
 * </p>
 * @since 2.0
 */
public final class _Generics {

    // -- STREAMING TYPE ARGUMENTS

    /**
     * Returns a Stream of the actual type arguments for given {@code genericType}.
     * @param owner - the corresponding class that declares the field or method,
     *     which uses the {@code genericType}
     * @param genericType
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOf(
            final @NonNull Class<?> owner,
            final @NonNull Type genericType) {

        return (genericType instanceof ParameterizedType)
                ? Stream.of(((ParameterizedType) genericType).getActualTypeArguments())
                        .flatMap(type->streamClassesOfType(owner, type))
                : Stream.empty();
    }

    /**
     * Returns a Stream of the actual type arguments for given {@code genericTypes}.
     * @param owner - the corresponding class that declares the method,
     *     which uses the {@code genericTypes}
     * @param genericTypes
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOf(
            final @NonNull Class<?> owner,
            final @Nullable Type[] genericTypes) {

        return _NullSafe.stream(genericTypes)
                .flatMap(type->streamGenericTypeArgumentsOf(owner, type));
    }

    // -- SHORTCUTS

    /**
     * Returns a Stream of the actual type arguments for given type {@code cls}.
     * @apiNote may return {@link Stream#empty()}, as we don't know how to do this in the general case
     * @implNote will work for simple cases, but NOT for wildcards or non trivial bounds
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOfType(final @NonNull Class<?> cls) {
        return streamGenericTypeArgumentsOfType(cls, cls);
    }

    /**
     * Returns a Stream of the actual type arguments for given type {@code cls} after up-castingn to
     * {@code stopAtSuperClass}.
     * @apiNote may return {@link Stream#empty()}, as we don't know how to do this in the general case
     * @implNote will work for simple cases, but NOT for wildcards or non trivial bounds
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOfType(
            final @NonNull Class<?> cls, final @NonNull Class<?> stopAtSuperClass) {
        var superClass = genericUpCast(cls, stopAtSuperClass);
        if(superClass instanceof ParameterizedType) {
            final ParameterizedType pt = (ParameterizedType) superClass;
            final Type[] typeArgs = pt.getActualTypeArguments();
            final int typeArgCount = _NullSafe.size(typeArgs);
            var extractedGenericTypes = Can.ofArray(typeArgs)
                        .<Class<?>>map(typeArg->typeToClass(typeArg));
            return extractedGenericTypes.size()==typeArgCount
                ? extractedGenericTypes.stream()
                : Stream.empty(); // if any of the type to class conversions failed, return an empty stream
        }
        return Stream.empty();
    }

    /**
     * Returns a Stream of the actual type arguments for given {@code field}.
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOfField(
            final @NonNull Field field) {
        return streamGenericTypeArgumentsOf(
                field.getDeclaringClass(),
                field.getGenericType());
    }

    /**
     * Returns a Stream of the actual type arguments for given {@code method}'s return type.
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOfMethodParameterTypes(
            final @NonNull Method method) {
        return streamGenericTypeArgumentsOf(
                method.getDeclaringClass(),
                method.getGenericParameterTypes());
    }

    /**
     * Returns a Stream of the actual type arguments for given {@code method}'s parameter types.
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOfMethodReturnType(
            final @NonNull Method method) {
        return streamGenericTypeArgumentsOf(
                method.getDeclaringClass(),
                method.getGenericReturnType());
    }

    /**
     * Returns a Stream of the actual type arguments for given {@code param}.
     */
    public static Stream<Class<?>> streamGenericTypeArgumentsOfParameter(
            final @NonNull Parameter param) {
        return streamGenericTypeArgumentsOf(
                param.getDeclaringExecutable().getDeclaringClass(),
                param.getParameterizedType());
    }

    // -- HELPER

    private static Stream<Class<?>> streamClassesOfType(
            final Class<?> owner,
            final Type type) {

        if (type instanceof Class) {
            return Stream.of((Class<?>) type);
        }
        if (type instanceof WildcardType) {
            var wildcardType = (WildcardType) type;
            return Stream.concat(
                        Stream.of(wildcardType.getLowerBounds()),
                        Stream.of(wildcardType.getUpperBounds()))
                    .flatMap(x->streamClassesOfType(owner, x)); // recursive call
        }

        if (type instanceof TypeVariable) {

            // try to match up with the actual type argument of the owner's generic superclass.
            final Type genericSuperclass = owner.getGenericSuperclass();
            if(genericSuperclass instanceof ParameterizedType) {
                var parameterizedTypeOfSuperclass = (ParameterizedType)genericSuperclass;
                var genericDeclaration = ((TypeVariable<?>) type).getGenericDeclaration();
                if(parameterizedTypeOfSuperclass.getRawType() == genericDeclaration) {
                    return Stream.of(parameterizedTypeOfSuperclass.getActualTypeArguments())
                        .flatMap(actualType->streamClassesOfType(owner, actualType)); // recursive call
                }
            }
            // otherwise, what to do?
        }

        return Stream.empty();
    }

    @Nullable
    private static Class<?> typeToClass(final @NonNull Type type) {
        if(type instanceof Class) {
            return (Class<?>) type;
        }
        if(type instanceof ParameterizedType) {
            var pType = (ParameterizedType) type;
            return typeToClass(pType.getRawType());
        }
        // don't know how to do this otherwise
        return null;
    }

    private static Type genericUpCast(final @NonNull Class<?> cls, final @NonNull Class<?> stopAtSuperClass) {
        var superClass = cls.getGenericSuperclass();
        if(cls.equals(stopAtSuperClass)) {
            // don't know how to get a ParameterizedType for cls, so we assume there is a super type to the rescue
            superClass = cls.getGenericSuperclass();
        }
        while (superClass instanceof ParameterizedType
                && stopAtSuperClass != ((ParameterizedType)superClass).getRawType()) {
            superClass = ((Class<?>) ((ParameterizedType) superClass).getRawType()).getGenericSuperclass();
        }
        return superClass;
    }

}
