Interface Instance<T>
-
- Type Parameters:
T
- the required bean type
- All Known Subinterfaces:
SeContainer
- All Known Implementing Classes:
CDI
public interface Instance<T> extends Iterable<T>, Provider<T>
Allows the application to dynamically obtain instances of beans with a specified combination of required type and qualifiers.
In certain situations, injection is not the most convenient way to obtain a contextual reference. For example, it may not be used when:
- the bean type or qualifiers vary dynamically at runtime, or
- depending upon the deployment, there may be no bean which satisfies the type and qualifiers, or
- we would like to iterate over all beans of a certain type.
In these situations, an instance of the
Instance
may be injected:@Inject Instance<PaymentProcessor> paymentProcessor;
Any combination of qualifiers may be specified at the injection point:
@Inject @PayBy(CHEQUE) Instance<PaymentProcessor> chequePaymentProcessor;
Or, the
@Any
qualifier may be used, allowing the application to specify qualifiers dynamically:@Inject @Any Instance<PaymentProcessor> anyPaymentProcessor;
For an injected
Instance
:- the required type is the type parameter specified at the injection point, and
- the required qualifiers are the qualifiers specified at the injection point.
The inherited
Provider.get()
method returns a contextual references for the unique bean that matches the required type and required qualifiers and is eligible for injection into the class into which the parentInstance
was injected, or throws anUnsatisfiedResolutionException
orAmbiguousResolutionException
.PaymentProcessor pp = chequePaymentProcessor.get();
The inherited
Iterable.iterator()
method returns an iterator over contextual references for beans that match the required type and required qualifiers and are eligible for injection into the class into which the parentInstance
was injected.for (PaymentProcessor pp : anyPaymentProcessor) pp.test();
- Author:
- Gavin King, John Ament, Martin Kouba
- See Also:
Provider.get()
,Iterable.iterator()
,AnnotationLiteral
,TypeLiteral
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
Instance.Handle<T>
This interface represents a contextual reference handle.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
destroy(T instance)
When called, the container destroys the instance if the active context object for the scope type of the bean supports destroying bean instances.Instance.Handle<T>
getHandle()
Obtains an initialized contextual reference handle for a bean that has the required type and qualifiers and is eligible for injection.Iterable<? extends Instance.Handle<T>>
handles()
Allows iterating over contextual reference handles for all beans that have the required type and required qualifiers and are eligible for injection.default Stream<? extends Instance.Handle<T>>
handlesStream()
Returns stream ofInstance.Handle
objects.boolean
isAmbiguous()
Determines if there is more than one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parentInstance
was injected.default boolean
isResolvable()
Determines if there is exactly one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parentInstance
was injected.boolean
isUnsatisfied()
Determines if there is no bean that matches the required type and qualifiers and is eligible for injection into the class into which the parentInstance
was injected.<U extends T>
Instance<U>select(TypeLiteral<U> subtype, Annotation... qualifiers)
Obtains a childInstance
for the given required type and additional required qualifiers.Instance<T>
select(Annotation... qualifiers)
Obtains a childInstance
for the given additional required qualifiers.<U extends T>
Instance<U>select(Class<U> subtype, Annotation... qualifiers)
Obtains a childInstance
for the given required type and additional required qualifiers.default Stream<T>
stream()
When called, provides back a Stream of the beans available in this Instance.-
Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
-
-
-
-
Method Detail
-
select
Instance<T> select(Annotation... qualifiers)
Obtains a child
Instance
for the given additional required qualifiers.- Parameters:
qualifiers
- the additional required qualifiers- Returns:
- the child
Instance
- Throws:
IllegalArgumentException
- if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier typeIllegalStateException
- if the container is already shutdown
-
select
<U extends T> Instance<U> select(Class<U> subtype, Annotation... qualifiers)
Obtains a child
Instance
for the given required type and additional required qualifiers.- Type Parameters:
U
- the required type- Parameters:
subtype
- aClass
representing the required typequalifiers
- the additional required qualifiers- Returns:
- the child
Instance
- Throws:
IllegalArgumentException
- if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier typeIllegalStateException
- if the container is already shutdown
-
select
<U extends T> Instance<U> select(TypeLiteral<U> subtype, Annotation... qualifiers)
Obtains a child
Instance
for the given required type and additional required qualifiers.- Type Parameters:
U
- the required type- Parameters:
subtype
- aTypeLiteral
representing the required typequalifiers
- the additional required qualifiers- Returns:
- the child
Instance
- Throws:
IllegalArgumentException
- if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier typeIllegalStateException
- if the container is already shutdown
-
stream
default Stream<T> stream()
When called, provides back a Stream of the beans available in this Instance. If no beans are found, it returns an empty stream.
- Returns:
- a
Stream
representing the beans associated with thisInstance
object - Since:
- 2.0
-
isUnsatisfied
boolean isUnsatisfied()
Determines if there is no bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent
Instance
was injected.- Returns:
true
if there is no bean that matches the required type and qualifiers and is eligible for injection into the class into which the parentInstance
was injected, orfalse
otherwise.
-
isAmbiguous
boolean isAmbiguous()
Determines if there is more than one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent
Instance
was injected.- Returns:
true
if there is more than one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parentInstance
was injected, orfalse
otherwise.
-
isResolvable
default boolean isResolvable()
Determines if there is exactly one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent
Instance
was injected.- Returns:
true
if there is exactly one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parentInstance
was injected, orfalse
otherwise.- Since:
- 2.0
-
destroy
void destroy(T instance)
When called, the container destroys the instance if the active context object for the scope type of the bean supports destroying bean instances. All normal scoped built-in contexts support destroying bean instances.
The instance passed should either be a dependent scoped bean instance obtained from the same
Instance
object, or the client proxy for a normal scoped bean instance.- Parameters:
instance
- the instance to destroy- Throws:
UnsupportedOperationException
- if the active context object for the scope type of the bean does not support destroying bean instances- Since:
- 1.1
-
getHandle
Instance.Handle<T> getHandle()
Obtains an initialized contextual reference handle for a bean that has the required type and qualifiers and is eligible for injection. Throws exceptions if there is no such bean or more than one.The contextual reference is obtained lazily, i.e. when first needed.
- Returns:
- a new
Instance.Handle
instnace - Throws:
UnsatisfiedResolutionException
- if there is no bean with given type and qualifiersAmbiguousResolutionException
- if there is more than one bean given type and qualifiers
-
handles
Iterable<? extends Instance.Handle<T>> handles()
Allows iterating over contextual reference handles for all beans that have the required type and required qualifiers and are eligible for injection.Note that the returned
Iterable
is stateless. Therefore, eachIterable.iterator()
produces a new set of handles.- Returns:
- a new iterable
-
handlesStream
default Stream<? extends Instance.Handle<T>> handlesStream()
Returns stream ofInstance.Handle
objects.- Returns:
- a new stream of contextual reference handles
-
-