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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187

package Torello.JavaDoc;

import Torello.Java.ReadOnly.ReadOnlyList;

/**
 * An interface that may be implemented by a user to execute detailed customizations and
 * modifications to a specific Java-Doc Web Page.  This interface should be implemented by a class
 * that has the same name as the class being processed, but ending with a <B>{@code '$'}</B>.
 * 
 * <BR /><BR />After writing a Java Class which implements this interface, simply copy it to the
 * directory in your file-system that contains the Java CIET/Type - <I>in a sub-directory that has
 * the following name:</I>
 * 
 * <BR /><BR /><B><CODE>upgrade-files/user-processors/MyClassName$.java</CODE></B>
 * 
 * <BR /><BR />Notice that the name of the this particular class ends with a <B>{@code '$'}</B>.
 * The first part of the class' name is being utilized to identify to the Java-Doc Upgrader logic
 * the name of the actual class/CIET/Type that your processor-class is going to process.
 * 
 * <BR /><BR />If you had a class named <B>{@code 'BigNumberCruncher.java'}</B> that was a Java
 * {@code 'class'}, and you wanted to write an HTML-Processor to insert several notices into the
 * JavaDoc Page for the {@code BigNumberCruncher} type - <B><I>you would write a user-processor
 * named {@code 'BigNumberCruncher$.java'}</I></B>.  You would make sure to leave the processor
 * in the following Java Source-Code Directory:
 * 
 * <BR /><BR /><B><CODE>
 * ../com/MyCompany/MyPackage/upgrade-files/user-processors/BigNumberCruncher$.class</CODE></B>
 * 
 * <BR /><BR />The class that you write would implement this interface {@code 'UserProcessorPage'}.
 * During the JavaDoc Upgrader phase of your build, the upgrader logic would invoke your 
 * user-processor and pass it the relevant HTML Data from the Java-Doc HTML Web-Page that had been
 * created by the Java-Doc Tool to your processor.
 */
public interface UserProcessorPage
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Main process dispatch method (and also header/footer dispatch)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Process a complete Java-Doc Generated Web-Page
     * @param jdhf An instance of the fully parsed HTML Page.
     */
    public default void process(JavaDocHTMLFile jdhf) { }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_HEADFOOT_DESC>
     * @param headerFooter <EMBED CLASS='external-html' DATA-FILE-ID=UPP_HEADFOOT_PARAM>
     * @see JavaDocHTMLFile#headerFooter
     */
    public default void processHeaderFooter(HeaderFooterHTML headerFooter) { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Summary Table HTML Hooks
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-ENTITY=Field DATA-ACCESSOR=fieldSummaryTable>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
     * @param fieldSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
     * @see JavaDocHTMLFile#fieldSummaryTable
     */
    public default void processFieldSumm(SummaryTableHTML<Field> fieldSummaries) { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY=Constructor DATA-ACCESSOR=constructorSummaryTable>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
     * @param constructorSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
     * @see JavaDocHTMLFile#constructorSummaryTable
     */
    public default void processCtorSumm(SummaryTableHTML<Constructor> constructorSummaries) { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY=Method DATA-ACCESSOR=methodSummaryTable>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
     * @param methodSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
     * @see JavaDocHTMLFile#methodSummaryTable
     */
    public default void processMethodSumm(SummaryTableHTML<Method> methodSummaries) { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY='Enum-Constant' DATA-ACCESSOR=ecSummaryTable>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
     * 
     * <BR /><BR /><B STYLE='color: red'>NOTE:</B> The vast majority of Java Type's (CIET's) will
     * not have any "Enum Constants" - <I>and would therefore not have an Enum-Constant Summary
     * Table!</I>  Only Java <B STYLE='color: blue'>{@code enum's}</B> may have such constants
     * defined.
     * 
     * @param ecSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
     * @see JavaDocHTMLFile#ecSummaryTable
     */
    public default void processECSumm(SummaryTableHTML<EnumConstant> ecSummaries) { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY='Annotation-Element'>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
     * 
     * <BR /><BR /><B STYLE='color: red'>NOTE:</B> The vast majority of Java Type's (CIET's) will
     * not have any "Annotation Elements" - <I>and would therefore not have an Annotation Element
     * Summary Table!</I>  Only Java <B STYLE='color: blue;'>{@code @annotations}</B> may have such
     * elements defined.
     * 
     * @param oaeSummaries
     *  <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM DATA-ACCESSOR=oaeSummaryTable>
     * 
     * @param raeSummaries
     *  <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM DATA-ACCESSOR=raeSummaryTable>
     * 
     * @see JavaDocHTMLFile#oaeSummaryTable
     * @see JavaDocHTMLFile#raeSummaryTable
     */
    public default void processAESumm(
            SummaryTableHTML<AnnotationElem> oaeSummaries,
            SummaryTableHTML<AnnotationElem> raeSummaries
        )
    { }


    // ********************************************************************************************
    // ********************************************************************************************
    // ReflHTML (Detail) HTML Hooks
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-ENTITY=Field>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
     * @param fieldDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
     */
    public default void processFieldDetails(ReadOnlyList<ReflHTML<Field>> fieldDetails)
    { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY=Constructor>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
     * @param constructorDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
     */
    public default void processCtorDetails(ReadOnlyList<ReflHTML<Constructor>> constructorDetails)
    { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY=Method>
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
     * @param methodDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
     */
    public default void processMethodDetails(ReadOnlyList<ReflHTML<Method>> methodDetails)
    { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY="Enum-Constant">
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Extremely Uncommon:</B>
     * 
     * <BR />The vast majority of Java Type's (CIET's) will not have any "Enum Constants" -
     * <I>and would therefore not have an Annotation Element Detail HTML Block!</I>  Only Java
     * <B STYLE='color: blue;'>{@code enum}</B> may have such constants defined.
     * 
     * @param ecDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
     */
    public default void processECDetails(ReadOnlyList<ReflHTML<EnumConstant>> ecDetails)
    { }

    /**
     * <EMBED CLASS=defs DATA-ENTITY="Annotation-Element">
     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
     *  
     * <BR /><BR /><B CLASS=JDDescLabel>Extremely Uncommon:</B>
     * 
     * The vast majority of Java Type's (CIET's) will not have any "Annotation Elements" - <I>and
     * would therefore not have an Annotation Element Detail HTML Block!</I>  Only Java
     * <B STYLE='color: blue;'>{@code @annotations}</B> may have such elements defined.
     * 
     * @param aeDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
     */
    public default void processAEDetails(ReadOnlyList<ReflHTML<AnnotationElem>> aeDetails)
    { }
}