@Inherited
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface RestrictedBindingSource
Bindings restricted by this annotation may only be created by sources annotated with a permit
from permits()
-- otherwise, an error message including the explanation()
is
issued.
There are two kinds of binding source:
ModuleAnnotatedMethodScanner
): If a binding was created by a
scanner, then that scanner is also a source of the binding (in addition to the module
sources) and a permit may be given to the scanner by annotating its class.
Bindings with qualifier annotations are restricted solely by the annotation on their qualifier (restrictions on the type are ignored for qualified bindings). Unqualified bindings are restricted by the annotation on their type.
This allows libraries to prevent their clients from binding their keys, similar to how
declaring a class final prevents subtyping. For example, a library may want to prevent users from
creating mock bindings for tests, using the explanation()
- included in the error message
- to point them to a supported testing module.
Example usage:
{@code
Modifier and Type | Required Element and Description |
---|---|
java.lang.String |
explanation
Explanation of why binding this target type is restricted.
|
java.lang.Class<? extends java.lang.annotation.Annotation>[] |
permits
List of
Permit annotations (must be non-empty), one of which has has to be present on a
restricted binding's source (defined in top-level javadoc). |
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String |
exemptModules
Exempt modules whose fully qualified class names match this regex.
|
RestrictedBindingSource.RestrictionLevel |
restrictionLevel |
public abstract java.lang.String explanation
Will appear as the error message if the target type is bound by non-allowed modules.
public abstract java.lang.Class<? extends java.lang.annotation.Annotation>[] permits
Permit
annotations (must be non-empty), one of which has has to be present on a
restricted binding's source (defined in top-level javadoc).public abstract java.lang.String exemptModules
If any module on the binding's module stack matches this regex, the binding is allowed (no permit necessary). No module is exempt by default (empty string).
Inteded to be used when retrofitting a binding with this restriction. When restricting an existing binding, it's often practical to first restrict with exemptions for existing violations (to prevent new violations), before updating the code in violation to use the permitted module(s).
public abstract RestrictedBindingSource.RestrictionLevel restrictionLevel