Class AbstractDescriptor

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<AbstractDescriptor>
    Direct Known Subclasses:
    CommandDescriptor, NestedDescriptor
    public abstract class AbstractDescriptor
extends java.lang.Object
implements java.lang.Comparable<AbstractDescriptor>, java.io.Serializable
    Serves as the parent class for both NestedDescriptor and CommandDescriptor. These two concrete subclass descriptors may be used to construct a 'builder' instance. Builders allow a programmer to assign values to a class' fields (NestedDescriptor) or values to the parameters of a command / method (CommandDescriptor).

    Builder Design Pattern
    🤷 There are quite a number of types / classes in the CDP which have a very long list of fields. There are also several methods in the domain classes which accept a very long parameter list. Since many, many of the class fields and method parameters are declared 'optional' by CDP, in order to use the constructor for these classes, or invoke these methods, he winds up typing very long lists of 'nulls'.

    👍 Using a 'builder' to construct classes with large numbers of fields, or invoke methods with a lengthy parameter list, allows the programmer to only pass the necessary values to these fields & parameters, rather than a very long and sparse list of values, largely replete with many 'nulls'

    📎 The information returned by this class should be identical to that which would be generated by the classes in java.lang.reflect.*.

    🔥 Using a precalculated 'descriptor' class is an order of magnitude easier to read, and likely programatically faster than, using actual Java Reflection
    See Also:
    Serialized Form


    • Method Summary

       
      Retrieve an 'index' (location) within the RO Lists of this Descriptor Instance
      Modifier and Type Method
      int nameToIndex​(String name)
       
      Methods: interface java.lang.Comparable
      Modifier and Type Method
      int compareTo​(AbstractDescriptor that)
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      int hashCode()
      String toString()

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1L;

      • name

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String name
        This is simply the name of the type or command represented by this descriptor.
        Code:
        Exact Field Declaration Expression:
         public final String name;

      • domain

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final Domains domain
        The Web Browser "Domain" in which the class / type (or command) represented by this descriptor exists.

        📌 Inside of a Web Browser's Source Code, a "Domain" is essentially the same as a Java Package, and basically means just that.

        Browser Automation Design
        Java-HTML's Browser Package implements a Web-Browser's Domains as a single class, rather than an entire package. This is because the Java CDP Implementation does not have any actual browser code; but rather is nothing more than a series of wrappers and datagram envelopes which communicate with the actual source code inside of the browser.

        👉 As a result, the methods & types of an entire Browser 'Domain' fit inside of a single Java Class, rather than occupying an entire Java Package. (Browser Domain 'CSS', for instance, is wholly placed into a single Java Class: 'CSS')
        Code:
        Exact Field Declaration Expression:
         public final Domains domain;

      • names

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> names
        Provides the names of the CDP properties or command parameters represented by this descriptor. For a NestedDescriptor, these names correspond to the fields of a nested data type. For a CommandDescriptor, these names correspond to the parameters accepted by a domain command.

        Specs as an AST
        💡 Within the Java-HTML Browser AST Parsing package (Torello.Browser.JsonAST), both concepts are actually represented by AST PPR's nodes: named JSON values with a declared CDP type, optional status, and experimental status.

        📌 This list is a "Parallel List", meaning its length should be equal to the other lists which reside in this class, and that the values contained by the lists all correspond to the same class-field or method-parameter.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<String> names;

      • types

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.Byte> types
        The bytes stored in this class are identical to the specified constants in class CDPTypes.

        📌 This list is a "Parallel List", meaning its length should be equal to the other lists which reside in this class, and that the values contained by the lists all correspond to the same class-field or method-parameter.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<Byte> types;

      • optionals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.Boolean> optionals
        Specifies which CDP properties or command parameters have been designated as optional. Optional values are permitted to be absent from the JsonObject which defines them.

        📌 This list is a "Parallel List", meaning its length should be equal to the other lists which reside in this class, and that the values contained by the lists all correspond to the same class-field or method-parameter.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<Boolean> optionals;

      • experimentals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.Boolean> experimentals
        Google's Chrome DevTools Protocol occasionally designates certain properties or command parameters as "experimental." If the element described by a particular list index has been marked experimental, then the same index in this list will be assigned 'TRUE'.

        📌 This list is a "Parallel List", meaning its length should be equal to the other lists which reside in this class, and that the values contained by the lists all correspond to the same class-field or method-parameter.
        Code:
        Exact Field Declaration Expression:
         public final ReadOnlyList<Boolean> experimentals;

      • size

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final int size
        The number of CDP properties or command parameters described by this descriptor-instance.

        📌 This number will be equal to the 'size()' of each of the lists in this class.
        Code:
        Exact Field Declaration Expression:
         public final int size;

    • Method Detail

      • nameToIndex

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int nameToIndex​(java.lang.String name)
        Retrieves the array index associated with the CDP property or command parameter whose name is 'fieldName'.

        Remember that the lists in this class are parallel lists! In order to find the type of a field name, look up the array index for a field's name, and then look at the same location in the types list to find that particular field's type!

        It isn't mission critical to use this method, and one may simply refer to the Java-Doc Documentation to find the exact "array index" of a particular field. It isn't rocket science at all! The first field in the class will have an array index of '0', and the second will have an array index of '1' - and so on and so forth!
        Parameters:
        name - Must be a java.lang.String that is identicial to one of the field names (Java would call these "identifiers") within this class. If the provided name doen't correspond to any field in this class, then UnknownPropertyException throws.
        Returns:
        The 'number' associated with the field named by 'fieldName'. If a type or event type has 4 fields, then this method would return a value between 0 and 3.
        Throws:
        UnknownPropertyException - If the User-Provided 'feildName' isn't found.
        Code:
        Exact Method Body:
         final int ret = names.indexOf(name);

 if (ret == -1) throw new UnknownPropertyException(name);

 return ret;

      • compareTo

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final int compareTo​(AbstractDescriptor that)
        Compares this descriptor to another descriptor for ordering purposes.

        Ordering is performed first by domain, and then by name.

        👉 This method is declared final, meaning that it may not be modified by the concrete subclasses of this abstract parent.
        Specified by:
        compareTo in interface java.lang.Comparable<AbstractDescriptor>
        Parameters:
        that - The descriptor instance being compared to this instance.
        Returns:
        A negative integer, zero, or a positive integer if this descriptor is less than, equal to, or greater than the specified descriptor.
        Code:
        Exact Method Body:
         final int ret = this.domain.compareTo(that.domain);

 if (ret != 0)   return ret;
 else            return this.name.compareTo(that.name);

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Generates an insightful String representation of 'this' instance.

        ⚠️ Since this class is an abstract class, with concrete sub-classes doing the actual work, the output generated by this particular 'toString()' method is not intended for use by a programmer, but rather used by the sub-classes to simplify their own 'toString()' methods.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A Java String
        See Also:
        NestedDescriptor.toString(), CommandDescriptor.toString()
        Code:
        Exact Method Body:
         // toCSV(Iterable<T> i, Function<? super T,​String> toString, boolean printNulls,
 //      Integer maxLength)
 // 
 // Conversion Map: Byte Constant into its Constant-Name, as a String
 // public static final ReadOnlyMap<java.lang.Byte,​java.lang.String> names

 final String types = StrCSV.toCSV(this.types, CDPTypes.names::get, true, null);

 // toCSV(Iterable<?> i, boolean trim, boolean printNulls, Integer maxLength)
 final String names          = StrCSV.toCSV(this.names, true, true, null);
 final String optionals      = StrCSV.toCSV(this.optionals, true, true, null);
 final String experimentals  = StrCSV.toCSV(this.experimentals, true, true, null);


 // wrapToIndentationPlus​(String s, int firstLineLen, int lineLen, int extraSpaces)
 // 
 // "Experimentals: ".length()   ==> 15
 // I4.length()                  ==> 4
 // 
 // firstLineLen = 80 - 15 - 4   ==> 61
 // lineLen      = 80 - 4        ==> 76
 // 
 // This is just here to make the code below more readable.  This is a "Cute Little Lambda"
 // a.k.a. a Java Function Pointer.

 final Function<String, String> print = (String s) ->
     StrPrint.wrapToIndentationPlus(s, 61, 76, 4);


 // Remember, this class 'AbstractDescriptor' is an abstract class, and this 'toString' 
 // method will only ever be invoked by the concrete subclasses 'toString'.  Those 
 // subclasses will "wrap" the output from this toString in curly-braces, and some nicer
 // looking labels.

 return
     I4 + "Domain: " + this.domain + '\n' +
     I4 + "Name:   " + this.name + '\n' +
     I4 + "size:   " + this.size + '\n' +
     '\n' +
     I4 + "Names:         " + print.apply(names)  + '\n' +
     I4 + "Types:         " + print.apply(types) + '\n' +
     I4 + "Optionals:     " + print.apply(optionals) + '\n' +
     I4 + "Experimentals: " + print.apply(experimentals);

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean equals​(java.lang.Object o)
        Check whether 'this' instance is equal to input parameter 'o'

        📎 This 'equals' method merely checks the values assigned to fields name and domain for equality. Each type and each command within CDP has its own, singleton, descriptor instance. These two fields can uniquely identify any descriptor instance in CDP.

        👉 This method is declared final, meaning that it may not be modified by the concrete subclasses of this abstract parent.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - Any Java Object. Only an instance of AbstractDescriptor that is identical to 'this' instance will return 'true'.
        Returns:
        TRUE if and only if 'this' is equal to 'o'.
        See Also:
        name, domain
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (o == null || getClass() != o.getClass()) return false;

 final AbstractDescriptor that = (AbstractDescriptor) o;

 return
         this.name.equals(that.name)
     &&  this.domain.equals(that.domain);

      • hashCode

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public final int hashCode()
        Generates a hashcode for this instance. This method utilizes the same fields for its hashing computation as the fields used by the equals(Object) method.

        👉 This method is declared final, meaning that it may not be modified by the concrete subclasses of this abstract parent.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A Java int
        See Also:
        equals(Object)
        Code:
        Exact Method Body:
         return this.name.hashCode() + 31 * this.domain.hashCode();