package Torello.Browser;

import static Torello.Java.StrPrint.I4;

import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.lang.reflect.MalformedParametersException;

import Torello.Java.ReadOnly.ReadOnlyArrayList;
import Torello.Java.ReadOnly.ReadOnlyList;

/**
 * Reflected information / data which has been extracted from one of the generated CDP domain
 * command methods.
 * 
 * <BR /><BR />
 * A "Domain Command" is any static method generated inside one of the primary browser domain
 * classes.  For example:
 * 
 * <BR /><BR />
 * <B><CODE>{@link Torello.Browser.JavaScriptAPI.RunTime#evaluate}</CODE></B>
 * 
 * <BR /><BR />
 * is a command method declared inside the {@code RunTime} domain class.  It accepts 16 input
 * parameters, most of which are optional.  Its corresponding {@code CommandDescriptor} singleton
 * is created and stored inside the generated command-helper class for that domain:
 * 
 * <BR /><BR />
 * <B><CODE><A HREF='JavaScriptAPI/hilite-files/RunTime$$Commands.java.html'>RunTime$$Commands
 * </A></CODE></B>
 * 
 * <BR /><BR />
 * The descriptor stores the command name, browser domain, parameter names, CDP type constants,
 * optional-parameter flags, experimental-parameter flags, and the Java {@link Class} returned by
 * the command.  This metadata is used by {@link CommandBuilder} to construct a {@link Script}
 * without requiring the user to write long method invocations filled with {@code null}
 * placeholders.
 * 
 * @param <T> The Java type returned by the {@link Script} created for this command.  This type
 * parameter allows {@code CommandDescriptor<T>} to work together with
 * {@link CommandBuilder}{@code <T>}.
 */
public class CommandDescriptor<T>
    extends AbstractDescriptor
    implements java.io.Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1L;

    /** The Java {@code Class} returned by the command. */
    public final Class<T> returnClass;

    // This package-private field is used by the "CommandBuilder" class's "build()" method
    private transient java.lang.reflect.Method method = null;

    // This is used below
    private transient java.lang.reflect.Parameter[] parameters = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor & toString
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is a public constructor, but it's primarily intended for internal use.
     * 
     * <!-- NOTE: Chat-GPT wrote these "Single Line Summaries!"  Pretty nifty... -->
     * 
     * @param name The name of the CDP type described by this descriptor.
     * @param domain The Browser Domain containing the described CDP type.
     * @param names Parallel list of CDP property names.
     * @param types Parallel list of {@link CDPTypes CDP Type Constants}.
     * @param optionals Parallel list indicating which properties are {@code optional}.
     * @param experimentals Parallel list indicating which properties are {@code experimental}.
     * @param returnClass The Java {@code Class} returned by the command.
     */
    public CommandDescriptor(
            final String                name,
            final Domains               domain,
            final ReadOnlyList<String>  names,
            final ReadOnlyList<Byte>    types,
            final ReadOnlyList<Boolean> optionals,
            final ReadOnlyList<Boolean> experimentals,
            final Class<T>              returnClass
        )
    {
        super(name, domain, names, types, optionals, experimentals);
        this.returnClass = returnClass;
    }

    /**
     * Generates a reasonable {@code String} representation of {@code 'this'} instance.
     * @return A Java {@code String}
     */
    @Override
    public String toString()
    {
        return 
            "CommandDescriptor:\n" +
            "{\n" +
            super.toString() +
            '\n' +
            I4 + "returnClass:   " + this.returnClass.getCanonicalName() + '\n' +
            "}\n";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private Reflection Methods
    // ********************************************************************************************
    // ********************************************************************************************


    // Allows the CommandBuilder to verify if a user has passed a valid class
    Class<?> getClass(final String name, final int index)
    {
        if (this.parameters == null)

            try 
                { this.parameters = this.method().getParameters(); }

            catch (MalformedParametersException e)
                { throw new CommandDescriptorError("Unable to retrieve method parameters", e); }

        return this.parameters[index].getType();
    }

    Method method()
    {
        if (this.method != null) return method;

        try
        {
            final Method[] methods =
                this.domain.getDomainClass().getMethods();

            if (methods == null)
                throw new CommandDescriptorError("getMethods() returned null");

            Method found = null;

            for (final Method m : methods)
            {
                if (m == null) continue;

                /*
                System.out.println(
                    "m.getName():       " + m.getName()                         + '\n' +
                    "this.name:         " + this.name                           + '\n' +
                    "m.getReturnType(): " + m.getReturnType()                   + '\n' +
                    "this.returnClass:  " + this.returnClass.getCanonicalName() + '\n' +
                    '\n'
                );
                */

                if (m.getName().equals(this.name))
                    if (m.getReturnType().equals(Script.class))
                    {
                        if (found != null) throw new CommandDescriptorError(
                            "More than one method matched command name '" +
                            this.name + '\''
                        );

                        found = m;
                    }
            }

            if (found == null) throw new CommandDescriptorError
                ("Unable to locate command method named '" + this.name + '\'');

            if (Modifier.isStatic(found.getModifiers()) == false) throw new CommandDescriptorError
                ("The reflected command method is not static.");

            this.method = found;
        }

        catch (SecurityException e)
        {
            throw new CommandDescriptorError(
                "There was an error extracting this command's method from its Domain Class.  " +
                "Please see the getCause() throwable for details.",
                e
            );
        }

        if (method.getParameterCount() != this.size) throw new CommandDescriptorError(
            "The number of parameters in the method which was retrieved is " +
            method.getParameterCount() + ", but the number of parameters listed in the " +
            "command descriptor is " + this.size + ".  These numbers should be equal."
        );

        return this.method;
    }

    private static class CommandDescriptorError extends Error
    {
        protected static final long serialVersionUID = 1;

        private CommandDescriptorError(final String message)
        { super(message); }

        private CommandDescriptorError(final String message, final Throwable cause)
        { super(message, cause); }
    }
}