package Torello.Browser;

import javax.json.JsonObject;
import java.util.function.Consumer;

import Torello.Java.EXCC;
import Torello.Java.StrPrint;


/**
 * <H2>Represents an Internal Java-Side Failure During WebSocket Communication</H2>
 * 
 * This class is used to represent errors that arise during the execution of internal logic
 * within the Java-based infrastructure responsible for interacting with the Chrome DevTools
 * Protocol (CDP) over WebSockets. It is the conceptual opposite of {@link BrowserError}, which
 * represents errors *reported by the browser itself*.
 * 
 * <BR /><BR />
 * {@code RDPError} instances are thrown or passed downstream whenever an unexpected or
 * invalid condition is detected by the Java-side handlers that process inbound or outbound
 * messages on the WebSocket channel.
 *
 * <BR /><BR />
 * These are *not* errors originating from the browser. Instead, they usually reflect one of
 * the following situations:
 *
 * <BR /><BR /><UL CLASS=JDUL>
 * <LI>Failures inside message-processing logic (e.g., malformed or unrecognized JSON)</LI>
 * <LI>Unchecked runtime exceptions triggered by handler code (e.g., NPE, casting failures)</LI>
 * <LI>Unexpected conditions raised by the NeoVisionaries WebSocket implementation</LI>
 * <LI>Structural violations in expected CDP response formats</LI>
 * </UL>
 *
 * <BR />{@code RDPError} objects can optionally include:
 *
 * <BR /><BR /><UL CLASS=JDUL>
 * <LI>A textual message describing the failure</LI>
 * <LI>The raw {@code JsonObject} that caused the error (if applicable)</LI>
 * <LI>A {@code Throwable} that was caught and wrapped</LI>
 * </UL>
 * 
 * <BR /><BR /><B CLASS=JDDescLabel2>Causing these Errors:</B>
 * <BR />
 * All instantiations of this class occur inside one of the four internal infrastructure
 * classes:
 *
 * <BR /><BR /><UL CLASS=JDUL>
 * 
 * <LI> <B><CODE><A HREF='hilite-files/HandleScriptResponse.java.html'>
 *      HandleScriptResponse</A></CODE></B>
 *      </LI>
 * 
 * <LI> <B><CODE><A HREF='hilite-files/HandleDispatch.java.html'>
 *      HandleDispatch</A></CODE></B>
 *      </LI>
 * 
 * <LI><B><CODE><A HREF='hilite-files/HandleEvent.java.html'>HandleEvent</A></CODE></B></LI>
 * <LI><B><CODE><A HREF='hilite-files/WSAdapter.java.html'>WSAdapter</A></CODE></B></LI>
 * </UL>
 *
 * <BR />
 * Because these errors reflect misbehavior or malformation in Java-managed logic, they should
 * never be ignored. They often signal bugs in parsing logic, protocol desynchronization, or
 * incorrect assumptions in command/response handling.
 * 
 * <BR /><BR /><BR /><B CLASS=JDDescLabel2>Registering a Handler:</B>
 * <BR />
 * To receive instances of this error class, a handler must be registered at the time you create
 * your {@link WebSocketSender} using one of the {@code createSender(...)} methods found in either
 * {@link BrowserConn#createSender BrowserConn} or {@link PageConn#createSender PageConn}. These
 * methods allow you to provide lambda handlers or consumer functions for error callbacks. Without
 * explicitly setting a handler for this error type, you will never see these errors—they will be
 * silently discarded or ignored by the internal infrastructure.
 * 
 * <BR /><BR />
 * Each of the three CDP error/response types — {@link RDPError}, {@link BrowserError}, and 
 * {@link BrowserEvent} — has its own dedicated handler. These are supplied as {@code Consumer}
 * arguments to {@code createSender(...)}, and any logic you wish to perform in response to these
 * events must be defined there. The {@code WebSocketSender} will invoke these handlers
 * automatically whenever it receives a message of the corresponding kind.
 */
public final class RDPError
    implements java.io.Serializable, Comparable<RDPError>
{
    /** <EMBED CLASS=external-html DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // Public, Final Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * A descriptive message explaining the nature of the internal error.
     *
     * <BR /><BR />
     * This string is almost always provided by the handler logic itself to contextualize what went
     * wrong — e.g., "Unrecognized ID field", "Unexpected type in CDP response", or "Missing
     * 'method' property in event dispatch."
     */
    public final String message;

    /**
     * The underlying exception or cause that led to this RDPError.
     *
     * <BR /><BR />
     * This may include {@code NullPointerException}, {@code ClassCastException}, or any
     * other unchecked exception that occurred during handler execution. It may be {@code null}
     * if the error was raised directly without an underlying Throwable.
     */
    public final Throwable cause;

    /**
     * The raw {@link JsonObject} that was being processed at the time the error occurred.
     *
     * <BR /><BR />
     * This field is useful for debugging. It often contains the browser's CDP response that
     * the Java code failed to parse or recognize. It may be {@code null} if the failure was
     * unrelated to message content (e.g., a runtime exception).
     */
    public final JsonObject jo;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    RDPError(String message)
    {
        if (message == null) System.err.println("Input to Error has a null message");

        this.message    = message;
        this.jo         = null;
        this.cause      = null;
    }

    RDPError(final String message, final JsonObject jo)
    {
        if (message == null)
            System.err.println("Input to RDPError Constructor  has a null message");

        if (jo == null) System.err.println
            ("Input to RDPError Constructor has a null JsonObject-Parameter");

        this.message    = message;
        this.jo         = jo;
        this.cause      = null;
    }

    RDPError(final String message, final Throwable cause)
    {
        if (message == null) System.err.println
            ("Input to RDPError Constructor  has a null message");

        if (cause == null) System.err.println
            ("Input to RDPError Constructor has a null Throwable-Parameter");

        this.message    = message;
        this.cause      = cause;
        this.jo         = null;
    }

    RDPError(String message, JsonObject jo, Throwable cause)
    {
        if (message == null) System.err.println
            ("Input to RDPError Constructor  has a null message");

        if (jo == null) System.err.println
            ("Input to RDPError Constructor has a null JsonObject-Parameter");

        if (cause == null) System.err.println
            ("Input to RDPError Constructor has a null Throwable-Parameter");

        this.message    = message;
        this.jo         = jo;
        this.cause      = cause;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object, Comparable, Clonable
    // ********************************************************************************************
    // ********************************************************************************************


    @Override
    public String toString()
    {
        final String jsonStr = (jo == null)
            ? "    JSON: NULL"
            : ("    JSON: \n" + PrintUtil.json2(jo));

        final String causeStr = (cause == null)
            ? "    Cause Throwable: NULL"
            : ("    Cause: \n" + EXCC.toString(cause));

        return 
            "RDPError Object\n" +
            "{\n" +
                "    Message: " + message + '\n' +
                jsonStr + '\n' +
                causeStr + '\n' +
            '}';
    }

    @Override
    public int hashCode()
    { return message.hashCode(); }

    @Override
    public boolean equals(Object o)
    {
        if (this == o) return true;
        if (o == null) return false;

        if (this.getClass() != o.getClass()) return false;

        final RDPError error = (RDPError) o;

        return (message.equals(error.message));
    }

    @Override
    public int compareTo(RDPError error)
    { return this.message.compareTo(error.message); }
}