001package Torello.Browser.JsonAST;
002
003import static Torello.Java.C.BYELLOW;
004import static Torello.Java.C.RESET;
005
006import Torello.JavaDoc.Annotations.LinkJavaSource;
007import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg;
008
009import Torello.Java.StorageWriter;
010import Torello.Java.LFEC;
011
012import Torello.Java.ReadOnly.ReadOnlyList;
013import Torello.Java.ReadOnly.ROArrayListBuilder;
014
015import javax.json.Json;
016import javax.json.JsonObject;
017
018import java.io.StringReader;
019import java.util.Iterator;
020
021
022/**
023 * Contains a {@link ReadOnlyList} that has each domain defined in the API.  There are exactly two
024 * API's that Google has created in its CDP (Chrome DevTools Protocol) System: the "Browser API",
025 * and the "JavaScript API".
026 * 
027 * <EMBED CLASS='external-html' DATA-FILE-ID=AST_TREES>
028 */
029@JDHeaderBackgroundImg(EmbedTagFileID="AST_NODES_JDHBI")
030public class API implements java.io.Serializable, Comparable<API>, Iterable<Domain>
031{
032    // ********************************************************************************************
033    // ********************************************************************************************
034    // STATIC FINAL FIELDS
035    // ********************************************************************************************
036    // ********************************************************************************************
037
038
039    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
040    protected static final long serialVersionUID = 1;
041
042
043    // ********************************************************************************************
044    // ********************************************************************************************
045    // Constant & Final Instance Fields
046    // ********************************************************************************************
047    // ********************************************************************************************
048
049
050    public final int id = IDManager.nextID();
051
052    /** Contains the Json Specifiction File's name */
053    public final String inFileName;
054
055    /** This will either contain the {@code String "BrowserAPI"} or the {@code "JavaScriptAPI"}  */
056    public final String name;
057
058    /** The complete list of domain's in the API, extracted &amp; parsed from the Json File. */
059    public final ReadOnlyList<Domain> domains;
060
061
062    // ********************************************************************************************
063    // ********************************************************************************************
064    // Accessors:  There is No Linking, No Simplifying ==> therefore no Non-Constant Fields
065    // ********************************************************************************************
066    // ********************************************************************************************
067
068
069    /**
070     * This method merely iterates the list of domain's contained by this API, to find and return 
071     * the domain whose name matches {@code 'domainName'}.
072     * 
073     * @param domainName the name of one of the domain's in this API, as a {@code java.lang.String}
074     * 
075     * @return The domain whose {@link Entity Domain.name} matches {@code 'domainName'}, or null if
076     * no such domain exists.
077     */
078    public Domain findDomain(String domainName)
079    {
080        for (Domain domain : domains) if (domain.name.equals(domainName)) return domain;
081        return null;
082    }
083
084
085    // ********************************************************************************************
086    // ********************************************************************************************
087    // Package Private Constructor
088    // ********************************************************************************************
089    // ********************************************************************************************
090
091
092    // This parses a JSON Object File for the Browser-API and the Java-Script API
093    API(
094            final StorageWriter sw,
095            final String        inFileName,
096            final String        apiName
097        )
098    {
099        this.inFileName = inFileName;
100        this.name       = apiName;
101        
102        sw.println("Reading File: " + BYELLOW + inFileName + RESET);
103
104        final String                        apiFile = LFEC.loadFile(inFileName);
105        final StringReader                  sr      = new StringReader(apiFile);
106        final JsonObject                    jo      = Json.createReader(sr).readObject();
107        final ROArrayListBuilder<Domain>    roalb   = new ROArrayListBuilder<>();
108
109        final Iterator<JsonObject> iter = jo
110            .getJsonArray("domains")
111            .getValuesAs(JsonObject.class)
112            .iterator();
113
114        while (iter.hasNext()) roalb.add(new Domain(this, iter.next()));
115
116        roalb.sort((Domain d1, Domain d2) -> d1.name.compareTo(d2.name));
117
118        this.domains = roalb.build();
119    }
120
121
122    // ********************************************************************************************
123    // ********************************************************************************************
124    // Comparable, java.lang.Object
125    // ********************************************************************************************
126    // ********************************************************************************************
127
128
129    /**
130     * Returns an {@code Iterator} that iterates the contents of the {@link #domains} list.
131     * 
132     * @see #domains
133     * @see Torello.Java.Additional.RemoveUnsupportedIterator
134     */
135    public Iterator<Domain> iterator()
136    { return this.domains.iterator(); }
137
138    /**
139     * Checks {@link #name} fields, using the standard {@code String.compareTo} to produce a
140     * comparison value.
141     */
142    public int compareTo(final API other)
143    {
144        if (this == other) return 0;
145        if (other == null) return 1;
146
147        return this.name.compareTo(other.name);
148    }
149
150    /** Checks {@link #id this.id} against {@code other.id} for equality. */
151    public boolean equals(final Object other)
152    {
153        if (other == null)              return false;
154        if (! (other instanceof API))   return false;
155        return this.id == ((API) other).id;
156    }
157
158    /** Utilizes {@link #id this.id} as a hash; it is a unique value across the AST Tree. */
159    public int hashCode()
160    { return id; }
161
162    /** Generates a full {@code String} representation of {@code this} instance. */
163    @LinkJavaSource(handle="StringAPI")
164    public String toString()
165    { return StringAPI.get(this); }
166}