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

Interface JctCompiler<C extends JctCompiler<C,R>,R extends JctCompilation>

Type Parameters:
C - the implementation type. This is provided to allow call-chaining the implementation.
R - the compilation type that gets returned once compilation completes.
All Known Implementing Classes:
AbstractJctCompiler
@API(since="0.0.1", status=STABLE) public interface JctCompiler<C extends JctCompiler<C,R>,R extends JctCompilation>
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

      R 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 R 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.
      IllegalStateException - if no compilation units were found.
      UncheckedIOException - if an IO error occurs.
      See Also:

    • compile

      R 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 generally.
      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> C 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

      C 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

      C 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 C 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

      C 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 C 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

      C 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 C 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

      C 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

      C 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

      C 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

      C 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

      C 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

      C 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

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

    • 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

      C 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 C 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 C 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

      C 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 C 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 C 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

      C 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

      C 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

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

    • isInheritPlatformClassPath

      @Deprecated(forRemoval=true, since="0.6.0") boolean isInheritPlatformClassPath()
      Deprecated, for removal: This API element is subject to removal in a future version.
      The platform class path has been mostly replaced by the use of system modules, so should not be used. This will be removed in v1.0.0.
      Get whether the current platform class path is being inherited from the caller JVM or not.

      This may also be known as the "bootstrap class path".

      Default environments probably will not provide this functionality, in which case it will be ignored.

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

      Returns:
      whether the platform class path is being inherited or not.

    • inheritPlatformClassPath

      @Deprecated(forRemoval=true, since="0.6.0") C inheritPlatformClassPath(boolean inheritPlatformClassPath)
      Deprecated, for removal: This API element is subject to removal in a future version.
      The platform class path has been mostly replaced by the use of system modules, so should not be used. This will be removed in v1.0.0.
      Set whether the current platform class path is being inherited from the caller JVM or not.

      This may also be known as the "bootstrap class path".

      Default environments probably will not provide this functionality, in which case it will be ignored.

      Parameters:
      inheritPlatformClassPath - 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

      C 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

      C 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

      C 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

      C 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

      C 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

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