Package oracle.dbtools.plugin.api.di

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

See: Description

Interface Summary

Interface	Description
Annotations	Provides methods for working with annotations.
Annotations.Builder<T extends Annotation>	Builds new Annotation instances
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()
Instantiator<T>	Instantiates an instance of a specific type.

Class Summary

Class	Description
AnnotationsProvider	Provides methods for working with annotations.
PriorityComparator	Orders types based on their Priority annotations (if any)

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.

Package oracle.dbtools.plugin.api.di Description

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 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.

Accelerating Instantiation

For a dependency injection framework one of the bottlenecks is the overhead involved in instantiating types. For example instantiating a type via reflection can be several orders of magnitude slower than directly instantiating the type.

To address this overhead, this runtime provides the ability to delegate the job of instantiating a type to a specialized type that is able to efficiently instantiate the requested type. We call this specialized type an Instantiator.

During startup of the dependency injection runtime, all available instances of Instantiator are discovered and then used by the runtime to accelerate the instantiation of the corresponding type.

The AnnotationProcessor used by the dependency injection runtime will automatically generate an Instantiator implementation at compile time for any type annotated with Provides.

It is expected that only the annotation processor will create Instantiator sub-types. Manually defined Instantiator instances should not be created and will not be supported.

Author:

cdivilly