Interface JctCompiler

All Known Implementing Classes:
AbstractJctCompiler

public interface JctCompiler
Base definition of a compiler that can be configured to perform a compilation run against sources.

JctCompiler objects are often a nexus that will manage configuring an underlying JSR-199 compiler internally in a platform-agnostic way.

Since:
0.0.1
Author:
Ashley Scopes
  • Field Details

  • Method Details

    • compile

      Invoke the compilation and return the compilation result.

      The actual classes to compile will be dynamically discovered. If you wish to specify the specific classes to compile, see compile(Workspace, String...) or compile(Workspace, Collection).

      Parameters:
      workspace - the workspace to compile.
      Returns:
      the compilation result.
      Throws:
      JctCompilerException - if the compiler threw an unhandled exception. This should not occur for compilation failures generally.
      IllegalStateException - if no compilation units were found.
      UncheckedIOException - if an IO error occurs.
      See Also:
    • compile

      default JctCompilation compile(Workspace workspace, String... classNames)
      Invoke the compilation and return the compilation result.

      Only classes matching the given class names will be compiled.

      If you wish to let JCT determine which classes to compile dynamically, see compile(Workspace) instead.

      Note that nested instance/static nested classes cannot be specified individually here. To compile them, you must also compile their outer class that they are defined within.

      Parameters:
      workspace - the workspace to compile.
      classNames - the class names to compile.
      Returns:
      the compilation result.
      Throws:
      JctCompilerException - if the compiler threw an unhandled exception. This should not occur for compilation failures generally.
      NullPointerException - if any class names are null, or if the array is null.
      IllegalStateException - if no compilation units were found.
      UncheckedIOException - if an IO error occurs.
      See Also:
    • compile

      JctCompilation compile(Workspace workspace, Collection<String> classNames)
      Invoke the compilation and return the compilation result.

      Only classes matching the given class names will be compiled.

      If you wish to let JCT determine which classes to compile dynamically, see compile(Workspace) instead.

      Note that nested instance/static nested classes cannot be specified individually here. To compile them, you must also compile their outer class that they are defined within.

      Parameters:
      workspace - the workspace to compile.
      classNames - the class names to compile.
      Returns:
      the compilation result.
      Throws:
      JctCompilerException - if the compiler threw an unhandled exception. This should not occur for compilation failures usually.
      NullPointerException - if the classNames collection contains any null values, or if the collection itself is null.
      IllegalArgumentException - if the collection is empty.
      IllegalStateException - if no compilation units were found.
      UncheckedIOException - if an IO error occurs.
      See Also:
    • configure

      <E extends Exception> JctCompiler configure(JctCompilerConfigurer<E> configurer) throws E
      Apply a given configurer to this compiler.

      Configurers can be lambdas, method references, or objects.

      
         // Using an object configurer
         var werrorConfigurer = new JctCompilerConfigurer<RuntimeException>() {
           @Override
           public void configure(JctCompiler compiler) {
             compiler.failOnWarnings(true);
           }
         };
         compiler.configure(werrorConfigurer);
      
         // Using a lambda configurer
         compiler.configure(c -> c.verbose(true));
       

      Configurers take a type parameter that corresponds to an exception type. This is the exception type that can be thrown by the configurer, or RuntimeException if no checked exception is thrown. This mechanism allows configurers to propagate checked exceptions to their caller where needed.

      
         class FileFlagConfigurer implements JctCompilerConfigurer<IOException> {
           private final Path path;
      
           public FileFlagConfigurer(String... path) {
             this(Path.of(path));
           }
      
           public FileFlagConfigurer(Path path) {
             this.path = path;
           }
      
           @Override
           public void configure(JctCompiler compiler) throws IOException {
             var flags = Files.lines(path)
                 .map(String::trim)
                 .filter(not(String::isBlank))
                 .toList();
             compiler.addCompilerOptions(flags);
           }
         }
      
         @Test
         void testSomething() throws IOException {
           ...
           compiler.configure(new FileFlagConfigurer("src", "test", "resources", "flags.txt"));
           ...
         }
       
      Type Parameters:
      E - any exception that may be thrown.
      Parameters:
      configurer - the configurer to invoke.
      Returns:
      this compiler object for further call chaining.
      Throws:
      E - any exception that may be thrown by the configurer. If no checked exception is thrown, then this should be treated as RuntimeException.
    • getName

      Get the friendly printable name of this compiler object.
      Returns:
      the name of the compiler.
    • name

      Set the friendly name of this compiler.

      This will be used by the JUnit5 support to name unit test cases.

      Parameters:
      name - the name to set.
      Returns:
      this compiler object for further call chaining.
    • getAnnotationProcessorOptions

      Get an immutable snapshot view of the current annotation processor options that are set.
      Returns:
      the current annotation processor options that are set.
    • addAnnotationProcessorOptions

      Add options to pass to any annotation processors.
      Parameters:
      annotationProcessorOptions - the options to pass.
      Returns:
      this compiler object for further call chaining.
    • addAnnotationProcessorOptions

      default JctCompiler addAnnotationProcessorOptions(String... annotationProcessorOptions)
      Add options to pass to any annotation processors.
      Parameters:
      annotationProcessorOptions - options to pass.
      Returns:
      this compiler object for further call chaining.
    • getAnnotationProcessors

      Get an immutable snapshot view of the current annotation processors that are explicitly set to be run, in the order that they were provided to the compiler.
      Returns:
      the current annotation processors that are set.
    • addAnnotationProcessors

      JctCompiler addAnnotationProcessors(Iterable<? extends Processor> annotationProcessors)
      Add annotation processors to invoke.

      Warning: This bypasses the discovery process of annotation processors provided in the annotation processor path and annotation processor module paths, as well as any other locations such as class paths and module paths.

      Parameters:
      annotationProcessors - the processors to invoke.
      Returns:
      this compiler object for further call chaining.
    • addAnnotationProcessors

      default JctCompiler addAnnotationProcessors(Processor... annotationProcessors)
      Add annotation processors to invoke.

      Warning: This bypasses the discovery process of annotation processors provided in the annotation processor path and annotation processor module paths, as well as any other locations such as class paths and module paths.

      Parameters:
      annotationProcessors - processors to invoke.
      Returns:
      this compiler object for further call chaining.
    • getCompilerOptions

      Get an immutable snapshot view of the current compiler options that are set.
      Returns:
      the current compiler options that are set.
    • addCompilerOptions

      Add command line options to pass to javac.
      Parameters:
      compilerOptions - the options to add.
      Returns:
      this compiler object for further call chaining.
    • addCompilerOptions

      default JctCompiler addCompilerOptions(String... compilerOptions)
      Add command line options to pass to javac.
      Parameters:
      compilerOptions - options to add.
      Returns:
      this compiler object for further call chaining.
    • isVerbose

      boolean isVerbose()
      Determine whether verbose logging is enabled or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_VERBOSE.

      Note that enabling this is compiler-specific behaviour. There is no guarantee that the output target or the format or verbosity of output will be consistent between different compiler implementations.

      Returns:
      whether verbose logging is enabled or not.
    • verbose

      JctCompiler verbose(boolean enabled)
      Set whether to use verbose output or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_VERBOSE.

      Note that enabling this is compiler-specific behaviour. There is no guarantee that the output target or the format or verbosity of output will be consistent between different compiler implementations.

      Parameters:
      enabled - true for verbose output, false for normal output.
      Returns:
      this compiler for further call chaining.
    • isPreviewFeatures

      Determine whether preview features are enabled or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_PREVIEW_FEATURES.

      Returns:
      whether preview features are enabled or not.
    • previewFeatures

      JctCompiler previewFeatures(boolean enabled)
      Set whether to enable compiler preview features or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_PREVIEW_FEATURES.

      Generally, this feature should be avoided if testing across multiple versions of Java, as preview features are often not finalised and may change without warning.

      Parameters:
      enabled - true to enable preview features, or false to disable them.
      Returns:
      this compiler object for further call chaining.
    • isShowWarnings

      boolean isShowWarnings()
      Determine whether warnings are enabled or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_SHOW_WARNINGS.

      Returns:
      whether warnings are enabled or not.
    • showWarnings

      JctCompiler showWarnings(boolean enabled)
      Set whether to enable displaying warnings or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_SHOW_WARNINGS.

      Parameters:
      enabled - true to enable warnings. false to disable them.
      Returns:
      this compiler object for further call chaining.
    • isShowDeprecationWarnings

      Determine whether deprecation warnings are enabled or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_SHOW_DEPRECATION_WARNINGS.

      Returns:
      whether deprecation warnings are enabled or not.
    • showDeprecationWarnings

      Set whether to enable deprecation warnings or not.

      This is ignored if showWarnings(boolean) is disabled.

      Unless otherwise changed or specified, implementations should default to DEFAULT_SHOW_DEPRECATION_WARNINGS.

      Parameters:
      enabled - true to enable deprecation warnings. false to disable them.
      Returns:
      this compiler object for further call chaining.
    • isFailOnWarnings

      boolean isFailOnWarnings()
      Determine whether warnings are being treated as errors or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_FAIL_ON_WARNINGS.

      Returns:
      whether warnings are being treated as errors or not.
    • failOnWarnings

      JctCompiler failOnWarnings(boolean enabled)
      Set whether to enable treating warnings as errors or not.

      Some compilers may call this flag something different, such as "-Werror".

      This is ignored if showWarnings(boolean) is disabled.

      Unless otherwise changed or specified, implementations should default to DEFAULT_FAIL_ON_WARNINGS.

      Parameters:
      enabled - true to enable treating warnings as errors. false to disable them.
      Returns:
      this compiler object for further call chaining.
    • getCompilationMode

      Get the compilation mode that is in use.

      Unless otherwise changed or specified, implementations should default to DEFAULT_COMPILATION_MODE.

      Returns:
      the compilation mode.
    • compilationMode

      Set the compilation mode to use for this compiler.

      This allows you to override whether sources are compiled or annotation-processed without running the full compilation process. Tuning this may provide faster test cases in some situations.

      Unless otherwise changed or specified, implementations should default to DEFAULT_COMPILATION_MODE.

      Parameters:
      compilationMode - the compilation mode to use.
      Returns:
      this compiler object for further call chaining.
    • getDefaultRelease

      Get the default release to use if no release or target version is specified.

      This can not be configured generally, as it is defined by the internal compiler implementation.

      Generally, this value will be an integer within a string. The value is represented as a string to allow supporting compilers which may use non-integer version numbers.

      Returns:
      the default release version to use.
    • getEffectiveRelease

      Get the effective release to use for the actual compilation.

      Generally, this value will be an integer within a string. The value is represented as a string to allow supporting compilers which may use non-integer version numbers.

      This may be determined from the source, target, release, and default release.

      Returns:
      the effective release.
    • getRelease

      Get the current release version that is set, or null if left to the compiler to decide. default.

      Generally, this value will be an integer within a string. The value is represented as a string to allow supporting compilers which may use non-integer version numbers.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Returns:
      the release version string, if set.
    • release

      Set the release version.

      This will clear any source and target version that is set.

      Generally, this value will be an integer within a string. The value is represented as a string to allow supporting compilers which may use non-integer version numbers.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Parameters:
      release - the version to set.
      Returns:
      this compiler object for further call chaining.
    • release

      default JctCompiler release(int release)
      Set the release version.

      This will clear any source and target version that is set.

      Generally, this value will be an integer within a string. The value is represented as a string to allow supporting compilers which may use non-integer version numbers.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Parameters:
      release - the version to set.
      Returns:
      this compiler object for further call chaining.
      Throws:
      IllegalArgumentException - if the version is less than 0.
      UnsupportedOperationException - if the compiler does not support integer versions.
    • release

      default JctCompiler release(SourceVersion release)
      Set the release version.

      This will clear any source and target version that is set.

      Generally, this value will be an integer within a string. The value is represented as a string to allow supporting compilers which may use non-integer version numbers.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Parameters:
      release - the version to set.
      Returns:
      this compiler object for further call chaining.
      Throws:
      UnsupportedOperationException - if the compiler does not support integer versions.
      NullPointerException - if the release is null.
    • useRuntimeRelease

      Request that the compiler uses a language version that corresponds to the runtime language version in use on the current JVM.

      For example, running this on JRE 19 would set the release to "19".

      This calls release(int) internally.

      Returns:
      this compiler object for further call chaining.
      Throws:
      UnsupportedOperationException - if the current JVM version does not correspond to a supported Java release version in the compiler, or if the compiler does not support integral version numbers.
      Since:
      1.1.0
    • getSource

      Get the current source version that is set, or null if left to the compiler to decide. default.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Returns:
      the source version string, if set.
    • source

      Set the source version.

      This will clear any release version that is set.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Source and target versions have mostly been replaced with the release version mechanism which controls both flags and can ensure other behaviours are consistent. This feature is still provided in case you have a specific use case that is not covered by this functionality.

      Parameters:
      source - the version to set.
      Returns:
      this compiler object for further call chaining.
    • source

      default JctCompiler source(int source)
      Set the source version.

      This will clear any release version that is set.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Source and target versions have mostly been replaced with the release version mechanism which controls both flags and can ensure other behaviours are consistent. This feature is still provided in case you have a specific use case that is not covered by this functionality.

      Parameters:
      source - the version to set.
      Returns:
      this compiler object for further call chaining.
      Throws:
      IllegalArgumentException - if the version is less than 0.
      UnsupportedOperationException - if the compiler does not support integer versions.
    • source

      default JctCompiler source(SourceVersion source)
      Set the source version.

      This will clear any release version that is set.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Source and target versions have mostly been replaced with the release version mechanism which controls both flags and can ensure other behaviours are consistent. This feature is still provided in case you have a specific use case that is not covered by this functionality.

      Parameters:
      source - the version to set.
      Returns:
      this compiler object for further call chaining.
      Throws:
      UnsupportedOperationException - if the compiler does not support integer versions.
      NullPointerException - if the source is null.
    • getTarget

      Get the current target version that is set, or null if left to the compiler default.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Returns:
      the target version string, if set.
    • target

      Set the target version.

      This will clear any release version that is set.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Source and target versions have mostly been replaced with the release version mechanism which controls both flags and can ensure other behaviours are consistent. This feature is still provided in case you have a specific use case that is not covered by this functionality.

      Parameters:
      target - the version to set.
      Returns:
      this compiler object for further call chaining.
    • target

      default JctCompiler target(int target)
      Set the target version.

      This will clear any release version that is set.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Source and target versions have mostly been replaced with the release version mechanism which controls both flags and can ensure other behaviours are consistent. This feature is still provided in case you have a specific use case that is not covered by this functionality.

      Parameters:
      target - the version to set.
      Returns:
      this compiler object for further call chaining.
      Throws:
      IllegalArgumentException - if the version is less than 0.
      UnsupportedOperationException - if the compiler does not support integer versions.
    • target

      default JctCompiler target(SourceVersion target)
      Set the target version.

      This will clear any release version that is set.

      Unless explicitly defined, the default setting is expected to be a sane compiler-specific default.

      Source and target versions have mostly been replaced with the release version mechanism which controls both flags and can ensure other behaviours are consistent. This feature is still provided in case you have a specific use case that is not covered by this functionality.

      Parameters:
      target - the version to set.
      Returns:
      this compiler object for further call chaining.
      Throws:
      UnsupportedOperationException - if the compiler does not support integer versions.
      NullPointerException - if the target is null.
    • isFixJvmModulePathMismatch

      Get whether we will attempt to fix modules appearing on the classpath, or non-modules appearing on the module path.

      This enables correct classpath and module path detection when the test pack is a module but the code being compiled in the test is not, and vice versa. We need this because many build systems decide whether to populate the --module-path or the --classpath with JPMS-enabled dependencies based on whether the project under compilation is a JPMS module itself.

      This only applies if isInheritModulePath() or isInheritClassPath() is enabled, and only applies to the current JVM classpath and module path.

      Unless otherwise changed or specified, implementations should default to DEFAULT_FIX_JVM_MODULE_PATH_MISMATCH.

      Returns:
      true if enabled, or false if disabled.
    • fixJvmModulePathMismatch

      JctCompiler fixJvmModulePathMismatch(boolean fixJvmModulePathMismatch)
      Get whether we will attempt to fix modules appearing on the classpath, or non-modules appearing on the module path.

      Unless otherwise changed or specified, implementations should default to DEFAULT_FIX_JVM_MODULE_PATH_MISMATCH.

      Parameters:
      fixJvmModulePathMismatch - whether to enable the mismatch fixing or not.
      Returns:
      this compiler object for further call chaining.
    • isInheritClassPath

      Get whether the class path is inherited from the active JVM or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_INHERIT_CLASS_PATH.

      Returns:
      whether the current class path is being inherited or not.
    • inheritClassPath

      JctCompiler inheritClassPath(boolean inheritClassPath)
      Set whether the class path is inherited from the active JVM or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_INHERIT_CLASS_PATH.

      Parameters:
      inheritClassPath - true to include it, or false to exclude it.
      Returns:
      this compiler object for further call chaining.
    • isInheritModulePath

      Get whether the module path is inherited from the active JVM or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_INHERIT_MODULE_PATH.

      Returns:
      whether the module path is being inherited or not.
    • inheritModulePath

      JctCompiler inheritModulePath(boolean inheritModulePath)
      Set whether the module path is inherited from the active JVM or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_INHERIT_MODULE_PATH.

      Parameters:
      inheritModulePath - true to include it, or false to exclude it.
      Returns:
      this compiler object for further call chaining.
    • isInheritSystemModulePath

      Get whether the system module path is inherited from the active JVM or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_INHERIT_SYSTEM_MODULE_PATH.

      Returns:
      whether the system module path is being inherited or not.
    • inheritSystemModulePath

      JctCompiler inheritSystemModulePath(boolean inheritSystemModulePath)
      Set whether the system module path is inherited from the active JVM or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_INHERIT_SYSTEM_MODULE_PATH.

      Parameters:
      inheritSystemModulePath - true to include it, or false to exclude it.
      Returns:
      this compiler object for further call chaining.
    • getLocale

      Get the output locale.

      Unless otherwise changed or specified, implementations should default to DEFAULT_LOCALE.

      Returns:
      the output locale to use.
    • locale

      Set the output locale.

      Unless otherwise changed or specified, implementations should default to DEFAULT_LOCALE.

      Parameters:
      locale - the locale to use.
      Returns:
      this compiler for further call chaining.
    • getLogCharset

      Get the charset being used to write compiler logs with.

      Unless otherwise changed or specified, implementations should default to DEFAULT_LOG_CHARSET.

      Returns:
      the charset.
    • logCharset

      Set the charset being used to write compiler logs with.

      Unless otherwise changed or specified, implementations should default to DEFAULT_LOG_CHARSET.

      Parameters:
      logCharset - the charset to use.
      Returns:
      this compiler for further call chaining.
    • getFileManagerLoggingMode

      Get the current file manager logging mode.

      Unless otherwise changed or specified, implementations should default to DEFAULT_FILE_MANAGER_LOGGING_MODE.

      Returns:
      the current file manager logging mode.
    • fileManagerLoggingMode

      Set how to handle logging calls to underlying file managers.

      Unless otherwise changed or specified, implementations should default to DEFAULT_FILE_MANAGER_LOGGING_MODE.

      Parameters:
      fileManagerLoggingMode - the mode to use for file manager logging.
      Returns:
      this compiler for further call chaining.
    • getDiagnosticLoggingMode

      Get the current diagnostic logging mode.

      Unless otherwise changed or specified, implementations should default to DEFAULT_DIAGNOSTIC_LOGGING_MODE.

      Returns:
      the current diagnostic logging mode.
    • diagnosticLoggingMode

      Set how to handle diagnostic capture.

      Unless otherwise changed or specified, implementations should default to DEFAULT_DIAGNOSTIC_LOGGING_MODE.

      Parameters:
      diagnosticLoggingMode - the mode to use for diagnostic capture.
      Returns:
      this compiler for further call chaining.
    • getAnnotationProcessorDiscovery

      Get how to perform annotation processor discovery.

      Unless otherwise changed or specified, implementations should default to DEFAULT_ANNOTATION_PROCESSOR_DISCOVERY.

      Specifying any annotation processors explicitly with addAnnotationProcessors(Iterable) or addAnnotationProcessors(Processor...) will bypass this setting, treating it as being disabled.

      Returns:
      the processor discovery mode to use.
    • annotationProcessorDiscovery

      Set how to perform annotation processor discovery.

      Unless otherwise changed or specified, implementations should default to DEFAULT_ANNOTATION_PROCESSOR_DISCOVERY.

      Specifying any annotation processors explicitly with addAnnotationProcessors(Iterable) or addAnnotationProcessors(Processor...) will bypass this setting, treating it as being disabled.

      Parameters:
      annotationProcessorDiscovery - the processor discovery mode to use.
      Returns:
      this compiler for further call chaining.
    • getDebuggingInfo

      Get the debugging info that is enabled.

      Unless otherwise changed or specified, implementations should default to DEFAULT_DEBUGGING_INFO.

      Returns:
      the set of debugging info flags that are enabled.
      Since:
      3.0.0
    • debuggingInfo

      Set the debugging info level to use.
      Parameters:
      debuggingInfoFlags - the set of debugging info flags to enable.
      Returns:
      this compiler for further call chaining.
      Since:
      3.0.0
    • isParameterInfoEnabled

      Determine if including reflective parameter info is enabled or not.

      Unless otherwise changed or specified, implementations should default to DEFAULT_PARAMETER_INFO_ENABLED.

      Returns:
      the parameter info inclusion preference.
      Since:
      3.0.0
    • parameterInfoEnabled

      JctCompiler parameterInfoEnabled(boolean parameterInfoEnabled)
      Set whether to include parameter reflective info by default in compiled classes or not.
      Parameters:
      parameterInfoEnabled - whether to include the parameter reflective info or not.
      Returns:
      this compiler for further call chaining.
      Since:
      3.0.0