Package io.gdcc.spi.meta.processor

Class PluginContractProcessor

java.lang.Object
javax.annotation.processing.AbstractProcessor
io.gdcc.spi.meta.processor.PluginContractProcessor
All Implemented Interfaces:
Processor
public final class PluginContractProcessor extends AbstractProcessor
Annotation processor generating build-time metadata for plugin implementations.

This processor scans classes marked with @DataversePlugin, discovers all implemented plugin contracts annotated with @PluginContract, validates the contract graph, and emits:

  1. a per-plugin descriptor under "META-INF/dataverse/plugins/", and
  2. a META-INF/services/... entry for the base plugin contract when safe to do so.

Note: The processor enforces contract rules for all top-level and member interfaces in compiled source files. Runtime validation of contracts in PluginLoader loaded from external JARs or assembled outside normal compilation will catch illegal usage the processor cannot see and validate (like anonymous or method body interfaces).

The descriptor captures the build-time view of:

  • the plugin implementation class,
  • the plugin's base contract,
  • all implemented contract API levels,
  • all required provider API levels.

Contract graph rules

The processor enforces a strict contract hierarchy:

  • A base contract is the unique, directly loadable identity of a plugin. Base contracts may not extend other contracts and may not declare requires.
  • A capability contract adds optional functionality. It must declare exactly one base contract in requires. A capability may optionally extend its required base contract in the Java type hierarchy to provide default implementations for methods declared by the base. A capability may not extend another capability.

Service registration

Service registration generation is intentionally cautious. If any implementation of a given base contract uses @AutoService, this processor suppresses generated service output for that entire contract to avoid two processors writing the same META-INF/services/... file.

Errors are reported against the offending source element and then converted into a local PluginContractProcessor.ProcessorException. This aborts processing of the current implementation only, allowing the processor to continue and surface additional problems in the same compilation run.

  • Constructor Details

    • PluginContractProcessor

      public PluginContractProcessor()

  • Method Details

    • init

      public void init(ProcessingEnvironment processingEnv)
      Initializes compiler utility helpers from the processing environment.
      Specified by:
      init in interface Processor
      Overrides:
      init in class AbstractProcessor
      Parameters:
      processingEnv - the active annotation processing environment

    • getSupportedAnnotationTypes

      public Set<String> getSupportedAnnotationTypes()
      Returns the annotation types directly claimed by this processor.

      The processor claims all annotations because it does not only react to explicitly annotated @DataversePlugin classes. It also performs project-wide validation for plugin contracts, provider contracts, and unannotated plugin implementations discovered in the type model.

      Specified by:
      getSupportedAnnotationTypes in interface Processor
      Overrides:
      getSupportedAnnotationTypes in class AbstractProcessor
      Returns:
      the supported top-level annotation types

    • getSupportedSourceVersion

      public SourceVersion getSupportedSourceVersion()
      Advertises support for the latest source version understood by the current compiler.

      This is preferred over a hard-coded release because the processor mainly operates on the annotation/type model and should remain usable across newer Java releases automatically.

      Specified by:
      getSupportedSourceVersion in interface Processor
      Overrides:
      getSupportedSourceVersion in class AbstractProcessor
      Returns:
      the latest source version supported by the running compiler

    • process

      public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
      Main processor entry point for each annotation processing round.

      During normal rounds, this processor performs two tasks:

      1. it inspects all root types and their hierarchies for project-wide contract validation,
      2. it processes explicitly annotated @DataversePlugin classes.

      During the final round, all accumulated descriptor and service models are written to the compiler output.

      Specified by:
      process in interface Processor
      Specified by:
      process in class AbstractProcessor
      Parameters:
      annotations - the annotations requested for this round
      roundEnv - the current round environment
      Returns:
      false so other processors may continue to participate normally