001package Torello.JavaDoc;
002
003import Torello.Java.ReadOnly.ReadOnlyList;
004
005/**
006 * An interface that may be implemented by a user to execute detailed customizations and
007 * modifications to a specific Java-Doc Web Page.  This interface should be implemented by a class
008 * that has the same name as the class being processed, but ending with a <B>{@code '$'}</B>.
009 * 
010 * <BR /><BR />After writing a Java Class which implements this interface, simply copy it to the
011 * directory in your file-system that contains the Java CIET/Type - <I>in a sub-directory that has
012 * the following name:</I>
013 * 
014 * <BR /><BR /><B><CODE>upgrade-files/user-processors/MyClassName$.java</CODE></B>
015 * 
016 * <BR /><BR />Notice that the name of the this particular class ends with a <B>{@code '$'}</B>.
017 * The first part of the class' name is being utilized to identify to the Java-Doc Upgrader logic
018 * the name of the actual class/CIET/Type that your processor-class is going to process.
019 * 
020 * <BR /><BR />If you had a class named <B>{@code 'BigNumberCruncher.java'}</B> that was a Java
021 * {@code 'class'}, and you wanted to write an HTML-Processor to insert several notices into the
022 * JavaDoc Page for the {@code BigNumberCruncher} type - <B><I>you would write a user-processor
023 * named {@code 'BigNumberCruncher$.java'}</I></B>.  You would make sure to leave the processor
024 * in the following Java Source-Code Directory:
025 * 
026 * <BR /><BR /><B><CODE>
027 * ../com/MyCompany/MyPackage/upgrade-files/user-processors/BigNumberCruncher$.class</CODE></B>
028 * 
029 * <BR /><BR />The class that you write would implement this interface {@code 'UserProcessorPage'}.
030 * During the JavaDoc Upgrader phase of your build, the upgrader logic would invoke your 
031 * user-processor and pass it the relevant HTML Data from the Java-Doc HTML Web-Page that had been
032 * created by the Java-Doc Tool to your processor.
033 */
034public interface UserProcessorPage
035{
036    // ********************************************************************************************
037    // ********************************************************************************************
038    // Main process dispatch method (and also header/footer dispatch)
039    // ********************************************************************************************
040    // ********************************************************************************************
041
042
043    /**
044     * Process a complete Java-Doc Generated Web-Page
045     * @param jdhf An instance of the fully parsed HTML Page.
046     */
047    public default void process(JavaDocHTMLFile jdhf) { }
048
049    /**
050     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_HEADFOOT_DESC>
051     * @param headerFooter <EMBED CLASS='external-html' DATA-FILE-ID=UPP_HEADFOOT_PARAM>
052     * @see JavaDocHTMLFile#headerFooter
053     */
054    public default void processHeaderFooter(HeaderFooterHTML headerFooter) { }
055
056
057    // ********************************************************************************************
058    // ********************************************************************************************
059    // Summary Table HTML Hooks
060    // ********************************************************************************************
061    // ********************************************************************************************
062
063
064    /**
065     * <EMBED CLASS=defs DATA-ENTITY=Field DATA-ACCESSOR=fieldSummaryTable>
066     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
067     * @param fieldSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
068     * @see JavaDocHTMLFile#fieldSummaryTable
069     */
070    public default void processFieldSumm(SummaryTableHTML<Field> fieldSummaries) { }
071
072    /**
073     * <EMBED CLASS=defs DATA-ENTITY=Constructor DATA-ACCESSOR=constructorSummaryTable>
074     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
075     * @param constructorSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
076     * @see JavaDocHTMLFile#constructorSummaryTable
077     */
078    public default void processCtorSumm(SummaryTableHTML<Constructor> constructorSummaries) { }
079
080    /**
081     * <EMBED CLASS=defs DATA-ENTITY=Method DATA-ACCESSOR=methodSummaryTable>
082     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
083     * @param methodSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
084     * @see JavaDocHTMLFile#methodSummaryTable
085     */
086    public default void processMethodSumm(SummaryTableHTML<Method> methodSummaries) { }
087
088    /**
089     * <EMBED CLASS=defs DATA-ENTITY='Enum-Constant' DATA-ACCESSOR=ecSummaryTable>
090     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
091     * 
092     * <BR /><BR /><B STYLE='color: red'>NOTE:</B> The vast majority of Java Type's (CIET's) will
093     * not have any "Enum Constants" - <I>and would therefore not have an Enum-Constant Summary
094     * Table!</I>  Only Java <B STYLE='color: blue'>{@code enum's}</B> may have such constants
095     * defined.
096     * 
097     * @param ecSummaries <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM>
098     * @see JavaDocHTMLFile#ecSummaryTable
099     */
100    public default void processECSumm(SummaryTableHTML<EnumConstant> ecSummaries) { }
101
102    /**
103     * <EMBED CLASS=defs DATA-ENTITY='Annotation-Element'>
104     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_DESC>
105     * 
106     * <BR /><BR /><B STYLE='color: red'>NOTE:</B> The vast majority of Java Type's (CIET's) will
107     * not have any "Annotation Elements" - <I>and would therefore not have an Annotation Element
108     * Summary Table!</I>  Only Java <B STYLE='color: blue;'>{@code @annotations}</B> may have such
109     * elements defined.
110     * 
111     * @param oaeSummaries
112     *  <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM DATA-ACCESSOR=oaeSummaryTable>
113     * 
114     * @param raeSummaries
115     *  <EMBED CLASS='external-html' DATA-FILE-ID=UPP_SUMMARY_PARAM DATA-ACCESSOR=raeSummaryTable>
116     * 
117     * @see JavaDocHTMLFile#oaeSummaryTable
118     * @see JavaDocHTMLFile#raeSummaryTable
119     */
120    public default void processAESumm(
121            SummaryTableHTML<AnnotationElem> oaeSummaries,
122            SummaryTableHTML<AnnotationElem> raeSummaries
123        )
124    { }
125
126
127    // ********************************************************************************************
128    // ********************************************************************************************
129    // ReflHTML (Detail) HTML Hooks
130    // ********************************************************************************************
131    // ********************************************************************************************
132
133
134    /**
135     * <EMBED CLASS=defs DATA-ENTITY=Field>
136     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
137     * @param fieldDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
138     */
139    public default void processFieldDetails(ReadOnlyList<ReflHTML<Field>> fieldDetails)
140    { }
141
142    /**
143     * <EMBED CLASS=defs DATA-ENTITY=Constructor>
144     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
145     * @param constructorDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
146     */
147    public default void processCtorDetails(ReadOnlyList<ReflHTML<Constructor>> constructorDetails)
148    { }
149
150    /**
151     * <EMBED CLASS=defs DATA-ENTITY=Method>
152     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
153     * @param methodDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
154     */
155    public default void processMethodDetails(ReadOnlyList<ReflHTML<Method>> methodDetails)
156    { }
157
158    /**
159     * <EMBED CLASS=defs DATA-ENTITY="Enum-Constant">
160     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
161     * 
162     * <BR /><BR /><B CLASS=JDDescLabel>Extremely Uncommon:</B>
163     * 
164     * <BR />The vast majority of Java Type's (CIET's) will not have any "Enum Constants" -
165     * <I>and would therefore not have an Annotation Element Detail HTML Block!</I>  Only Java
166     * <B STYLE='color: blue;'>{@code enum}</B> may have such constants defined.
167     * 
168     * @param ecDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
169     */
170    public default void processECDetails(ReadOnlyList<ReflHTML<EnumConstant>> ecDetails)
171    { }
172
173    /**
174     * <EMBED CLASS=defs DATA-ENTITY="Annotation-Element">
175     * <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_DESC>
176     *  
177     * <BR /><BR /><B CLASS=JDDescLabel>Extremely Uncommon:</B>
178     * 
179     * The vast majority of Java Type's (CIET's) will not have any "Annotation Elements" - <I>and
180     * would therefore not have an Annotation Element Detail HTML Block!</I>  Only Java
181     * <B STYLE='color: blue;'>{@code @annotations}</B> may have such elements defined.
182     * 
183     * @param aeDetails <EMBED CLASS='external-html' DATA-FILE-ID=UPP_DETAILS_PARAM>
184     */
185    public default void processAEDetails(ReadOnlyList<ReflHTML<AnnotationElem>> aeDetails)
186    { }
187}