001package Torello.Java.Build;
002
003import java.io.IOException;
004
005/**
006 * The Function-Pointer Interface used with the Stage-3 Upgrader "Pre" and "Post" Processors.
007 * 
008 * <BR /><BR />This is a feature that is used internally (very heavily) by the Java-HTML 
009 * {@code '.jar'}-Library.  There are quite a number of features that are used by the current
010 * manifestation of the Java-Doc Upgrader Tool, which haven't documented or formalized to the
011 * point where they may be included within the actual Upgrader-Tool itself, yet.
012 * 
013 * <BR /><BR >Because features which aren't full-blown API calls (not yet anyway) are stil being
014 * utilized to upgrade Java-Doc {@code '.html'}-Files, they are instead inserted into these
015 * "Pre-Upgrader" and "Post-Upgrader" Scripts, as a part of the Build-Tool's processes.
016 * 
017 * <BR /><BR />If it is necessary, a script may be created using any one of Java's available 
018 * {@code FunctionalInterface} or Lambda-Syntax mechanisms.  Once created, assigning the reference
019 * of your script to the class {@link Config} Configuration-Fields:
020 * {@link Config#preUpgraderScript} and / or {@link Config#postUpgraderScript} is how to ensure
021 * that these scripts will be run during your build's using this Build-Tool.
022 * 
023 * <BR /><BR />Unlike the documentation for class {@link JarInclude}, providing the Java-HTML 
024 * native Build-Code as an example, inline right here, of a "Pre Upgrader Script" or a "Post 
025 * Upgrader Script" is patently impossible.  The scripts used by this library are extremely 
026 * long and do a lot of extra-cleanup routines which just wouldn't make a lot of sense.  
027 * 
028 * <BR /><BR />Suffice it to say, if there are "other things" you would like the build to do
029 * besides just the things listed in the 8 Build-Stages / Build-Steps offered by this tool, you
030 * may create a script here, and assign it to the class {@link Config} public field's
031 * {@link Config#preUpgraderScript} and / or {@link Config#postUpgraderScript} to see that your
032 * scripts are run.
033 * 
034 * @see Config#preUpgraderScript
035 * @see Config#postUpgraderScript
036 * @see Config#createBuilder(String[])
037 * @see RunBuild#run(BuilderRecord)
038 */
039@FunctionalInterface
040public interface UpgradeProcessor extends java.io.Serializable
041{
042    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDFI>  */
043    public static final long serialVersionUID = 1;
044
045    /**
046     * <EMBED CLASS='external-html' DATA-FILE-ID=FUNC_INTER_METH>
047     *
048     * <BR /><BR />May be used to implement any kind of pre-processing or post-processing during
049     * the "Stage 3" - Java-Doc Upgrader Stage.  Pass any Lambda-Expression or Function-Pointer to
050     * to the {@link BuilderRecord} instance using the {@link Config} Configuration-Class fields: 
051     * {@link Config#preUpgraderScript preUpgraderScript} and
052     * {@link Config#postUpgraderScript postUpgraderScript}
053     * 
054     * @param brec Provided to this method by the Build-Mechanism for convienence.  This class
055     * contains many public constant-fields.
056     * 
057     * @param logOutput May be used to print any output or log data
058     * 
059     * @throws IOException {@code IOException} is very common during the build, and if it is thrown
060     * it will printed
061     */
062    public void accept(BuilderRecord brec, StringBuilder logOutput) throws IOException;
063}