Package io.gdcc.spi.meta.annotations

package io.gdcc.spi.meta.annotations

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

For plugin implementors

The primary entry point in this package is @DataversePlugin. Plugin implementation classes intended for discovery and loading by Dataverse should declare this annotation.

A plugin implementation must implement exactly one base contract and may additionally implement compatible capability contracts. Only the base contract serves as the direct loading identity of the plugin.

Example: Plugin side

(The implemented interface are from the example below)

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

For SPI authors and maintainers

SPI contracts are declared with @PluginContract. A base contract defines the unique, directly loadable plugin kind. A capability contract defines additional optional behavior and is never loaded directly.

Contract interfaces must extend Plugin, declare PluginContract, and provide a compile-time int API_LEVEL constant. Plugin contracts must not extend other plugin contracts, except that a capability may extend its required base contract.

Required Dataverse infrastructure dependencies are declared with @RequiredProvider, which identifies core provider contracts needed by a plugin contract.

Capabilities are attached to a plugin through normal Java interface implementation. This allows SPI authors to define 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: Contract side

A capability extending its required 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";
     }
 }
 

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.