Package org.int4.dirk.spi.instantiation

Interface Instance<T>

Type Parameters:

T - the type of the instances

public interface Instance<T>

Allows dynamic access to instances created by an injector. An Instance can be used to create instances of type T which match all its criteria. Sub Instances can be created which further narrow the set of possible matches.

Instances are created for specific injection targets. This target may be marked optional. If the target is optional, null is a valid result in case the Instance can provide no matches.

Method Summary

Modifier and Type	Method	Description
void	destroy(T instance)	Destroys an instance created with this Instance or one of its children.
void	destroyAll(java.util.Collection<T> instances)	Destroys a collection of instances created with this Instance or one of its children.
T	get()	Creates an instance of type T.
java.util.List<T>	getAll()	Creates all instances of type T.
Instance<T>	select(java.lang.annotation.Annotation... qualifiers)	Creates an Instance based on this one which further narrows the potential matching instances by requiring additional qualifiers.
<U extends T> Instance<U>	select(java.lang.Class<U> subtype, java.lang.annotation.Annotation... qualifiers)	Creates an Instance based on this one which further narrows the potential matching instances to a subtype of T and the given additional qualifiers.
<U extends T> Instance<U>	select(TypeLiteral<U> subtype, java.lang.annotation.Annotation... qualifiers)	Creates an Instance based on this one which further narrows the potential matching instances to a subtype of T and the given additional qualifiers.

Method Detail

get

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

Creates an instance of type T. If there are multiple matching instances an AmbiguousResolutionException exception is thrown. If the target for which this Instance was created is optional, then null is returned when there are no matches, otherwise an UnsatisfiedResolutionException is thrown.

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

getAll

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

Creates all instances of type T. If the target for which this Instance was created is optional, then null is returned when there are no matches, otherwise an empty list is returned.

Scoped types which scope is currently inactive are ignored, and so this call never produces scope related exceptions.

Returns:

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

Throws:

CreationException - when the creation of an instance failed

destroy

void destroy(T instance)

Destroys an instance created with this Instance or one of its children.

Parameters:

instance - an instance to destroy, cannot be null

destroyAll

void destroyAll(java.util.Collection<T> instances)

Destroys a collection of instances created with this Instance or one of its children.

Parameters:

instances - a collection of instances to destroy, cannot be null

select

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

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

Parameters:

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

Returns:

an Instance, never null

Throws:

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

select

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

Creates an Instance based on this one 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 Instance, never null

Throws:

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

select

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

Creates an Instance based on this one 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 - specifies a subtype of type T, cannot be null

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

Returns:

an Instance, never null

Throws:

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