Class RearrangeEntitySummaries

  • public class RearrangeEntitySummaries
    extends java.lang.Object
    Process Java Doc Web-Page: Organizes Entity items and generates sub-section labels for Java Doc Summary Sections by way of user-provided sorters and title-categories

    JD-Upgrader Internally Used Class, Methods are Package-Private

    There is largely no use for these methods outside of the Java Doc Upgrader Application. Little Java-Doc Style Documentation will be provided here. The code itself (and code comments) may be viewed using the HiLited Source Code Button in the Navigation-Bar, or the URL-Link that is lower on this page.

    To see how this Upgrader Application class works, click the HiLited Source Code Link above.

    This class helps the rearranging of entity summary sections on a JavaDoc Web-Page. There are five possible entity-summaries that could be arranged on a Java Doc Web-Page:

    • Method Summary Section
    • Field Summary Section
    • Constructor Summary Section
    • Enum Constant Summary Section
    • Inner Class Summary Section

    Each of these summaries are, generally, a Table of Contents for the 'entities' in a Java Source-File. When sorting the table of contents, grouping items that are either related, or perform similar functions generally makes it much easier for a new user to understand their purpose. Furthermore, these sorters allow for a Title-Bar that stands out quite well, thereby eliminating some of the confusion that can stem from the original Java Doc auto-arranged summary lists.

    There are also "Annotation Element Sections" on Java Doc Web-Pages (but only for @interface / annotations); however, since the number of elements inside of an annotation is nearly always very low, and because annotations aren't as common as the other Java Types (Classes, Interfaces & Enum's), it is not possible to write an "Annotation Element Summary Sorter."

    Writing a summary sorter for a class - is easy, however - some amount of tedium is occasionally necessary. Note that each summary section (Method Summary, Field Summary, etc...) needs it's own sorter. The following two links will provide an example directly from this Java HTML JAR Library. The most recent set of sorters for the package Torello.HTML and for Torello.Java are fully listed in these HiLited Source Code Files, below:

    All that is entailed when writing a Summary-Sorter File, is the creation of a '.java' source-code file in the 'upgrade-files/config-classes/' sub-directory. That sub-directory should be located inside the source-code Package-Directory of whatever Java Package that contains the CIET/Types which you would like sorted by the Java Doc Upgrader. The above listed files, which are the exact Summary-Sorters that were used to compile the current version of Java HTML (the one you are reading, right now), were placed in the directories listed here:

    • Torello/HTML/upgrade-files/config-classes/
    • Torello/Java/upgrade-files/config-classes/

    These files should either have no 'package' statement at all, or they should be given the package-name consistent with the package they are sorting. The links above have the necessary Java-Source to make clear exactly how to write a Summary-Sorter File. The table below explains what each of the sorter-name suffixes that are needed to communicate to this upgrader tool what to what entity (Methods, Fields, Constructors, etc...) any particular should be applied.

    NOTE: Though rarely used, the '$' (dollar-sign) is a valid character to be used inside Java Identifiers. Note that either of the two options may be used when creating a name for a sorter - $M$Sorter or $Method$Sorter
    Entity Being CategorizedSorter & Sections Name-Suffix
    Categorize Methods Title Bars: $M$Sections, $Method$Sections (either suffix will suffice)

    Sorter Methods: $M$Sorter, $Method$Sorter
    Categorize Fields Title Bars: $F$Sections, $Field$Sections

    Sorter Methods: $F$Sorter, $Field$Sorter
    Categorize Constructors Title Bars: $C$Sections, $Constructor$Sections

    Sorter Methods: $C$Sorter, $Constructor$Sorter
    Categorize Enum-Constants
    (Java 'enum' Types only)
    Title Bars: $EC$Sections, $EnumConstant$Sections

    Sorter Methods:: $EC$Sorter, $EnumConstant$Sorter
    Categorize Inner-Classes Title Bars: $IC$Sections, $InnerClass$Sections

    Sorter Methods: $IC$Sorter, $InnerClass$Sorter

    FINALLY: Notice that the prefix of a Sorter-Method, and also the prefix of Category-Section String[] Array is the exact name of the CIET/Type that contains the Summary-Section being categorized and sorted. In order to create a Field Sorter for class MyClass1, you would need to build a String[] Array, and a Field sorter method as below:

    • public static String[] MyClass1$F$Sections = { "Title Text 1", "Title Text 2", ... };
    • public static int MyClass1$F$Sorter (Field f) { ... }

    For a more visual explanation of what the 'Summary Items' are, please review the following before and after screen clips:

Stateless Class: This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member field. It is very similar to the Java-Bean @Stateless Annotation.
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 4 Method(s), 4 declared static
  • 6 Field(s), 6 declared static, 6 declared final

    • Method Summary

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait