Class JJDocMojo

java.lang.Object
org.apache.maven.plugin.AbstractMojo
org.apache.maven.reporting.AbstractMavenReport
org.codehaus.mojo.javacc.JJDocMojo
All Implemented Interfaces:
org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo, org.apache.maven.reporting.MavenMultiPageReport, org.apache.maven.reporting.MavenReport
@Mojo(name="jjdoc") @Execute(phase=GENERATE_SOURCES) public class JJDocMojo extends org.apache.maven.reporting.AbstractMavenReport
JJDoc takes a JavaCC parser specification and produces documentation for the BNF grammar. This mojo will search the source directory for all *.jj files and run JJDoc once for each file it finds. Each of these output files, along with an index.html file will be placed in the site directory (target/site/jjdoc), and a link will be created in the "Project Reports" menu of the generated site.
Since:
2.3
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    JJDocMojo.GrammarInfoComparator
    Compares grammar infos using their relative grammar file paths as the sort key.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private Boolean
    bnf
    A flag whether to generate a plain text document with the unformatted BNF.
    private String
    cssHref
    The hypertext reference to an optional CSS file for the generated HTML documents.
    private File
    defaultGrammarDirectoryJavaCC
    The default source directory for hand-crafted grammar files.
    private File
    defaultGrammarDirectoryJJTree
    The default source directory for grammar files generated by JJTree.
    private File
    defaultGrammarDirectoryJTB
    The default source directory for grammar files generated by JTB.
    private String
    grammarEncoding
    The file encoding to use for reading the grammar files.
    private String
    jjdocDirectory
    The relative path of the JJDoc reports in the output directory.
    private boolean
    oneTable
    This option controls the structure of the generated HTML output.
    private File
    outputDirectory
    The destination directory where JJDoc saves the generated documentation files.
    private File[]
    sourceDirectories
    The directories where the JavaCC grammar files (*.jj) are located.
    private Boolean
    text
    A flag to specify the output format for the generated documentation.

    Fields inherited from class org.apache.maven.reporting.AbstractMavenReport

    locale, mojoExecution, outputFormat, outputTimestamp, project, reactorProjects, remoteProjectRepositories, repoSession, siteDirectory, siteRenderer, siteTool

    Fields inherited from interface org.apache.maven.reporting.MavenReport

    CATEGORY_PROJECT_INFORMATION, CATEGORY_PROJECT_REPORTS, ROLE

    Fields inherited from interface org.apache.maven.plugin.Mojo

    ROLE

  • Constructor Summary

    Constructors
    Constructor
    Description
    JJDocMojo()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canGenerateReport()
     
    private void
    createReportFooter(org.apache.maven.doxia.sink.Sink sink)
    Create the HTML footer for the report page.
    private void
    createReportHeader(ResourceBundle bundle, org.apache.maven.doxia.sink.Sink sink)
    Create the header and title for the HTML report page.
    private void
    createReportLink(org.apache.maven.doxia.sink.Sink sink, File sourceDirectory, File grammarFile, String linkPath)
    Create a table row containing a link to the JJDoc report for a grammar file.
    void
    executeReport(Locale locale)
    Run the actual report.
    void
    generate(org.apache.maven.doxia.sink.Sink sink, Locale locale)
     
    private ResourceBundle
    getBundle(Locale locale)
    Get the resource bundle for the report text.
    String
    getDescription(Locale locale)
     
    private File
    getJJDocOutputDirectory()
    Get the output directory of the JJDoc files, i.e.
    String
    getName(Locale locale)
     
    protected String
    getOutputDirectory()
    Get the output directory of the report if run directly from the command line.
    private String
    getOutputFileExtension()
    The JJDoc output file will have a .html or .txt extension depending on the value of the parameters text and bnf.
    String
    getOutputName()
     
    private File[]
    getSourceDirectories()
    Get the source directories that should be scanned for grammar files.
    private JJDoc
    newJJDoc()
    Creates a new facade to invoke JJDoc.
    private GrammarInfo[]
    scanForGrammars(File sourceDirectory)
    Searches the specified source directory to find grammar files that can be documented.

    Methods inherited from class org.apache.maven.reporting.AbstractMavenReport

    closeReport, constructXrefLocation, execute, generate, getCategoryName, getInputEncoding, getLocale, getOutputEncoding, getProject, getReportOutputDirectory, getSink, getSinkFactory, getSiteRenderer, getXrefLocation, isExternalReport, setReportOutputDirectory

    Methods inherited from class org.apache.maven.plugin.AbstractMojo

    getLog, getPluginContext, setLog, setPluginContext

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.apache.maven.reporting.MavenReport

    getOutputPath

  • Field Details

    • sourceDirectories

      @Parameter private File[] sourceDirectories
      The directories where the JavaCC grammar files (*.jj) are located. By default, the directories ${basedir}/src/main/javacc, ${project.build.directory}/generated-sources/jjtree and ${project.build.directory}/generated-sources/jtb are scanned for grammar files to document.

    • defaultGrammarDirectoryJavaCC

      @Parameter(defaultValue="${basedir}/src/main/javacc") private File defaultGrammarDirectoryJavaCC
      The default source directory for hand-crafted grammar files.

    • defaultGrammarDirectoryJJTree

      @Parameter(defaultValue="${project.build.directory}/generated-sources/jjtree") private File defaultGrammarDirectoryJJTree
      The default source directory for grammar files generated by JJTree.

    • defaultGrammarDirectoryJTB

      @Parameter(defaultValue="${project.build.directory}/generated-sources/jtb") private File defaultGrammarDirectoryJTB
      The default source directory for grammar files generated by JTB.

    • jjdocDirectory

      @Parameter(defaultValue="jjdoc") private String jjdocDirectory
      The relative path of the JJDoc reports in the output directory. This path will be appended to the output directory.

    • outputDirectory

      @Parameter(defaultValue="${project.reporting.outputDirectory}", property="javacc.outputDirectory") private File outputDirectory
      The destination directory where JJDoc saves the generated documentation files. Note that this parameter is only relevant if the goal is run from the command line or from the default build lifecycle. If the goal is run indirectly as part of a site generation, the output directory configured in the Maven Site Plugin is used instead.

    • grammarEncoding

      @Parameter(defaultValue="${project.build.sourceEncoding}", property="javacc.grammarEncoding") private String grammarEncoding
      The file encoding to use for reading the grammar files.
      Since:
      2.6

    • cssHref

      @Parameter(property="javacc.cssHref") private String cssHref
      The hypertext reference to an optional CSS file for the generated HTML documents. If specified, this CSS file will be included via a <link> element in the HTML documents. Otherwise, the default style will be used.
      Since:
      2.5

    • text

      @Parameter(property="javacc.text") private Boolean text
      A flag to specify the output format for the generated documentation. If set to true, JJDoc will generate a plain text description of the BNF. Some formatting is done via tab characters, but the intention is to leave it as plain as possible. Specifying false causes JJDoc to generate a hyperlinked HTML document unless the parameter bnf has been set to true. Default value is false.

    • bnf

      @Parameter(property="javacc.bnf") private Boolean bnf
      A flag whether to generate a plain text document with the unformatted BNF. Note that setting this option to true is only effective if the parameter text is false. Default value is false.
      Since:
      2.6

    • oneTable

      @Parameter(property="javacc.oneTable", defaultValue="true") private boolean oneTable
      This option controls the structure of the generated HTML output. If set to true, a single HTML table for the entire BNF is generated. Setting it to false will produce one table for every production in the grammar.

  • Constructor Details

    • JJDocMojo

      public JJDocMojo()

  • Method Details

    • getOutputDirectory

      protected String getOutputDirectory()
      Get the output directory of the report if run directly from the command line.
      Overrides:
      getOutputDirectory in class org.apache.maven.reporting.AbstractMavenReport
      Returns:
      The report output directory.
      See Also:
      • AbstractMavenReport.getOutputDirectory()

    • getJJDocOutputDirectory

      private File getJJDocOutputDirectory()
      Get the output directory of the JJDoc files, i.e. the sub directory in the report output directory as specified by the jjdocDirectory parameter.
      Returns:
      The report output directory of the JJDoc files.

    • getSourceDirectories

      private File[] getSourceDirectories()
      Get the source directories that should be scanned for grammar files.
      Returns:
      The source directories that should be scanned for grammar files, never null.

    • getName

      public String getName(Locale locale)
      Parameters:
      locale - The locale to use for this report.
      Returns:
      The name of this report.
      See Also:
      • MavenReport.getName(java.util.Locale)

    • getDescription

      public String getDescription(Locale locale)
      Parameters:
      locale - The locale to use for this report.
      Returns:
      The description of this report.
      See Also:
      • MavenReport.getDescription(java.util.Locale)

    • getOutputName

      public String getOutputName()
      Returns:
      The name of the main report file.
      See Also:
      • MavenReport.getOutputName()

    • canGenerateReport

      public boolean canGenerateReport()
      Specified by:
      canGenerateReport in interface org.apache.maven.reporting.MavenReport
      Overrides:
      canGenerateReport in class org.apache.maven.reporting.AbstractMavenReport
      Returns:
      true if the configured source directories are not empty, false otherwise.
      See Also:
      • MavenReport.canGenerateReport()

    • executeReport

      public void executeReport(Locale locale) throws org.apache.maven.reporting.MavenReportException
      Run the actual report.
      Specified by:
      executeReport in class org.apache.maven.reporting.AbstractMavenReport
      Parameters:
      locale - The locale to use for this report.
      Throws:
      org.apache.maven.reporting.MavenReportException - If the report generation failed.

    • getOutputFileExtension

      private String getOutputFileExtension()
      The JJDoc output file will have a .html or .txt extension depending on the value of the parameters text and bnf.
      Returns:
      The file extension (including the leading period) to be used for the JJDoc output files.

    • createReportHeader

      private void createReportHeader(ResourceBundle bundle, org.apache.maven.doxia.sink.Sink sink)
      Create the header and title for the HTML report page.
      Parameters:
      bundle - The resource bundle with the text.
      sink - The sink for writing to the main report file.

    • createReportLink

      private void createReportLink(org.apache.maven.doxia.sink.Sink sink, File sourceDirectory, File grammarFile, String linkPath)
      Create a table row containing a link to the JJDoc report for a grammar file.
      Parameters:
      sink - The sink to write the report
      sourceDirectory - The source directory of the grammar file.
      grammarFile - The JavaCC grammar file.
      linkPath - The path to the JJDoc output.

    • createReportFooter

      private void createReportFooter(org.apache.maven.doxia.sink.Sink sink)
      Create the HTML footer for the report page.
      Parameters:
      sink - The sink to write the HTML report page.

    • newJJDoc

      private JJDoc newJJDoc()
      Creates a new facade to invoke JJDoc. Most options for the invocation are derived from the current values of the corresponding mojo parameters. The caller is responsible to set the input file and output file on the returned facade.
      Returns:
      The facade for the tool invocation, never null.

    • scanForGrammars

      private GrammarInfo[] scanForGrammars(File sourceDirectory) throws org.apache.maven.reporting.MavenReportException
      Searches the specified source directory to find grammar files that can be documented.
      Parameters:
      sourceDirectory - The source directory to scan for grammar files.
      Returns:
      An array of grammar infos describing the found grammar files or null if the source directory does not exist.
      Throws:
      org.apache.maven.reporting.MavenReportException - If there is a problem while scanning for .jj files.

    • getBundle

      private ResourceBundle getBundle(Locale locale)
      Get the resource bundle for the report text.
      Parameters:
      locale - The locale to use for this report.
      Returns:
      The resource bundle.

    • generate

      public void generate(org.apache.maven.doxia.sink.Sink sink, Locale locale) throws org.apache.maven.reporting.MavenReportException
      Specified by:
      generate in interface org.apache.maven.reporting.MavenReport
      Overrides:
      generate in class org.apache.maven.reporting.AbstractMavenReport
      Throws:
      org.apache.maven.reporting.MavenReportException