Package org.int4.dirk.api

Interface CandidateRegistry

All Known Subinterfaces:

Injector

All Known Implementing Classes:

StandardInjector

public interface CandidateRegistry

Provides methods to manage injection candidates, like registering and removing.

Depending on the underlying store used certain invariants will be automatically enforced. For example, removing a candidate which is currently required as a dependency could result in an exception if the store is enforcing that all known candidates must be resolvable.

Depending on which extensions are active, more candidates will be derived from any given candidate when certain annotations or interfaces are implemented. For example, registering a candidate which has produces annotated members will also register the types produced. The same could apply to candidates implementing a provider interface.

Method Summary

Modifier and Type	Method	Description
boolean	contains(java.lang.reflect.Type type, java.lang.Object... qualifiers)	Returns true when the given type with the given qualifiers is present, otherwise false.
void	register(java.lang.reflect.Type type)	Registers a Type, and all its derived candidates if any, if all its dependencies can be resolved and it would not cause existing registered types to have ambiguous dependencies as a result of registering the given type.
void	register(java.util.Collection<java.lang.reflect.Type> types)	Registers the given Types, and all their derived candidates if any, if all their dependencies can be resolved and it would not cause existing registered types to have ambiguous dependencies as a result of registering the given types.
void	registerInstance(java.lang.Object instance, java.lang.annotation.Annotation... qualifiers)	Registers an instance, and all its derived candidates if any, as a singleton if it would not cause existing registered types to have ambiguous dependencies as a result.
void	remove(java.lang.reflect.Type type)	Removes the given Type, and all its derived candidates if any, if doing so would not result maintains all invariants for the remaining registered types.
void	remove(java.util.Collection<java.lang.reflect.Type> types)	Removes the given Types, all their derived candidates if any, if doing so would not result maintains all invariants for the remaining registered types.
void	removeInstance(java.lang.Object instance, java.lang.annotation.Annotation... qualifiers)	Removes an instance, and all its derived candidates if any, if doing so would not result in broken dependencies in the remaining registered types.

Method Detail

contains

boolean contains(java.lang.reflect.Type type,
                 java.lang.Object... qualifiers)

Returns true when the given type with the given qualifiers is present, otherwise false.

Parameters:

type - a type to check for, cannot be null

qualifiers - optional list of qualifier annotations, either Annotation or Class<? extends Annotation>

Returns:

true when the given type with the given criteria is present, otherwise false

register

void register(java.lang.reflect.Type type)
       throws AutoDiscoveryException,
              DefinitionException,
              DependencyException

Registers a Type, and all its derived candidates if any, if all its dependencies can be resolved and it would not cause existing registered types to have ambiguous dependencies as a result of registering the given type.

If there are unresolvable dependencies, or registering this type would result in ambiguous dependencies for previously registered types, then this method will throw an exception.

Parameters:

type - the type to register, cannot be null

Throws:

AutoDiscoveryException - when auto discovery fails to find all required types

DefinitionException - when a definition problem was encountered

DependencyException - when dependencies between registered types cannot be resolved

register

void register(java.util.Collection<java.lang.reflect.Type> types)
       throws AutoDiscoveryException,
              DefinitionException,
              DependencyException

Registers the given Types, and all their derived candidates if any, if all their dependencies can be resolved and it would not cause existing registered types to have ambiguous dependencies as a result of registering the given types.

If there are unresolvable dependencies, or registering these types would result in ambiguous dependencies for previously registered types, then this method will throw an exception.

Parameters:

types - a collection of types to register, cannot be null or contain nulls

Throws:

AutoDiscoveryException - when auto discovery fails to find all required types

DefinitionException - when a definition problem was encountered

DependencyException - when dependencies between registered types cannot be resolved

registerInstance

void registerInstance(java.lang.Object instance,
                      java.lang.annotation.Annotation... qualifiers)
               throws DefinitionException,
                      DependencyException

Registers an instance, and all its derived candidates if any, as a singleton if it would not cause existing registered types to have ambiguous dependencies as a result.

If registering this instance would result in ambiguous dependencies for previously registered classes, then this method will throw an exception.

Parameters:

instance - the instance to register with the Injector

qualifiers - optional list of qualifiers for this instance

Throws:

DefinitionException - when a definition problem was encountered

DependencyException - when dependencies between registered types cannot be resolved

remove

void remove(java.lang.reflect.Type type)
     throws AutoDiscoveryException,
            DefinitionException,
            DependencyException

Removes the given Type, and all its derived candidates if any, if doing so would not result maintains all invariants for the remaining registered types.

If there would be broken dependencies then the removal will fail and an exception is thrown.

Parameters:

type - the type to remove, cannot be null

Throws:

AutoDiscoveryException - when auto discovery fails to find all required types

DefinitionException - when a definition problem was encountered

DependencyException - when dependencies between registered types cannot be resolved

remove

void remove(java.util.Collection<java.lang.reflect.Type> types)
     throws AutoDiscoveryException,
            DefinitionException,
            DependencyException

Removes the given Types, all their derived candidates if any, if doing so would not result maintains all invariants for the remaining registered types.

If there would be broken dependencies then the removal will fail and an exception is thrown.

Parameters:

types - a collection of types to remove, cannot be null or contain nulls

Throws:

AutoDiscoveryException - when auto discovery fails to find all required types

DefinitionException - when a definition problem was encountered

DependencyException - when dependencies between registered types cannot be resolved

removeInstance

void removeInstance(java.lang.Object instance,
                    java.lang.annotation.Annotation... qualifiers)
             throws DefinitionException,
                    DependencyException

Removes an instance, and all its derived candidates if any, if doing so would not result in broken dependencies in the remaining registered types.

If there would be broken dependencies then the removal will fail and an exception is thrown.

Parameters:

instance - the instance to remove, cannot be null

qualifiers - optional list of qualifiers for this instance

Throws:

DefinitionException - when a definition problem was encountered

DependencyException - when dependencies between registered types cannot be resolved