Package io.gdcc.spi.meta.annotations

package io.gdcc.spi.meta.annotations

Annotations used to declare Dataverse plugin contracts, plugin implementations, and required core providers.

This package defines the author-facing SPI model:

• a base contract is the unique, directly loadable identity of a plugin,
• a capability contract adds optional functionality but is never loaded directly,
• a plugin implementation must implement exactly one base contract and may additionally implement compatible capabilities,
• a required provider declares Dataverse infrastructure contracts needed by a plugin contract.

Only base contracts are used as plugin loading identities.

Contract interfaces must extend Plugin, declare PluginContract, and provide a compile-time int API_LEVEL constant. Plugin contracts must not extend other plugin contracts (with the single exception of a capability extending a required base contract).

Capabilities are attached to a plugin through normal Java interface implementation. This allows SPI authors to provide additional methods and default implementations without introducing ambiguity into plugin loading. If multiple implemented interfaces contribute conflicting default methods, the plugin implementation class must resolve that conflict explicitly.

Example with extending base contract:

 @PluginContract(role = PluginContract.Role.BASE)
 public interface FooBar extends Plugin {
     int API_LEVEL = 1;
     String getMediaType();
 }

 @PluginContract(
     role = PluginContract.Role.CAPABILITY,
     requires = { FooBar.class }
 )
 public interface BarBeque extends FooBar {
     int API_LEVEL = 1;

     default String getMediaType() {
         return "application/bbq";
     }
 }

 @DataversePlugin
 public class Grill implements FooBar, BarBeque {
     // no override needed unless another default conflicts
 }
 

Class	Description
DataversePlugin	Marks a concrete plugin implementation class for metadata generation.
PluginContract	Declares a versioned plugin contract interface.
PluginContract.Role	Distinguishes directly loadable base contracts from additional capability contracts.
RequiredProvider	Declares that a PluginContract requires a specific core provider contract.