# Package oracle.dbtools.plugin.api.di

A `javax.inject` compatible Dependency Injection (D.I.) framework.

### Injecting Dependencies

A type can declare dependencies on other types via an `@Inject` annotated constructor. Field and method based injection are *NOT* supported. For example:

     public class SomeService {

       @Inject
       SomeService(final SomeOtherType dependency) {
         this.dependency = dependency;
       }

       public String doSomething(final String input) {
         final String result = dependency.doSomethingElse(input);
         return result;
       }

       private final SomeOtherType dependency;
     }

#### Optional Dependencies

An injection site can be marked optional, by annotating it with the `Optional` annotation, for example:

     public class SomeService {
      @Inject
      SomeService(@Optional final SomeDependency dependency) {
        this.dependency = dependency;
      }
      ...
     }

If an injection site is optional and no instance of the requested dependency can be located, then a `null` value is injected instead.

#### Multiple Dependencies

An injection site can inject multiple providers of a service, by injecting a parameterized `Iterable` instance. For example:

     public class SomeService {
      @Inject
      SomeService(final Iterable<ServiceType> providers) {
        this.providers = providers;
      }
      ...
     }

If there are no providers of the requested service type available, then an empty `Iterable` will be injected.

The provided `Iterable` instance is immutable.

#### Provider Injection

Instead of injecting a dependency directly an injection site can inject a parameterized `javax.inject.Provider` instance, for example:

     public class SomeService {
      @Inject SomeService(final Provider<CyclicDependency> provider) {
        this.provider = provider;
      }

      public void doSomething() {
        final CyclicDependency dependency = provider.get();
        // Use CyclicDependency
        ...
      }
      private final Provider<CyclicDependency> provider;
     }

### Available Dependencies

The set of out of the box services that the dependency injection runtime provides are documented by the `AvailableDependencies` type.

### Advertising Services

A type can advertise to the dependency injection runtime that it is available to provide one more dependencies (aka services) by using the `Provides` annotation. Consult the `Provides` documentation for more information on how the set of services provided by a type is inferred (or alternatively specified explicitly if necessary).

### Dynamic Dependency Location

For some uses cases it can be useful to be able to discover dependencies at runtime rather than always having to inject them directly via an @Inject annotated constructor.

The `InstanceLocator` and `InstanceProvider` types provide the means to do these kinds of operations.

Author:
  cdivilly

- Interface Summary
  Interface | Description
  --- | ---
  Annotations | Provides methods for working with annotations.
  Annotations.Builder<T extends java.lang.annotation.Annotation> | Builds new `Annotation` instances
  DependencyInjectionModule | A Module is a collection of related services
  InstanceLocator | Allows the application to dynamically obtain instances of services with a specified combination of required type and qualifiers.
  InstanceProvider<T> | `Provider` specialization that provides the ability to: determine if a provider implementation was found, via `InstanceProvider.isUnsatisfied()` determine if there are multiple implementations found, via `InstanceProvider.isAmbiguous()` Iterate over the available implementations, via `InstanceProvider.iterator()` Stream through available implementations, via `InstanceProvider.stream()`
  Instantiator<T> | Deprecated. Alternative techniques for accelerating dependency injection make the use of this interface redundant
  ScopeConfiguration | Provides the capability to inject additional services and instances into a scope

- Class Summary
  Class | Description
  --- | ---
  AnnotationsProvider | Provides methods for working with annotations.
  DeferredInstanceProvider<T> | `InstanceProvider` implementation that defers resolving an instance until `DeferredInstanceProvider.get()`, `DeferredInstanceProvider.hasMultiple()`, `DeferredInstanceProvider.isUnsatisfied()`, or `DeferredInstanceProvider.iterator()` is invoked
  Instances | Locates concrete instances of types
  Instances.Builder | Build `Instances` instances
  Instances.QualifiedInstance<T> | Represents an individual instance of a qualified service
  ModuleDependencies | Enumerates the set of `DependencyInjectionModule`s that a given `DependencyInjectionModule` depends on
  ModuleDependencies.Builder |
  PriorityComparator | Orders types based on their `Priority` annotations (if any)
  ResolvedInstances<T> | Represents the discovered matches for a call to `InstanceLocator.select(TypeQualifier)`

- Enum Summary
  Enum | Description
  --- | ---
  AvailableDependencies | Enumerates the publicly available services that can be injected into plugins via the `Inject` annotation on a type's constructor.

- Exception Summary
  Exception | Description
  --- | ---
  DeferredInstanceProviderCycleException | `IllegalStateException` specialization raised when an attempt is made using a `DeferredInstanceProvider` to locate an instance of itself, which would cause a circular reference