Module io.github.ascopes.jct
Package io.github.ascopes.jct.compilers

Interface JctCompiler

All Known Implementing Classes:
AbstractJctCompiler
@API(since="0.0.1", status=STABLE) public interface JctCompiler
Base definition of a compiler that can be configured to perform a compilation run against sources. This is designed to provide functionality that javac does by default, for JDK 17.
Since:
0.0.1
Author:
Ashley Scopes

  • Field Details

  • Method Details

    • compile

      JctCompilation compile(Workspace workspace)
      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, 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 firstClassName, String... additionalClassNames)
      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.

      Parameters:
      workspace - the workspace to compile.
      firstClassName - the first class name to compile.
      additionalClassNames - any additional 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.
      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.

      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 that can throw a checked exception.
      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.

    • getName

      String getName()
      Get the friendly printable name of this compiler object.
      Returns:
      the name of the compiler.

    • name

      JctCompiler name(String name)
      Set the friendly name of this compiler.
      Parameters:
      name - the name to set.
      Returns:
      this compiler object for further call chaining.

    • getAnnotationProcessorOptions

      List<String> 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

      JctCompiler addAnnotationProcessorOptions(Iterable<String> annotationProcessorOptions)
      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 annotationProcessorOption, String... annotationProcessorOptions)
      Add options to pass to any annotation processors.
      Parameters:
      annotationProcessorOption - the first option to pass.
      annotationProcessorOptions - additional options to pass.
      Returns:
      this compiler object for further call chaining.

    • getAnnotationProcessors

      List<Processor> 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.

      This bypasses the discovery process of annotation processors provided in the annotation processor path.

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

    • addAnnotationProcessors

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

      This bypasses the discovery process of annotation processors provided in the annotation processor path.

      Parameters:
      annotationProcessor - the first processor to invoke.
      annotationProcessors - additional processors to invoke.
      Returns:
      this compiler object for further call chaining.

    • getCompilerOptions

      List<String> getCompilerOptions()
      Get an immutable snapshot view of the current compiler options that are set.
      Returns:
      the current compiler options that are set.

    • addCompilerOptions

      JctCompiler addCompilerOptions(Iterable<String> compilerOptions)
      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 compilerOption, String... compilerOptions)
      Add command line options to pass to javac.
      Parameters:
      compilerOption - the first option to add.
      compilerOptions - additional 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

      boolean 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 preview features or not.

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

      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

      boolean 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

      JctCompiler showDeprecationWarnings(boolean enabled)
      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.

      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

      CompilationMode 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

      JctCompiler compilationMode(CompilationMode compilationMode)
      Set the compilation mode to use for this compiler.

      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

      String getDefaultRelease()
      Get the default release to use if no release or target version is specified.

      This can not be configured.

      Returns:
      the default release version to use.

    • getEffectiveRelease

      String getEffectiveRelease()
      Get the effective release to use for the actual compilation.

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

      Returns:
      the effective release.

    • getRelease

      String getRelease()
      Get the current release 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 release version string, if set.

    • release

      JctCompiler release(String release)
      Set the release version.

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

      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.

      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(SourceVersion release)
      Set the release version.

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

      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.

    • useRuntimeRelease

      @API(since="1.1.0", status=STABLE) default JctCompiler useRuntimeRelease()
      Request that the compiler uses a language version that corresponds to the runtime language version in use on the JVM running tests.

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

      This calls internally.

      Returns:
      this compiler object for further call chaining.

    • getSource

      String 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

      JctCompiler source(String 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.

      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.

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

    • 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.

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

    • getTarget

      String 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

      JctCompiler target(String 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.

      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.

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

    • 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.

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

    • isFixJvmModulePathMismatch

      boolean 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 flat 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

      boolean isInheritClassPath()
      Get whether the class path is inherited from the caller 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 caller 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

      boolean isInheritModulePath()
      Get whether the module path is inherited from the caller 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 caller 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

      boolean isInheritSystemModulePath()
      Get whether the system module path is inherited from the caller 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 caller 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

      Locale getLocale()
      Get the output locale.

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

      Returns:
      the output locale to use.

    • locale

      JctCompiler locale(Locale 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

      Charset 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

      JctCompiler logCharset(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

      LoggingMode 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

      JctCompiler fileManagerLoggingMode(LoggingMode 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

      LoggingMode 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

      JctCompiler diagnosticLoggingMode(LoggingMode 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

      AnnotationProcessorDiscovery 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, Processor...) will bypass this setting, treating it as being disabled.

      Returns:
      the processor discovery mode to use.

    • annotationProcessorDiscovery

      JctCompiler annotationProcessorDiscovery(AnnotationProcessorDiscovery 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, 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.