package Torello.Browser.BrowserAPI;

// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Java-HTML Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import Torello.Browser.*;
import Torello.Browser.helper.*;
import Torello.Browser.JavaScriptAPI.*;
import Torello.JSON.*;

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

import Torello.JavaDoc.Annotations.StaticFunctional;
import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg;

import Torello.Browser.BrowserAPI.NestedHelpers.Commands.IO$$Commands;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// JDK Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import javax.json.JsonObject;
import javax.json.JsonValue;

/**
 * <SPAN CLASS=COPIEDJDK><B>Input/Output operations for streams produced by DevTools.</B></SPAN>
 * <EMBED CLASS='external-html' DATA-FILE-ID=CDP.CODE_GEN_NOTE>
 */
@StaticFunctional@JDHeaderBackgroundImg(EmbedTagFileID="CDP.WOOD_PLANK_NOTE")
public class IO
{
    // No Pubic Constructors
    private IO() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Eliminated Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is either obtained from another method or specified as <CODE>blob:{@code <uuid>}</CODE> where
     * <CODE>{@code <uuid>}</CODE> is an UUID of a Blob.

     * <EMBED CLASS='external-html' DATA-CTAS='String' DATA-FILE-ID=CDP.EliminatedType
     *     DATA-NAME=StreamHandle>
     */
    public static final String StreamHandle =
        "StreamHandle has been eliminated.\n" +
        "It was replaced with the standard Java-Type: String";



    // ********************************************************************************************
    // ********************************************************************************************
    // Command-Return Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Read a chunk of the stream
     * 
     * <EMBED CLASS=globalDefs DATA-DOMAIN=IO DATA-API=BrowserAPI DATA-CMD=read>
     * @see IO#read
     */
    @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_CMD_JDHBI")
    public static class read$$RET
        extends BaseType<read$$RET>
        implements java.io.Serializable
    {
        /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
        protected static final long serialVersionUID = 1;

        private static final NestedHelper<IO.read$$RET> singleton =
            Torello.Browser.BrowserAPI.NestedHelpers.CmdReturns.
                IO$$read$$RET.singleton;

        /**
         * Set if the data is base64-encoded
         * <BR /><B CLASS=Opt-Top>OPTIONAL</B>
         */
        public final Boolean base64Encoded;

        /** Data that were read. */
        public final String data;

        /** Set if the end-of-file condition occurred while reading. */
        public final boolean eof;

        /** Constructor.  Please review this class' fields for documentation. */
        public read$$RET
            (ReadOnlyList<Boolean> isPresent, Boolean base64Encoded, String data, boolean eof)
        {
            super(singleton, Domains.IO, "read", 3);

            this.base64Encoded  = base64Encoded;
            this.data           = data;
            this.eof            = eof;

            this.isPresent = (isPresent == null)
                ? singleton.generateIsPresentList(this)
                : THROWS.check(isPresent, 3, "IO.read$$RET");
        }

        /** Creates an instance of this class from a {@link JsonObject}.*/
        public static read$$RET fromJSON(JsonObject jo)
        { return singleton.fromJSON(jo); }

        /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/
        public static NestedDescriptor<read$$RET> descriptor()
        { return singleton.descriptor(); }
    }




    // ********************************************************************************************
    // ********************************************************************************************
    // Commands
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Close the stream, discard any temporary backing storage.
     * 
     * @param handle Handle of the stream to close.
     * 
     * @return An instance of <CODE>{@link Script}&lt;Void&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that
     * the Browser Function has run to completion.
     * </DIV>
     */
    public static Script<Void> close(String handle)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "handle", false, "IO.close", handle);

        return Script.NO_RET(Domains.IO, "close", requestJSON);
    }

    /**
     * Read a chunk of the stream
     * 
     * @param handle Handle of the stream to read.
     * 
     * @param offset 
     * Seek to the specified offset before reading (if not specified, proceed with offset
     * following the last read). Some types of streams may only support sequential reads.
     * <BR /><B CLASS=Opt-Top>OPTIONAL</B>
     * 
     * @param size Maximum number of bytes to read (left upon the agent discretion if not specified).
     * <BR /><B CLASS=Opt-Top>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;{@link read$$RET}&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise}
     * <CODE>&lt;{@link read$$RET}&gt;</CODE> will be returned
     *
     * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>,
     * using {@link Promise#await()}, <I>and the returned result of this Browser Function may
     * be retrieved.</I>
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * This Browser Function's {@code Promise} returns:{@link read$$RET}
     * A dedicated return type implies that the browser may return more than 1 datum
     * </DIV>
     */
    public static Script<read$$RET> read(String handle, Integer offset, Integer size)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            IO$$Commands.read$$, "IO.read",
            handle, offset, size
        );

        return new Script<>(
            Domains.IO, "read", requestJSON,
            read$$RET::fromJSON,
            read$$RET.class
        );
    }

    /**
     * Return UUID of Blob object specified by a remote object id.
     * 
     * @param objectId Object id of a Blob object wrapper.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise}
     * <CODE>&lt;String&gt;</CODE> will be returned
     *
     * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>,
     * using {@link Promise#await()}, <I>and the returned result of this Browser Function may
     * be retrieved.</I>
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * This Browser Function's {@code Promise} returns:
     * <CODE>String (<B>uuid</B>)</CODE>
     * <BR />
     * UUID of the specified Blob.
     * </DIV>
     */
    public static Script<String> resolveBlob(String objectId)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "objectId", false, "IO.resolveBlob", objectId);

        return new Script<>(
            Domains.IO, "resolveBlob", requestJSON,
            jo -> ReadJSON.getString(jo, "uuid", true, false),
            String.class
        );
    }


}