Class Stats


  • public class Stats
    extends java.lang.Object
    Stats - Documentation.

    This class keeps a running log of upgrade-statistics.




    • Field Detail

      • packageStats

        public java.util.TreeMap<java.lang.String,​Stats> packageStats
        A Stats instance for each package encountered during the upgrade.
        Code:
        Exact Field Declaration Expression:
        1
        public TreeMap<String, Stats> packageStats = new TreeMap<>();
        
      • embedTagsHT

        public java.util.Hashtable<java.lang.String,​java.lang.Integer> embedTagsHT
        Will keep a record of the use of the <EMBED CLASS="external-html>" HTML Tags.
        Code:
        Exact Field Declaration Expression:
        1
        public Hashtable<String, Integer> embedTagsHT = new Hashtable<>();
        
      • packageEmbedTagsHT

        public java.util.Hashtable<java.lang.String,​java.util.Hashtable<java.lang.String,​java.lang.Integer>> packageEmbedTagsHT
        Will keep a record of the use of <EMBED>-Tags inside each package.
        Code:
        Exact Field Declaration Expression:
        1
        public Hashtable<String, Hashtable<String, Integer>> packageEmbedTagsHT = new Hashtable<>();
        
    • Constructor Detail

      • Stats

        protected Stats()
        Constructor. Initializes all fields in this class.
    • Method Detail

      • numHiLitedDivs

        public int numHiLitedDivs()
        Returns:
        A count of the total number of HiLited HTML <DIV> Elements.
        Code:
        Exact Method Body:
        1
         return numHiLitedDivs;
        
      • numMethods

        public int numMethods()
        Returns:
        A count of the total number of methods found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numMethods;
        
      • numConstructors

        public int numConstructors()
        Returns:
        A count of the total number of constructors found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numConstructors;
        
      • numFields

        public int numFields()
        Returns:
        A count of the total number of fields found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numFields;
        
      • numHiLitedMethods

        public int numHiLitedMethods()
        Returns:
        A count of the total number of method bodies hilited by the upgrader.
        Code:
        Exact Method Body:
        1
         return numHiLitedMethods;
        
      • numHiLitedConstructors

        public int numHiLitedConstructors()
        Returns:
        A count of the total number of constructor bodies hilited by the upgrader.
        Code:
        Exact Method Body:
        1
         return numHiLitedConstructors;
        
      • numHiLitedFields

        public int numHiLitedFields()
        Returns:
        A count of the total number of field declarations hilited by the upgrader.
        Code:
        Exact Method Body:
        1
         return numHiLitedFields;
        
      • numDocumentedMethods

        public int numDocumentedMethods()
        Returns:
        A count of the total number of methods that were documented by Java Doc.
        Code:
        Exact Method Body:
        1
         return numDocumentedMethods;
        
      • numDocumentedConstructors

        public int numDocumentedConstructors()
        Returns:
        A count of the total number of constructors that were documented by Java Doc.
        Code:
        Exact Method Body:
        1
         return numDocumentedConstructors;
        
      • numDocumentedFields

        public int numDocumentedFields()
        Returns:
        A count of the total number of fields that were documented by Java Doc.
        Code:
        Exact Method Body:
        1
         return numDocumentedFields;
        
      • numStaticMethods

        public int numStaticMethods()
        Returns:
        A count of the total number of static methods found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numStaticMethods;
        
      • numStaticFields

        public int numStaticFields()
        Returns:
        A count of the total number of static fields found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numStaticFields;
        
      • numFinalMethods

        public int numFinalMethods()
        Returns:
        A count of the total number of final methods found by the upgrade.
        Code:
        Exact Method Body:
        1
         return numFinalMethods;
        
      • numFinalConstructors

        public int numFinalConstructors()
        Returns:
        A count of the total number of final constructors found by the upgrader.
        Code:
        Exact Method Body:
        1
         return numFinalConstructors;
        
      • numFinalFields

        public int numFinalFields()
        Returns:
        A count of the total number of final fields found by the upgrader.
        Code:
        Exact Method Body:
        1
         return numFinalFields;
        
      • numPublicMethods

        public int numPublicMethods()
        Returns:
        A count of the total number of public methods found by the upgrader.
        Code:
        Exact Method Body:
        1
         return numPublicMethods;
        
      • numPublicConstructors

        public int numPublicConstructors()
        Returns:
        A count of the total number of public constructors found by the upgrader.
        Code:
        Exact Method Body:
        1
         return numPublicConstructors;
        
      • numPublicFields

        public int numPublicFields()
        Returns:
        A count of the total number of public fields found by the upgrader.
        Code:
        Exact Method Body:
        1
         return numPublicFields;
        
      • numProtectedMethods

        public int numProtectedMethods()
        Returns:
        The total number of protected methods found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numProtectedMethods;
        
      • numProtectedConstructors

        public int numProtectedConstructors()
        Returns:
        The total number of protected constructors found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numProtectedConstructors;
        
      • numProtectedFields

        public int numProtectedFields()
        Returns:
        The total number of protected fields found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numProtectedFields;
        
      • numPrivateMethods

        public int numPrivateMethods()
        Returns:
        The total number of private methods found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numPrivateMethods;
        
      • numPrivateConstructors

        public int numPrivateConstructors()
        Returns:
        The total number of private constructors found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numPrivateConstructors;
        
      • numPrivateFields

        public int numPrivateFields()
        Returns:
        The total number of private fields found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numPrivateFields;
        
      • numTransientFields

        public int numTransientFields()
        Returns:
        A count of the total number of transient fields found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numTransientFields;
        
      • numVolatileFields

        public int numVolatileFields()
        Returns:
        A count of the total number of volatile fields found during the upgrade.
        Code:
        Exact Method Body:
        1
         return numVolatileFields;
        
      • registerEmbedMap

        protected void registerEmbedMap​(java.util.Set<java.lang.String> embedTags)
        Initializes the <EMBED> tag stats-table.
        Code:
        Exact Method Body:
        1
         for (String embedTag : embedTags) this.embedTagsHT.put(embedTag, Integer.valueOf(0));
        
      • incrementTag

        protected void incrementTag​(java.lang.String packageName,
                                    java.lang.String embedTag)
        Increments the total-count by 1 for a particular embed-tag inside of an internal Hashtable field that counts how many times each particular FILE-ID embed-tag is used.

        NOTE: Explained below is that there are actually two separate counts maintained. The first DATA-FILE-ID attribute-count is kept for all uses of each ID during the entire upgrade process. The second count is for how many times each FILE-ID attribute is used on a per package basis.
        Parameters:
        packageName - The name of the package for the documentation-page where the particular embedTag was found. This is required because two different counts are maintained by this statistics class:

        1. An aggregate-total count for all uses of each <EMBED CLASS='external-html' ...> found in all documentation-pages produced by this upgrader-build tool.
        2. A total count for all uses of each Embed-Tag in each package of the build.
        embedTag - This is the external-HTML 'Embed Tag' whose count needs to be incremented by one. Embed-Tags are a tool provided to users which allow them to link external-html files into their source-code files by inserting elements such as: <EMBED CLASS='external-html' DATA-FILE-ID=SomeID>
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
        44
        45
        46
        47
        48
         // Increment the Embed-Tag count in the "aggregate-total" Hashtable.
         embedTagsHT.put(embedTag, embedTagsHT.get(embedTag) + 1);
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Now increment the Embed-Tag count for the package-specific count Hashtable.
         // Make sure to used the "Cached" table, if there is one.  Since this is used
         // hundreds of times over and over for the SAME PACKAGE, just save the last
         // used PACKAGE TABLE in a private, internal field.  Just Make sure to CHECK
         // to see that the package-name is, indeed, the same beforehand!.
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         Hashtable<String, Integer> packageEmbedTags = null;
        
         if ((lastUsedPackageName != null) && packageName.equals(lastUsedPackageName))
             packageEmbedTags = lastUsedHT;
         else
         {
             lastUsedPackageName = packageName;
             packageEmbedTags    = this.packageEmbedTagsHT.get(packageName);
                        
             // For the FIRST USE of any particular PACKAGE Embed-Tag HT, the HT must be
             // CREATED FIRST!  Call the Hashtable constructor, and put it in the big map
             // of package Embed-Tag Hashtables.
        
             if (packageEmbedTags == null)
             {
                 packageEmbedTags = new Hashtable<>();
                 this.packageEmbedTagsHT.put(packageName, packageEmbedTags);
             }
        
             lastUsedHT = packageEmbedTags;
         }
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Now we just have to increment the count for the particular Tag-ID by one
         // for the package HT.  
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         // If this is the first use of the specific Embed-Tag in the package-level count, then
         // a Hashtable entry for this Embed-Tag needs to be created.
        
         Integer count = packageEmbedTags.get(embedTag);
        
         if (count == null)  count = 1;
         else                count = count  + 1;
        
         // Update the embedTag count in the package-level HT.
         packageEmbedTags.put(embedTag, count);
        
      • run

        public void run​(CommonParamRecord pr,
                        int numHLM,
                        int numHLC,
                        int numHLF,
                        int numHLD)
        Increment all of the counters / running-totals for a given source-file or documentation page.
        Parameters:
        pr - This contains all of the needed parameters for this method, encapsulated into a single record-class. The list is somewhat lengthy, so this makes the code "look cleaner"
        numHLM - A count of the number of methods that were hilited for a given documentation page.
        numHLC - A count of the number of constructors that were hilited for a given documentation page.
        numHLF - A count of the number of fields that were just hilited for a given documentation page.
        numHLD - A count of the number HTML <DIV CLASS=... elements that were just hilited for the given source-file / documentation-file.
        Code:
        Exact Method Body:
          1
          2
          3
          4
          5
          6
          7
          8
          9
         10
         11
         12
         13
         14
         15
         16
         17
         18
         19
         20
         21
         22
         23
         24
         25
         26
         27
         28
         29
         30
         31
         32
         33
         34
         35
         36
         37
         38
         39
         40
         41
         42
         43
         44
         45
         46
         47
         48
         49
         50
         51
         52
         53
         54
         55
         56
         57
         58
         59
         60
         61
         62
         63
         64
         65
         66
         67
         68
         69
         70
         71
         72
         73
         74
         75
         76
         77
         78
         79
         80
         81
         82
         83
         84
         85
         86
         87
         88
         89
         90
         91
         92
         93
         94
         95
         96
         97
         98
         99
        100
        101
         Method[]        mArr = pr.jscf.getMethods();
         Constructor[]   cArr = pr.jscf.getConstructors();
         Field[]         fArr = pr.jscf.getFields();
        
         if (! packageStats.containsKey(pr.jscf.packageName))
             packageStats.put(pr.jscf.packageName, new Stats());
        
         final Stats ps = packageStats.get(pr.jscf.packageName);
        
         ps.numHiLitedDivs               += numHLD;
         this.numHiLitedDivs             += numHLD;
        
         ps.numMethods                   += mArr.length;
         this.numMethods                 += mArr.length;
         ps.numHiLitedMethods            += numHLM;
         this.numHiLitedMethods          += numHLM;
         ps.numDocumentedMethods         += pr.jdhf.numMethods();
         this.numDocumentedMethods       += pr.jdhf.numMethods();
        
         ps.numConstructors              += cArr.length;
         this.numConstructors            += cArr.length;
         ps.numHiLitedConstructors       += numHLC;
         this.numHiLitedConstructors     += numHLC;
         ps.numDocumentedConstructors    += pr.jdhf.numConstructors();
         this.numDocumentedConstructors  += pr.jdhf.numConstructors();
        
         ps.numFields                    += fArr.length;
         this.numFields                  += fArr.length;
         ps.numHiLitedFields             += numHLF;
         this.numHiLitedFields           += numHLF;
         ps.numDocumentedFields          += pr.jdhf.numFields();
         this.numDocumentedFields        += pr.jdhf.numFields();
        
         for (Method m : mArr) m.getModifiers((String modifier) ->
         {
             switch (modifier)
             {
                 case "static"       :   this.numStaticMethods++;
                                         ps.numStaticMethods++;
                                         break;
                 case "public"       :   this.numPublicMethods++;
                                         ps.numPublicMethods++;
                                         break;
                 case "protected"    :   this.numProtectedMethods++;
                                         ps.numProtectedMethods++;
                                         break;
                 case "private"      :   this.numPrivateMethods++;
                                         ps.numPrivateMethods++;
                                         break;
                 case "final"        :   this.numFinalMethods++;
                                         ps.numFinalMethods++;
                                         break;
             }
         });
        
         for (Constructor c : cArr) c.getModifiers((String modifier) ->
         {
             switch (modifier)
             {
                 case "public"       :   this.numPublicConstructors++;
                                         ps.numPublicConstructors++;
                                         break;
                 case "protected"    :   this.numProtectedConstructors++;
                                         ps.numProtectedConstructors++;
                                         break;
                 case "private"      :   this.numPrivateConstructors++;
                                         ps.numPrivateConstructors++;
                                         break;
                 case "final"        :   this.numFinalConstructors++;
                                         ps.numFinalConstructors++;
                                         break;
             }
         });
        
         for (Field f : fArr) f.getModifiers((String modifier) ->
         {
             switch (modifier)
             {
                 case "static"       :   this.numStaticFields++;
                                         ps.numStaticFields++;
                                         break;
                 case "public"       :   this.numPublicFields++;
                                         ps.numPublicFields++;
                                         break;
                 case "protected"    :   this.numProtectedFields++;
                                         ps.numProtectedFields++;
                                         break;
                 case "private"      :   this.numPrivateFields++;
                                         ps.numPrivateFields++;
                                         break;
                 case "final"        :   this.numFinalFields++;
                                         ps.numFinalFields++;
                                         break;
                 case "transient"    :   this.numTransientFields++;
                                         ps.numTransientFields++;
                                         break;
                 case "volatile"     :   this.numVolatileFields++;
                                         ps.numVolatileFields++;
                                         break;
             }
         });
        
      • toString

        public java.lang.String toString()
        Generates a String that enapsulates all of the counters / running-totals inside this data statistic class.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A String representation of this class.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
         StringBuilder sb = new StringBuilder();
        
         for (String packageName : packageStats.keySet())
             sb.append(
                 "Stats for Package: [" + C.BCYAN + packageName + C.RESET + "]:\n\n" +
                 StrIndent.indent(toStringINTERNAL(packageStats.get(packageName)), 4) + '\n'
             );
        
         sb.append("UPGADE / BUILD TOTAL:\n\n" + toStringINTERNAL(this));
        
         return sb.toString();
        
      • toStringEmbedTagCount

        public java.lang.String toStringEmbedTagCount​
                    (java.util.Map<java.lang.String,​java.lang.String> embedTagIDMap)
        
        Produces a report of how many each times the 'Embed Tags' were used in the documentation pages. The Embed-Tags are externally linked HTML files that may be inserted into Java Doc Documentation pages by using the HTML '<EMBED>' element.
        Parameters:
        embedTagIDMap - This must be passed so that the file-names themselves can be included in the report that is generated by this class.
        Returns:
        A (very long) Java String which contains all of the 'count' information about how many times each FILE-ID (external HTML files) was used during the upgrade process. The tables printed to the output String list the count for each <EMBED CLASS='external-html' DATA-FILE-ID=...> as an aggregate total for the entire build, and how many times the Tag ID's were used in each of the packages within the build.
        See Also:
        Upgrade.embedTagIDTable, Upgrade.setEmbedTagsMap​(Map)
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
         StringBuilder sb = new StringBuilder();
        
         for (String packageName : packageEmbedTagsHT.keySet())
         {
             sb.append(
                 "Embed Tag FILE-ID Attributes for Package: " +
                 C.BCYAN + packageName + C.RESET + '\n'
             );
        
             toStringHT_INTERNAL(packageEmbedTagsHT.get(packageName), embedTagIDMap, sb);
         }
        
         sb.append(C.BCYAN + "Complete Upgrade Totals:\n" + C.RESET);
        
         String zeroCountStr = toStringHT_INTERNAL(embedTagsHT, embedTagIDMap, sb);
        
         if (zeroCountStr.length() > 0)
             sb.append(
                 C.BCYAN + "Unused Embed Tags:\n" + C.RESET +
                 zeroCountStr + '\n'
             );
        
         return sb.toString();