Package rife.bld.extension

Class JacocoReportOperation

java.lang.Object
rife.bld.operations.AbstractOperation<JacocoReportOperation>
rife.bld.extension.JacocoReportOperation
@NullMarked public class JacocoReportOperation extends AbstractOperation<JacocoReportOperation>
Generates JaCoCo reports.

Execution modes:

Note: the live internal lists returned by classFiles(), execFiles(), sourceFiles(), etc. are mutable by design to support the fluent builder pattern. Modifying them may cause unexpected behavior.

Since:
1.0
Author:
Erik C. Thauvin

  • Field Details

  • Constructor Details

    • JacocoReportOperation

      public JacocoReportOperation()

  • Method Details

    • execute

      public void execute() throws Exception
      Performs the operation execution that can be wrapped by the #executeOnce call.
      Specified by:
      execute in class AbstractOperation<JacocoReportOperation>
      Throws:
      NullPointerException - if the project is null
      Exception

    • classFiles

      public JacocoReportOperation classFiles(File... classFiles)
      Sets the locations of Java class files.
      Parameters:
      classFiles - the class files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if classFiles is null or contains null elements
      IllegalArgumentException - if classFiles is empty
      See Also:

    • classFiles

      public JacocoReportOperation classFiles(String... classFiles)
      Sets the locations of Java class files.
      Parameters:
      classFiles - the class files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if classFiles is null or contains null elements
      IllegalArgumentException - if classFiles is empty, or contains blank elements
      See Also:

    • classFiles

      public JacocoReportOperation classFiles(Path... classFiles)
      Sets the locations of Java class files.
      Parameters:
      classFiles - the class files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if classFiles is null or contains null elements
      IllegalArgumentException - if classFiles is empty
      See Also:

    • classFiles

      public List<File> classFiles()
      Returns the locations of Java class files.

      The returned list is the live internal list and is mutable by design to support the fluent builder pattern.

      Returns:
      the class files

    • classFiles

      public final JacocoReportOperation classFiles(Collection<File> classFiles)
      Sets the locations of Java class files.
      Parameters:
      classFiles - the class files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if classFiles is null or contains null elements
      IllegalArgumentException - if classFiles is empty
      See Also:

    • classFilesPaths

      public final JacocoReportOperation classFilesPaths(Collection<Path> classFiles)
      Sets the locations of Java class files.
      Parameters:
      classFiles - the class files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if classFiles is null or contains null elements
      IllegalArgumentException - if classFiles is empty
      See Also:

    • classFilesStrings

      public final JacocoReportOperation classFilesStrings(Collection<String> classFiles)
      Sets the locations of Java class files.
      Parameters:
      classFiles - the class files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if classFiles is null or contains null elements
      IllegalArgumentException - if classFiles is empty, or contains blank elements
      See Also:

    • csv

      public JacocoReportOperation csv(File csv)
      Sets the location of the CSV report.
      Parameters:
      csv - the report location
      Returns:
      this operation instance
      Throws:
      NullPointerException - if csv is null

    • csv

      public JacocoReportOperation csv(String csv)
      Sets the location of the CSV report.
      Parameters:
      csv - the report location
      Returns:
      this operation instance
      Throws:
      NullPointerException - if csv is null
      IllegalArgumentException - if csv is blank

    • csv

      public JacocoReportOperation csv(Path csv)
      Sets the location of the CSV report.
      Parameters:
      csv - the report location
      Returns:
      this operation instance
      Throws:
      NullPointerException - if csv is null

    • csv

      public @Nullable File csv()
      Returns the CSV report location.
      Returns:
      the CSV report location

    • destFile

      public JacocoReportOperation destFile(File destFile)
      Sets the file to write execution data to.
      Parameters:
      destFile - the file
      Returns:
      this operation instance
      Throws:
      NullPointerException - if destFile is null

    • destFile

      public JacocoReportOperation destFile(String destFile)
      Sets the file to write execution data to.
      Parameters:
      destFile - the file
      Returns:
      this operation instance
      Throws:
      NullPointerException - if destFile is null
      IllegalArgumentException - if destFile is blank

    • destFile

      public JacocoReportOperation destFile(Path destFile)
      Sets the file to write execution data to.
      Parameters:
      destFile - the file
      Returns:
      this operation instance
      Throws:
      NullPointerException - if destFile is null

    • destFile

      public @Nullable File destFile()
      Returns the file to write execution data to.
      Returns:
      the file to write execution data to

    • disableCsv

      public JacocoReportOperation disableCsv()
      Disables generation of the CSV report.
      Returns:
      this operation
      Since:
      1.1

    • disableHtml

      public JacocoReportOperation disableHtml()
      Disables generation of the HTML report.
      Returns:
      this operation instance
      Since:
      1.1

    • disableXml

      public JacocoReportOperation disableXml()
      Disables generation of the XML report.
      Returns:
      this operation instance
      Since:
      1.1

    • enableAllReports

      public JacocoReportOperation enableAllReports()
      Enables generation of all report formats (CSV, HTML, and XML).

      This is a convenience method equivalent to calling enableCsv(), enableHtml(), and enableXml(). All reports are enabled by default.

      Example: 

      
 new JacocoReportOperation()
     .fromProject(project)
     .disableHtml()
     .disableCsv()
     .enableAllReports() // re-enables everything
     .execute();
      Returns:
      this operation instance for method chaining
      Since:
      1.1
      See Also:

    • enableCsv

      public JacocoReportOperation enableCsv()
      Enables generation of the CSV report.

      Call this to re-enable CSV output after disableCsv() was called. CSV generation is enabled by default.

      Returns:
      this operation instance for method chaining
      Since:
      1.1
      See Also:

    • enableHtml

      public JacocoReportOperation enableHtml()
      Enables generation of the HTML report.

      Call this to re-enable HTML output after disableHtml() was called. HTML generation is enabled by default. The HTML report includes source highlighting and is suitable for human review.

      Returns:
      this operation instance for method chaining
      Since:
      1.1
      See Also:

    • enableXml

      public JacocoReportOperation enableXml()
      Enables generation of the XML report.

      Call this to re-enable XML output after disableXml() was called. XML generation is enabled by default. The XML report is machine-readable and commonly used by CI tools like SonarQube.

      Returns:
      this operation instance for method chaining
      Since:
      1.1
      See Also:

    • encoding

      public JacocoReportOperation encoding(String encoding)
      Sets the source file encoding. The platform encoding is used by default.
      Parameters:
      encoding - the encoding
      Returns:
      this operation instance
      Throws:
      NullPointerException - if encoding is null
      IllegalArgumentException - if encoding is blank

    • encoding

      public @Nullable String encoding()
      Returns the source file encoding, or null if not set (platform default will be used).
      Returns:
      the source file encoding

    • excludes

      public JacocoReportOperation excludes(String... patterns)
      Sets class name patterns to exclude from the coverage analysis.

      Uses Ant-style path patterns matched against JVM internal class names with '/' separators. Exclude patterns take precedence over include patterns.

      Pattern syntax:

      • * matches zero or more characters except '/'
      • ** matches zero or more directories
      • ? matches a single character

      Common examples:

      • "&ast;&ast;/&ast;Test&ast;" - exclude all test classes
      • "&ast;&ast;/generated/&ast;&ast;" - exclude generated code
      • "&ast;&ast;/proto/&ast;&ast;" - exclude protobuf classes
      • "&ast;&ast;/Dagger&ast;" - exclude Dagger generated classes
      Parameters:
      patterns - the Ant-style exclude patterns; must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if patterns is null, or contains null elements
      IllegalArgumentException - if patterns is empty, or contains empty strings
      See Also:

    • excludes

      public List<String> excludes()
      Returns the class name patterns to exclude from coverage analysis.

      The returned list is the live internal list and is mutable by design to support the fluent builder pattern.

      Returns:
      the exclude patterns, empty if no classes are excluded
      See Also:

    • excludes

      public final JacocoReportOperation excludes(Collection<String> patterns)
      Sets class name patterns to exclude from the coverage analysis.

      Uses Ant-style path patterns matched against JVM internal class names with '/' separators. Exclude patterns take precedence over include patterns.

      Pattern syntax:

      • * matches zero or more characters except '/'
      • ** matches zero or more directories
      • ? matches a single character

      Common examples:

      • "&ast;&ast;/&ast;Test&ast;" - exclude all test classes
      • "&ast;&ast;/generated/&ast;&ast;" - exclude generated code
      • "&ast;&ast;/proto/&ast;&ast;" - exclude protobuf classes
      • "&ast;&ast;/Dagger&ast;" - exclude Dagger generated classes
      Parameters:
      patterns - the Ant-style exclude patterns; must not be null, empty, or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if patterns is null, or contains null elements
      IllegalArgumentException - if patterns is empty, or contains blank elements
      See Also:

    • execFiles

      public JacocoReportOperation execFiles(File... execFiles)
      Sets the locations of the JaCoCo *.exec files to read.

      If exec files are provided and testOperation(TestOperation) is not called, tests will not be executed. Reports are generated from the provided files only.

      If both exec files and a test operation are provided, tests run and the new execution data is merged with the provided files.

      Parameters:
      execFiles - the exec files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if execFiles is null or contains null elements
      IllegalArgumentException - if execFiles is empty
      See Also:

    • execFiles

      public JacocoReportOperation execFiles(String... execFiles)
      Sets the locations of the JaCoCo *.exec files to read.

      If exec files are provided and testOperation(TestOperation) is not called, tests will not be executed. Reports are generated from the provided files only.

      If both exec files and a test operation are provided, tests run and the new execution data is merged with the provided files.

      Parameters:
      execFiles - the exec files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if execFiles is null or contains null elements
      IllegalArgumentException - if execFiles is empty, or contains blank elements
      See Also:

    • execFiles

      public JacocoReportOperation execFiles(Path... execFiles)
      Sets the locations of the JaCoCo *.exec files to read.

      If exec files are provided and testOperation(TestOperation) is not called, tests will not be executed. Reports are generated from the provided files only.

      If both exec files and a test operation are provided, tests run and the new execution data is merged with the provided files.

      Parameters:
      execFiles - the exec files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if execFiles is null or contains null elements
      IllegalArgumentException - if execFiles is empty
      See Also:

    • execFiles

      public final JacocoReportOperation execFiles(Collection<File> execFiles)
      Sets the locations of the JaCoCo *.exec files to read.

      If exec files are provided and testOperation(TestOperation) is not called, tests will not be executed. Reports are generated from the provided files only.

      If both exec files and a test operation are provided, tests run and the new execution data is merged with the provided files.

      Parameters:
      execFiles - the exec files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if execFiles is null or contains null elements
      IllegalArgumentException - if execFiles is empty
      See Also:

    • execFiles

      public List<File> execFiles()
      Returns the locations of the JaCoCo *.exec files to read.

      The returned list is the live internal list and is mutable by design to support the fluent builder pattern.

      Returns:
      the exec files

    • execFilesPaths

      public final JacocoReportOperation execFilesPaths(Collection<Path> execFiles)
      Sets the locations of the JaCoCo *.exec files to read.

      If exec files are provided and testOperation(TestOperation) is not called, tests will not be executed. Reports are generated from the provided files only.

      If both exec files and a test operation are provided, tests run and the new execution data is merged with the provided files.

      Parameters:
      execFiles - the exec files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if execFiles is null or contains null elements
      IllegalArgumentException - if execFiles is empty
      See Also:

    • execFilesStrings

      public final JacocoReportOperation execFilesStrings(Collection<String> execFiles)
      Sets the locations of the JaCoCo *.exec files to read.

      If exec files are provided and testOperation(TestOperation) is not called, tests will not be executed. Reports are generated from the provided files only.

      If both exec files and a test operation are provided, tests run and the new execution data is merged with the provided files.

      Parameters:
      execFiles - the exec files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if execFiles is null or contains null elements
      IllegalArgumentException - if execFiles is empty, or contains blank elements
      See Also:

    • fromProject

      public JacocoReportOperation fromProject(BaseProject project)
      Configure the operation from a BaseProject.
      Parameters:
      project - the project
      Returns:
      this operation instance
      Throws:
      NullPointerException - if project is null

    • html

      public JacocoReportOperation html(File html)
      Sets the directory for the HTML report output.
      Parameters:
      html - the HTML report directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if html is null

    • html

      public JacocoReportOperation html(String html)
      Sets the directory for the HTML report output.
      Parameters:
      html - the HTML report directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if html is null
      IllegalArgumentException - if html is blank

    • html

      public JacocoReportOperation html(Path html)
      Sets the directory for the HTML report output.
      Parameters:
      html - the HTML report directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if html is null

    • html

      public @Nullable File html()
      Returns the HTML report output directory.
      Returns:
      the HTML report directory

    • includes

      public JacocoReportOperation includes(String... patterns)
      Sets class name patterns to include in the coverage analysis.

      Uses Ant-style path patterns matched against JVM internal class names with '/' separators. If no includes are specified, all classes are included by default unless excluded.

      Pattern syntax:

      • * matches zero or more characters except '/'
      • ** matches zero or more directories
      • ? matches a single character

      Examples:

      • "com/myapp/&ast;&ast;" - all classes in com.myapp and subpackages
      • "&ast;&ast;/service/&ast;" - all classes directly in any service package
      • "com/myapp/MyClass" - single class com.myapp.MyClass
      Parameters:
      patterns - the Ant-style include patterns; must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if patterns is null, or contains null elements
      IllegalArgumentException - if patterns is empty, or contains empty elements
      See Also:

    • includes

      public List<String> includes()
      Returns the class name patterns to include in coverage analysis.

      The returned list is the live internal list and is mutable by design to support the fluent builder pattern.

      Returns:
      the include patterns, empty if all classes are included
      See Also:

    • includes

      public final JacocoReportOperation includes(Collection<String> patterns)
      Sets class name patterns to include in the coverage analysis.

      Uses Ant-style path patterns matched against JVM internal class names with '/' separators. If no includes are specified, all classes are included by default unless excluded.

      Pattern syntax:

      • * matches zero or more characters except '/'
      • ** matches zero or more directories
      • ? matches a single character

      Examples:

      • "com/myapp/&ast;&ast;" - all classes in com.myapp and subpackages
      • "&ast;&ast;/service/&ast;" - all classes directly in any service package
      • "com/myapp/MyClass" - single class com.myapp.MyClass
      Parameters:
      patterns - the Ant-style include patterns; must not be null, empty, or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if patterns is null, or contains null elements
      IllegalArgumentException - if patterns is empty, or contains blank elements
      See Also:

    • isCsvDisabled

      public boolean isCsvDisabled()
      Returns whether CSV report generation is disabled.
      Returns:
      true if the CSV report is disabled
      Since:
      1.1

    • isHtmlDisabled

      public boolean isHtmlDisabled()
      Returns whether HTML report generation is disabled.
      Returns:
      true if the HTML report is disabled
      Since:
      1.1

    • isQuiet

      public boolean isQuiet()
      Return the status of the quiet flag.
      Returns:
      true if enabled, false otherwise

    • isXmlDisabled

      public boolean isXmlDisabled()
      Returns whether XML report generation is disabled.
      Returns:
      true if the XML report is disabled
      Since:
      1.1

    • name

      public JacocoReportOperation name(String name)
      Sets the name used for the report.
      Parameters:
      name - the name
      Returns:
      this operation instance
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if name is blank

    • name

      public String name()
      Returns the name used for the report.
      Returns:
      the report name.

    • quiet

      public JacocoReportOperation quiet(boolean quiet)
      Suppresses all output.
      Parameters:
      quiet - true or false
      Returns:
      this operation instance

    • sourceFiles

      public JacocoReportOperation sourceFiles(File... sourceFiles)
      Sets the locations of the source files. (e.g., src/main/java)
      Parameters:
      sourceFiles - the source files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if sourceFiles is null or contains null elements
      IllegalArgumentException - if sourceFiles is empty
      See Also:

    • sourceFiles

      public JacocoReportOperation sourceFiles(String... sourceFiles)
      Sets the locations of the source files. (e.g., src/main/java)
      Parameters:
      sourceFiles - the source files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if sourceFiles is null or contains null elements
      IllegalArgumentException - if sourceFiles is empty, or contains blank elements
      See Also:

    • sourceFiles

      public JacocoReportOperation sourceFiles(Path... sourceFiles)
      Sets the locations of the source files. (e.g., src/main/java)
      Parameters:
      sourceFiles - the source files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if sourceFiles is null or contains null elements
      IllegalArgumentException - if sourceFiles is empty
      See Also:

    • sourceFiles

      public final JacocoReportOperation sourceFiles(Collection<File> sourceFiles)
      Sets the locations of the source files. (e.g., src/main/java)
      Parameters:
      sourceFiles - the source files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if sourceFiles is null or contains null elements
      IllegalArgumentException - if sourceFiles is empty
      See Also:

    • sourceFiles

      public List<File> sourceFiles()
      Returns the locations of the source files.

      The returned list is the live internal list and is mutable by design to support the fluent builder pattern.

      Returns:
      the source files

    • sourceFilesPaths

      public final JacocoReportOperation sourceFilesPaths(Collection<Path> sourceFiles)
      Sets the locations of the source files. (e.g., src/main/java)
      Parameters:
      sourceFiles - the source files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if sourceFiles is null or contains null elements
      IllegalArgumentException - if sourceFiles is empty
      See Also:

    • sourceFilesStrings

      public final JacocoReportOperation sourceFilesStrings(Collection<String> sourceFiles)
      Sets the locations of the source files. (e.g., src/main/java)
      Parameters:
      sourceFiles - the source files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if sourceFiles is null or contains null elements
      IllegalArgumentException - if sourceFiles is empty, or contains blank elements
      See Also:

    • tabWidth

      public JacocoReportOperation tabWidth(int tabWidth)
      Sets the tab stop width for the source pages. Default is 4.
      Parameters:
      tabWidth - the tab width
      Returns:
      this operation instance
      Throws:
      IllegalArgumentException - if tabWidth is not positive

    • tabWidth

      public int tabWidth()
      Returns the tab stop width for the source pages.
      Returns:
      the tab stop width

    • testOperation

      public JacocoReportOperation testOperation(TestOperation<?,?> testOperation)
      Sets the test operation.

      If set, tests are always executed even when execFiles(File...) is also called. The JaCoCo agent is attached to this operation and the resulting execution data is merged with any provided exec files.

      If not set and no exec files are provided, fromProject(BaseProject) will create a default test operation from the project.

      Parameters:
      testOperation - the test operation; must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if testOperation is null
      See Also:

    • testToolOptions

      public List<String> testToolOptions()
      Returns the test tool options.

      The returned list is the live internal list and is mutable by design to support the fluent builder pattern.

      Returns:
      the test tool options

    • testToolOptions

      public JacocoReportOperation testToolOptions(String... options)
      Sets the test tool options.
      Parameters:
      options - the options to set
      Returns:
      this operation instance
      Throws:
      NullPointerException - if options is null or contains null elements
      IllegalArgumentException - if options is empty, or contains blank elements
      See Also:

    • testToolOptions

      public final JacocoReportOperation testToolOptions(Collection<String> options)
      Sets the test tool options.
      Parameters:
      options - the options to set
      Returns:
      this operation instance
      Throws:
      NullPointerException - if options is null or contains null elements
      IllegalArgumentException - if options is empty, or contains blank elements
      See Also:

    • xml

      public JacocoReportOperation xml(File xml)
      Sets the location of the XML report.
      Parameters:
      xml - the report location
      Returns:
      this operation instance
      Throws:
      NullPointerException - if xml is null

    • xml

      public JacocoReportOperation xml(String xml)
      Sets the location of the XML report.
      Parameters:
      xml - the report location
      Returns:
      this operation instance
      Throws:
      NullPointerException - if xml is null
      IllegalArgumentException - if xml is blank

    • xml

      public JacocoReportOperation xml(Path xml)
      Sets the location of the XML report.
      Parameters:
      xml - the report location
      Returns:
      this operation instance
      Throws:
      NullPointerException - if xml is null

    • xml

      public @Nullable File xml()
      Returns the XML report location.
      Returns:
      the XML report location