/*
 * 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
 *
 *      https://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.commons.jexl3.introspection;

import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

import org.apache.commons.jexl3.JexlArithmetic;
import org.apache.commons.jexl3.JexlOperator;

/**
 * 'Federated' introspection/reflection interface to allow JEXL introspection
 * behavior to be customized.
 *
 * @since 1.0
 */
public interface JexlUberspect {
    /**
     * The various builtin property resolvers.
     * <p>
     * Each resolver discovers how to set/get a property with different techniques; seeking
     * method names or field names, etc.
     *
     * @since 3.0
     */
    enum JexlResolver implements PropertyResolver {
        /** Seeks methods named get{P,p}property and is{P,p}property. */
        PROPERTY,

        /** Seeks map methods get/put. */
        MAP,

        /** Seeks list methods to get/set. */
        LIST,

        /** Seeks any get/{set,put} method (quacking like a list or a map). */
        DUCK,

        /**  Seeks public instance members.*/
        FIELD,

        /** Seeks a getContainer(property) and setContainer(property, value) as in {@code x.container.property}. */
        CONTAINER;

        @Override
        public final JexlPropertyGet getPropertyGet(final JexlUberspect uber,
                                                    final Object obj,
                                                    final Object identifier) {
            return uber.getPropertyGet(Collections.singletonList(this), obj, identifier);
        }

        @Override
        public final JexlPropertySet getPropertySet(final JexlUberspect uber,
                                                    final Object obj,
                                                    final Object identifier,
                                                    final Object arg) {
            return uber.getPropertySet(Collections.singletonList(this), obj, identifier, arg);
        }
    }

    /**
     * A marker interface that solves a simple class name into a fully qualified one.
     * <p>The base implementation uses imports.</p>
     * @since 3.6.0
     */
    interface ClassNameResolver {
        /**
         * Resolves a class name.
         * @param name the simple class name
         * @return the fully qualified class name
         */
        String resolveClassName(String name);
    }

    /**
     * A marker interface that solves a class constant by name.
     * <p>The base implementation uses imports to solve enums and public static final fields.</p>
     * @since 3.6.0
     */
    interface ClassConstantResolver extends ClassNameResolver {
        /**
         * Resolves a constant by its name.
         * @param name the constant name, a qualified name
         * @return the constant value or TRY_FAILED if not found
         */
        Object resolveConstant(String name);
    }

    /**
     * The factory type for creating constant resolvers.
     * @since 3.6.0
     */
    interface ConstantResolverFactory {
        /**
         * Creates a constant resolver.
         * @param imports the collection of imports (packages and classes) to use
         * @return a constant resolver
         */
        ClassConstantResolver createConstantResolver(Collection<String> imports);
    }

    /**
     * Abstracts getting property setter and getter.
     * <p>
     * These are used through 'strategies' to solve properties; a strategy orders a list of resolver types,
     * and each resolver type is tried in sequence; the first resolver that discovers a non-null {s,g}etter
     * stops the search.
     *
     * @see JexlResolver
     * @see JexlUberspect#getPropertyGet
     * @see JexlUberspect#getPropertySet
     * @since 3.0
     */
    interface PropertyResolver {

        /**
         * Gets a property getter.
         *
         * @param uber       the uberspect
         * @param obj        the object
         * @param identifier the property identifier
         * @return the property getter or null
         */
        JexlPropertyGet getPropertyGet(JexlUberspect uber, Object obj, Object identifier);

        /**
         * Gets a property setter.
         *
         * @param uber       the uberspect
         * @param obj        the object
         * @param identifier the property identifier
         * @param arg        the property value
         * @return the property setter or null
         */
        JexlPropertySet getPropertySet(JexlUberspect uber, Object obj, Object identifier, Object arg);
    }

    /**
     * Determines property resolution strategy.
     *
     * <p>To use a strategy, you have to set it at engine creation using
     * {@link org.apache.commons.jexl3.JexlBuilder#strategy(JexlUberspect.ResolverStrategy)}
     * as in:</p>
     *
     * {@code JexlEngine jexl = new JexlBuilder().strategy(MY_STRATEGY).create();}
     *
     * @since 3.0
     */
    interface ResolverStrategy {
        /**
         * Applies this strategy to a list of resolver types.
         *
         * @param operator the property access operator, can be null
         * @param obj      the instance we seek to obtain a property setter/getter from, cannot be null
         * @return the ordered list of resolver types, cannot be null
         */
        List<PropertyResolver> apply(JexlOperator operator, Object obj);
    }

    /**
     * A resolver types list tailored for POJOs, favors '.' over '[]'.
     */
    List<PropertyResolver> POJO = Collections.unmodifiableList(Arrays.asList(
            JexlResolver.PROPERTY,
            JexlResolver.MAP,
            JexlResolver.LIST,
            JexlResolver.DUCK,
            JexlResolver.FIELD,
            JexlResolver.CONTAINER
    ));

    /**
     * A resolver types list tailored for Maps, favors '[]' over '.'.
     */
    List<PropertyResolver> MAP = Collections.unmodifiableList(Arrays.asList(
            JexlResolver.MAP,
            JexlResolver.LIST,
            JexlResolver.DUCK,
            JexlResolver.PROPERTY,
            JexlResolver.FIELD,
            JexlResolver.CONTAINER
    ));

    /**
     * The default strategy.
     * <p>
     * If the operator is '[]' or if the operator is null and the object is a map, use the MAP list of resolvers;
     * Other cases use the POJO list of resolvers.
     */
    ResolverStrategy JEXL_STRATEGY = (op, obj) -> {
        if (op == JexlOperator.ARRAY_GET) {
            return MAP;
        }
        if (op == JexlOperator.ARRAY_SET) {
            return MAP;
        }
        if (op == null && obj instanceof Map) {
            return MAP;
        }
        return POJO;
    };

    /**
     * The map strategy.
     *
     * <p>If the operator is '[]' or if the object is a map, use the MAP list of resolvers.
     * Otherwise, use the POJO list of resolvers.</p>
     */
    ResolverStrategy MAP_STRATEGY = (op, obj) -> {
        if (op == JexlOperator.ARRAY_GET) {
            return MAP;
        }
        if (op == JexlOperator.ARRAY_SET) {
            return MAP;
        }
        if (obj instanceof Map) {
            return MAP;
        }
        return POJO;
    };

    /**
     * Gets an arithmetic operator resolver for a given arithmetic instance.
     *
     * @param arithmetic the arithmetic instance
     * @return the arithmetic uberspect or null if no operator method were overridden
     * @since 3.0
     * @see #getOperator(JexlArithmetic)
     */
    JexlArithmetic.Uberspect getArithmetic(JexlArithmetic arithmetic);

    /**
     * Gets an arithmetic operator executor for a given arithmetic instance.
     *
     * @param arithmetic the arithmetic instance
     * @return an operator uberspect instance
     * @since 3.5.0
     */
    default JexlOperator.Uberspect getOperator(final JexlArithmetic arithmetic) {
        return null;
    }

    /**
     * Seeks a class by name using this uberspect class-loader.
     * @param className the class name
     * @return the class instance or null if the class cannot be located by this uberspect class loader or if
     * permissions deny access to the class
     */
    default Class<?> getClassByName(final String className) {
        try {
            return Class.forName(className, false, getClassLoader());
        } catch (final ClassNotFoundException ignore) {
            return null;
        }
    }

    /**
     * Gets the current class loader.
     * @return the class loader
     */
    ClassLoader getClassLoader();

    /**
     * Returns a class constructor.
     *
     * @param ctorHandle a class or class name
     * @param args       constructor arguments
     * @return a {@link JexlMethod}
     * @since 3.0
     */
    JexlMethod getConstructor(Object ctorHandle, Object... args);

    /**
     * Gets an iterator from an object.
     *
     * @param obj to get the iterator from
     * @return an iterator over obj or null
     */
    Iterator<?> getIterator(Object obj);

    /**
     * Returns a JexlMethod.
     *
     * @param obj    the object
     * @param method the method name
     * @param args   method arguments
     * @return a {@link JexlMethod}
     */
    JexlMethod getMethod(Object obj, String method, Object... args);

    /**
     * Property getter.
     * <p>
     * Seeks a JexlPropertyGet apropos to an expression like {@code bar.woogie}.</p>
     * See {@link ResolverStrategy#apply(JexlOperator, Object)}
     *
     * @param resolvers  the list of property resolvers to try
     * @param obj        the object to get the property from
     * @param identifier property name
     * @return a {@link JexlPropertyGet} or null
     * @since 3.0
     */
    JexlPropertyGet getPropertyGet(List<PropertyResolver> resolvers, Object obj, Object identifier);

    /**
     * Property getter.
     *
     * <p>returns a JelPropertySet apropos to an expression like {@code bar.woogie}.</p>
     *
     * @param obj        the object to get the property from
     * @param identifier property name
     * @return a {@link JexlPropertyGet} or null
     */
    JexlPropertyGet getPropertyGet(Object obj, Object identifier);

    /**
     * Property setter.
     * <p>
     * Seeks a JelPropertySet apropos to an expression like {@code foo.bar = "geir"}.</p>
     * See {@link ResolverStrategy#apply(JexlOperator, Object)}
     *
     * @param resolvers  the list of property resolvers to try,
     * @param obj        the object to get the property from
     * @param identifier property name
     * @param arg        value to set
     * @return a {@link JexlPropertySet} or null
     * @since 3.0
     */
    JexlPropertySet getPropertySet(List<PropertyResolver> resolvers, Object obj, Object identifier, Object arg);

    /**
     * Property setter.
     * <p>
     * Seeks a JelPropertySet apropos to an expression like  {@code foo.bar = "geir"}.</p>
     *
     * @param obj        the object to get the property from.
     * @param identifier property name
     * @param arg        value to set
     * @return a {@link JexlPropertySet} or null
     */
    JexlPropertySet getPropertySet(Object obj, Object identifier, Object arg);

    /**
     * Applies this uberspect property resolver strategy.
     *
     * @param op the operator
     * @param obj the object
     * @return the applied strategy resolver list
     */
    List<PropertyResolver> getResolvers(JexlOperator op, Object obj);

    /**
     * Gets this uberspect version.
     *
     * @return the class loader modification count
     */
    int getVersion();

    /**
     * Sets the class loader to use.
     *
     * <p>This increments the version.</p>
     *
     * @param loader the class loader
     */
    void setClassLoader(ClassLoader loader);

}