oracle.dbtools.plugin.api.di.annotations

## Annotation Type Provides

-     @Retention(value=RUNTIME)
       @Target(value={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 `ConfigurationSetting`s 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 and Description
    --- | ---
    `Class<?>[]` | `value` The list of services this class provides.

- - ### Element Detail

    - #### value

          public abstract 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:
        {}

Copyright © 2010, 2022, Oracle and/or its affiliates.