Package oracle.dbtools.plugin.api.di.annotations

Annotation Interface Provides

@Retention(RUNTIME)
@Target({TYPE,FIELD})
@RequestScoped
@Documented
public @interface Provides

Indicates that a class provides one or more services. By default, all the declared interfaces of the class are considered to be services provided by the class. If the class does not implement any interfaces then the service being offered is the class itself.

Classes annotated with Provides are discoverable by the Dependency Injection framework.

If necessary the set of services provided by a type can be explicitly specified using the value() property.

Examples

Type Provides self

 @Provides
 class Foo {
  ...
 }
 

Since Foo does not implement any interfaces then it provides itself as a service.

Type implicitly provides implementation of an interface

 @Provides
 class Foo implements Bar {
  ...
 }
 

Foo provides the service Bar.

Type explicitly provides implementation of an interface

 @Provides({Bar.class})
 class Foo extends AbstractBar {
  ...
 }
 

Foo is a specialization of the AbstractBar superclass that provides the Bar service.

 @Provides
 class Foo extends AbstractBar implements Bar{
  ...
 }
 

An alternate way to express Foo is a specialization of the AbstractBar superclass that provides the Bar service.

Type explicitly provides implementation of an interface, and self

 @Provides({Foo.class,Bar.class}}
 class Foo extends AbstractBar implements Bar{
  ...
 }
 

Foo provides the Bar service and also provides itself as a service.

Providing Static Fields

Static Constant fields in a type may be annotated with Provides to provide singleton instances of the field value. Alternatively if the type is declared as abstract it may be annotated with Provides and each constant field annotated with a Qualifier will bound into the scope. The provided service is the type of the constant field.

Examples

Type provides a configuration setting

 @Provides
 public abstract class SomePluginSettings {
  public static final String SOME_TIMEOUT_SETTING = "some.plugin.someTimeoutSetting";
  ...
  @Named(SomePluginSettings.SOME_TIMEOUT_SETTING);
  private static final ConfigurationSetting _SOME_SETTING = ConfigurationSetting.setting(TimeDuration.value("15m"));
 }
 

• The type is annotated with Provides but is marked abstract. This indicates that it is not the type itself that should be injected but rather any constant fields annotated with a Qualifier (in this case Named)
• Read more about injecting ConfigurationSettings in the oracle.dbtools.plugin.api.conf package summary

Type provides singleton instance of self

 public class SomeSingleton {
  private SomeSingleton() {}
  ...
  public static final SomeSingleton instance() { return INSTANCE; }
  @Provides
  private static final SomeSingleton INSTANCE = new SomeSingleton;
 }
 

• The type does not have Provides annotation
• The constant field containing the SomeSingleton instance is annotated with Provides. This single instance will be injected at every site declaring a dependency on SomeSingleton

Scoping

Provides is annotated with the RequestScoped scoping, meaning that a single instance of a type annotated with Provides will be created per scope. RequestScoped types do not need to be thread-safe, as they will only be referenced in a single thread.

If necessary a type can indicate that only a single instance should be created across all scopes by annotating the type with ApplicationScoped. Any such type must be thread-safe as the instance may be referenced across multiple threads. ApplicationScoped types cannot depend on any RequestScoped types.

 @Provides({GlobalService.class}}
 @ApplicationScoped
 class Singleton implements GlobalService{
  ...
 }
 

Author:

cdivilly

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<?>[]	value	The list of services this class provides.

Element Details

value

Class<?>[] value

The list of services this class provides.

Returns:

the set of services this class provides. If empty then the annotation processor should infer the set of services is the set of interfaces implemented by the service, or if the class implements no services, then the public API of the class becomes the service provided.

Default:

{}