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

package Torello.Java.Build;

import java.io.IOException;

/**
 * The Function-Pointer Interface used with the Stage-3 Upgrader "Pre" and "Post" Processors.
 * 
 * <BR /><BR />This is a feature that is used internally (very heavily) by the Java-HTML 
 * {@code '.jar'}-Library.  There are quite a number of features that are used by the current
 * manifestation of the Java-Doc Upgrader Tool, which haven't documented or formalized to the
 * point where they may be included within the actual Upgrader-Tool itself, yet.
 * 
 * <BR /><BR >Because features which aren't full-blown API calls (not yet anyway) are stil being
 * utilized to upgrade Java-Doc {@code '.html'}-Files, they are instead inserted into these
 * "Pre-Upgrader" and "Post-Upgrader" Scripts, as a part of the Build-Tool's processes.
 * 
 * <BR /><BR />If it is necessary, a script may be created using any one of Java's available 
 * {@code FunctionalInterface} or Lambda-Syntax mechanisms.  Once created, assigning the reference
 * of your script to the class {@link Config} Configuration-Fields:
 * {@link Config#preUpgraderScript} and / or {@link Config#postUpgraderScript} is how to ensure
 * that these scripts will be run during your build's using this Build-Tool.
 * 
 * <BR /><BR />Unlike the documentation for class {@link JarInclude}, providing the Java-HTML 
 * native Build-Code as an example, inline right here, of a "Pre Upgrader Script" or a "Post 
 * Upgrader Script" is patently impossible.  The scripts used by this library are extremely 
 * long and do a lot of extra-cleanup routines which just wouldn't make a lot of sense.  
 * 
 * <BR /><BR />Suffice it to say, if there are "other things" you would like the build to do
 * besides just the things listed in the 8 Build-Stages / Build-Steps offered by this tool, you
 * may create a script here, and assign it to the class {@link Config} public field's
 * {@link Config#preUpgraderScript} and / or {@link Config#postUpgraderScript} to see that your
 * scripts are run.
 * 
 * @see Config#preUpgraderScript
 * @see Config#postUpgraderScript
 * @see Config#createBuilder(String[])
 * @see RunBuild#run(BuilderRecord)
 */
@FunctionalInterface
public interface UpgradeProcessor extends java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDFI>  */
    public static final long serialVersionUID = 1;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=FUNC_INTER_METH>
     *
     * <BR /><BR />May be used to implement any kind of pre-processing or post-processing during
     * the "Stage 3" - Java-Doc Upgrader Stage.  Pass any Lambda-Expression or Function-Pointer to
     * to the {@link BuilderRecord} instance using the {@link Config} Configuration-Class fields: 
     * {@link Config#preUpgraderScript preUpgraderScript} and
     * {@link Config#postUpgraderScript postUpgraderScript}
     * 
     * @param brec Provided to this method by the Build-Mechanism for convienence.  This class
     * contains many public constant-fields.
     * 
     * @param logOutput May be used to print any output or log data
     * 
     * @throws IOException {@code IOException} is very common during the build, and if it is thrown
     * it will printed
     */
    public void accept(BuilderRecord brec, StringBuilder logOutput) throws IOException;
}