package Torello.Browser.JsonAST;

import java.io.File;
import Torello.Java.LFEC;

/**
 * This class is the primary User-Interaction API class.  This class will load the "already parsed"
 * a.k.a. the "already generated" AST Object Instances from the Java-HTML {@code '.jar'} File into 
 * memory from disk.  This class uses the standard JDK Object serialization and de-serialization 
 * techniques.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=SERIALIZED_AST>
 */
public class SERIALIZED_AST implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    /**
     * The Java-HTML {@code '.jar'} File contains a data-file by this name.  Using standard Java 
     * Serialization, both Google's "JavaScript API" and Google's "Browser API" have had their
     * Abstract Syntax Tree's serialized (saved) to disk.
     * 
     * <BR /><BR />
     * If you don't remember how to load a serialized data-file into memory, there is a simple
     * method in this class which does just that.  (See {@link #deserializeFromJAR()})
     *
     */
    public static final String FILE_NAME_JAR = "SerializedAST.dat";

    /**
     * This is an instance field, and after the AST's have been loaded from the {@code '.jar'} 
     * file, this field will contain the Abstract Syntax Tree for Google's "Browser API" suite of
     * methods, types and events.
     * 
     * <BR /><BR />
     * Remember that all of the public-facing methods &amp; fields in the AST nodes are declared
     * {@code 'final'}.  Any lists or sets present in these nodes have been built with classes from
     * Java-HTML's "Read Only" Package.  It is impossible to break, ruin or screw-up these trees.
     * <B STYLE='color: red;'><I>They, and their contents, are perfectly immutable!</I></B>
     * 
     * @see #deserializeFromJAR()
     */
    public final API browserAPI;

    /**
     * This is an instance field, and after the AST's have been loaded from the {@code '.jar'} 
     * file, this field will contain the Abstract Syntax Tree for Google's "JavaScript API" suite
     * of methods, types and events.
     * 
     * <BR /><BR />
     * Remember that all of the public-facing methods &amp; fields in the AST nodes are declared
     * {@code 'final'}.  Any lists or sets present in these nodes have been built with classes from
     * Java-HTML's "Read Only" Package.  It is impossible to break, ruin or screw-up these trees.
     * <B STYLE='color: red;'><I>They, and their contents, are perfectly immutable!</I></B>
     * 
     * @see #deserializeFromJAR()
     */
    public final API jsAPI;

    /**
     * This is some rather boring "facts" about the classes and methods in the AST ("the tree").
     * This data-field and group of Read-Only "sets" and "lists" exists solely to make the actual
     * code written for the (proprietary, and non-visible) Java-HTML Browser Package Code Generator
     * look a little nicer and a little bit easier to read.
     * 
     * <BR /><BR />
     * You may review these lists; they aren't that interesting.  The contents of the
     * {@link InfoData} are all declared {@code 'final'} and typed using "Read Only" data-types.
     * They are perfectly immutable, and you cannot "screw them up" or anything like that. 😀😀
     */
    public final InfoData browserDat;

    /**
     * This is some rather boring "facts" about the classes and methods in the AST ("the tree").
     * This data-field and group of Read-Only "sets" and "lists" exists solely to make the actual
     * code written for the (proprietary, and non-visible) Java-HTML Browser Package Code Generator
     * look a little nicer and a little bit easier to read.
     * 
     * <BR /><BR />
     * You may review these lists; they aren't that interesting.  The contents of the
     * {@link InfoData} are all declared {@code 'final'} and typed using "Read Only" data-types.
     * They are perfectly immutable, and you cannot "screw them up" or anything like that. 😀😀
     */
    public final InfoData jsDat;

    SERIALIZED_AST(
            final API       browserAPI,
            final API       jsAPI,
            final InfoData  browserDat,
            final InfoData  jsDat
        )
    {
        this.browserAPI = browserAPI;
        this.jsAPI      = jsAPI;
        this.browserDat = browserDat;
        this.jsDat      = jsDat;
    }

    /**
     * Reads both {@link API API's} (the "Browser API" and the "JavaScript API") from disk, and
     * into Java Memory.  The {@code 'API'} class is the root node of an Abstract Syntax Treee,
     * or AST.  It is just the "Java-ized" variant of the Protocol-API which Google has specified
     * using the two {@code '.json'} files:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B><CODE><A HREF='../doc-files/protocol_as_json/browser_protocol.json'>
     * browser_protocol.json</A></CODE></B></LI>
     * 
     * <LI><B><CODE><A HREF='../doc-files/protocol_as_json/js_protocol.json'>
     * js_protocol.json</A></CODE></B></LI>
     * </UL>
     * 
     * @return An instance of this class, with all four data-fields properly initialized.
     * @see LFEC#readObjectFromFile_JAR(Class, String, boolean, Class)
     */
    public static SERIALIZED_AST deserializeFromJAR()
    {
        // readObjectFromFile_JAR
        // (
        //      Class<?> classLoaderClass,
        //      String f,
        //      boolean zip,
        //      Class<T> returnClass
        // )

        return LFEC.readObjectFromFile_JAR(
            SERIALIZED_AST.class,
            "data-files" + File.separator + FILE_NAME_JAR,
            true,
            SERIALIZED_AST.class 
        );
    }
}