Package org.int4.dirk.spi.instantiation

Interface InstantiationContext<T>

Type Parameters:

T - the type of the instances

public interface InstantiationContext<T>

A context which can be used to create instances of type T which match all its criteria. Sub contexts can be created which further narrow the set of possible matches.

Contexts are often created for a specific injection target. This target may allow optional injection. If optional injection is allowed, null is a valid result in case there are no matches.

Method Summary

Modifier and Type	Method	Description
T	create()	Creates an instance of type T.
java.util.List<T>	createAll()	Creates all instances of type T this context can provide.
InstantiationContext<T>	select(java.lang.annotation.Annotation... qualifiers)	Creates an InstantiationContext based on this context which further narrows the potential matching instances by requiring additional qualifiers.
<U extends T> InstantiationContext<U>	select(java.lang.Class<U> subtype, java.lang.annotation.Annotation... qualifiers)	Creates an InstantiationContext based on this context which further narrows the potential matching instances to a subtype of T and the given additional qualifiers.
<U extends T> InstantiationContext<U>	select(java.lang.reflect.Type subtype, java.lang.annotation.Annotation... qualifiers)	Creates an InstantiationContext based on this context which further narrows the potential matching instances to a subtype of T and the given additional qualifiers.

Method Detail

create

T create()
  throws CreationException,
         UnsatisfiedResolutionException,
         AmbiguousResolutionException,
         ScopeNotActiveException

Creates an instance of type T. If there are multiple matching instances key given an AmbiguousResolutionException exception is thrown. Returns null if there are no matches and null is a considered valid result for this context.

Returns:

an instance or null if there were no matches

Throws:

CreationException - when the creation of the instance failed

UnsatisfiedResolutionException - when nothing matched and null is not valid

AmbiguousResolutionException - when their are multiple potential instances

ScopeNotActiveException - when the scope for the given type is not active

createAll

java.util.List<T> createAll()
                     throws CreationException

Creates all instances of type T this context can provide. If there were no matches null is returned if valid for this context, otherwise returns an empty list. Scoped types which scope is currently inactive are excluded.

Returns:

a list of instances, can be null or empty but never contains null

Throws:

CreationException - when the creation of an instance failed

select

InstantiationContext<T> select(java.lang.annotation.Annotation... qualifiers)

Creates an InstantiationContext based on this context which further narrows the potential matching instances by requiring additional qualifiers.

Parameters:

qualifiers - an array of additional qualifier Annotations, cannot be null

Returns:

an InstantiationContext, never null

Throws:

java.lang.IllegalArgumentException - if any of the given annotation is not a qualifier

select

<U extends T> InstantiationContext<U> select(java.lang.Class<U> subtype,
                                             java.lang.annotation.Annotation... qualifiers)

Creates an InstantiationContext based on this context which further narrows the potential matching instances to a subtype of T and the given additional qualifiers.

Type Parameters:

U - a subtype of type T

Parameters:

subtype - a subtype of type T, cannot be null

qualifiers - an array of additional qualifier Annotations, cannot be null

Returns:

an InstantiationContext, never null

Throws:

java.lang.IllegalArgumentException - if any of the given annotation is not a qualifier

select

<U extends T> InstantiationContext<U> select(java.lang.reflect.Type subtype,
                                             java.lang.annotation.Annotation... qualifiers)

Creates an InstantiationContext based on this context which further narrows the potential matching instances to a subtype of T and the given additional qualifiers.

Type Parameters:

U - a subtype of type T

Parameters:

subtype - a subtype of type T, cannot be null

qualifiers - an array of additional qualifier Annotations, cannot be null

Returns:

an InstantiationContext, never null

Throws:

java.lang.IllegalArgumentException - if any of the given annotation is not a qualifier

java.lang.IllegalArgumentException - if the given type is not a subtype of T