Package io.gdcc.spi.meta.annotations

Annotation Interface PluginContract

@Retention(RUNTIME)
@Target(TYPE)
public @interface PluginContract

Declares a versioned plugin contract interface.

A plugin contract defines either a directly loadable plugin kind (PluginContract.Role.BASE) or an additional, non-loadable capability (PluginContract.Role.CAPABILITY).

The annotated type must be an interface extending Plugin and must declare a compile-time constant primitive int API_LEVEL field.

General contract rules:

1. Plugin contracts may only be declared on interfaces.
2. Plugin contracts must extend Plugin.
3. Plugin contracts may not extend other plugin contracts. (One exception, see below.)
4. A plugin implementation may implement exactly one base contract.

Base contracts are used as the unique service-loading identity of a plugin. Capability contracts are never loaded directly; they add optional functionality and are discovered through generated plugin metadata.

Capability rules:

1. A capability contract must declare requires().
2. A capability must require exactly one base contract.
3. A capability may extend the required base contract to provide default implementations.
4. For now, requiring or extending another capability is not supported.
5. A plugin implementing a capability must also implement its required base contract.

Note: this annotation cannot be used repeatedly on the same type.

Implementation Note:

Example base contract:

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

Example capability contract:

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

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	PluginContract.Role	Distinguishes directly loadable base contracts from additional capability contracts.

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
PluginContract.Role	role	Declares whether this contract is a directly loadable base contract or an additional capability contract.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
RequiredProvider[]	providers	Core provider contracts required by this plugin contract.
Class<? extends Plugin>[]	requires	Other plugin contracts that must also be implemented when this contract is implemented.

Element Details

role

PluginContract.Role role

Declares whether this contract is a directly loadable base contract or an additional capability contract.

requires

Class<? extends Plugin>[] requires

Other plugin contracts that must also be implemented when this contract is implemented.

For capabilities, this must currently contain exactly one required base contract. Capabilities are not directly loadable and therefore must always be paired with their base contract.

Default:

{}

providers

RequiredProvider[] providers

Core provider contracts required by this plugin contract.

Default:

{}