Class EmbedTag


  • public class EmbedTag
    extends java.lang.Object
    Process Java Doc Web-Page: Replace <EMBED CLASS='external-html'> tags in code-comments with their respective External-HTML Files.

    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 is capable of finding and replacing specified HTML "EMBED" Elements (<EMBED>) and replacing them with externally-located HTML pages. It does this by requiring that the tag have a class='external-html' attribute and also an inner-tag that specifies an ID for that piece of HTML. This is in the form of DATA-FILE-ID='SOME-ID-TOKEN'. When the Upgrader finds an HTML Embed element in the page whose class is external-html, it will search for this 'Data-File-ID' attribute in the element, and then use a user-provided lookup-table, or lambda function, to insert that HTML into the class.

    VALUE ADDED: This can allow programmers to type longer descriptions - particularly for elements such as the top-level class descriptions - in separate files from their source-code, if they so chose. A separate directory for longer HTML explanations for a class functionality or description can contain '.html' files that may automatically imported into their javadoc's using the HTML Embed Element and this tool.

    Hopefully, this simple example of how to insert an HTML 'EMBED' Element into a Java-Doc Documentation Comment Page will make it easier to add External HTML Files directly into code documentation. Please notice the 'Attribute' in the example named 'DATA-FILE-ID'. This is a token that must be defined in the Embed Tags Definitions This definitions list is simply a list of Tokens and HTML FileNames - separated by white-space, one-per-line that has been passed or registered with the Upgrader. See the Upgrader's method setEmbedTagsMap(...) for more details.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    /**
     * The purpose of this method is to save every person on earth.  Please see the descriptive table included below:
     * 
     * <EMBED class='external-html' DATA-FILE-ID='IDTOKEN'>
     *
     * @returns An explanation of steps that have already been taken to save the world
     * @throws SleepingInException If the alarm clock does not go off, this exception will throw.
     */
    public static String saveTheWorld()
    {
        ...
    }
    


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
  • 8 Method(s), 8 declared static
  • 8 Field(s), 8 declared static, 8 declared final


    • Field Detail

      • LOCAL_EMBED_TAGS_FILENAME

        🡇    
        public static final java.lang.String LOCAL_EMBED_TAGS_FILENAME
        The list of Embedded HTML Files may be stored on a per-package basis by saving all locally imported '.html' files in sub-directory of the package-directory where your source-code is saved.

        The directory for saving locally imported '.html' is:
        "upgrade-files/external-html/"

        The name of the Java 'Properties' File for saving the ID Map File is:
        "external-html-ids.properties"
        Code:
        Exact Field Declaration Expression:
        public static final String LOCAL_EMBED_TAGS_FILENAME =
                "upgrade-files" + Upgrade.FSEP + "external-html-ids.properties";
        
      • EMBED_TAG_PARAMETER_REGEX

        🡅  🡇    
        public static final java.util.regex.Pattern EMBED_TAG_PARAMETER_REGEX
        The Embed Tag Parameter-Variable Regular Expression (Used for Parse). Embed-Tag Parameters allow a user to use variables inside the external HTMl files they insert. If one external HTML file is going to be used over and over, with only one or two words changing in each use, then a parameter may be inserted into that file, and it will be automatically replaced when the HTML is inserted into the Java Doc Page.

        An Embed-Tag Parameter name must match this regular-expression. If you cannot read @@\w[\w\d]+, it just says any combination of letters (upper or lower-case), number, and the '_' (underscore) character. This string must be preceeded by two '@' signs, in a row. Also, the parameter name must start with a letter or underscore

        An example of a valid Embed-Tag Parameter Name would be '@@PARAM1' or maybe '@@1_TYPE_VAL'
        Code:
        Exact Field Declaration Expression:
        public static final Pattern EMBED_TAG_PARAMETER_REGEX = Pattern.compile("(@@\\w[\\w\\d]*)");
        
      • EMBED_TAG_PARAMETER_PRED

        🡅    
        public static final java.util.function.Predicate<java.lang.String> EMBED_TAG_PARAMETER_PRED
        Code:
        Exact Field Declaration Expression:
        public static final Predicate<String> EMBED_TAG_PARAMETER_PRED =
                EMBED_TAG_PARAMETER_REGEX.asPredicate();