Instance

Type Parameters:

T - the required bean type

All Superinterfaces:

java.lang.Iterable<T>, Provider<T>

All Known Subinterfaces:

SeContainer

All Known Implementing Classes:

CDI
```
public interface Instance<T>
extends java.lang.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 parent Instance was injected, or throws an UnsatisfiedResolutionException or AmbiguousResolutionException.
```
 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 parent Instance was injected.
```
 for (PaymentProcessor pp : anyPaymentProcessor)
 pp.test();
 
```
See Also:

Provider.get(), Iterable.iterator(), AnnotationLiteral, TypeLiteral

Examples (en):

cdi-dynamic-inject

Examples (pt):

cdi-dynamic-inject

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface Instance.Handle<T>
This interface represents a contextual reference handle.

Nested Classes
Modifier and Type	Interface and 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 and 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.
`java.lang.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 java.util.stream.Stream<? extends Instance.Handle<T>>`	`handlesStream()` Returns stream of `Instance.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 parent `Instance` 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 parent `Instance` 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 parent `Instance` was injected.
`Instance<T>`	`select(java.lang.annotation.Annotation... qualifiers)` Obtains a child `Instance` for the given additional required qualifiers.
`<U extends T> Instance<U>`	`select(java.lang.Class<U> subtype, java.lang.annotation.Annotation... qualifiers)` Obtains a child `Instance` for the given required type and additional required qualifiers.
`<U extends T> Instance<U>`	`select(TypeLiteral<U> subtype, java.lang.annotation.Annotation... qualifiers)` Obtains a child `Instance` for the given required type and additional required qualifiers.
`default java.util.stream.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

Methods inherited from interface jakarta.inject.Provider
get

- Method Detail
 - select
```
Instance<T> select(java.lang.annotation.Annotation... qualifiers)
```
 Obtains a child Instance for the given additional required qualifiers.
 
 Parameters:
 
 qualifiers - the additional required qualifiers
 
 Returns:
 
 the child Instance
 
 Throws:
 
 java.lang.IllegalArgumentException - if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type
 
 java.lang.IllegalStateException - if the container is already shutdown
 - select
```
 Instance select(java.lang.Class subtype,
 java.lang.annotation.Annotation... qualifiers)
```
 Obtains a child Instance for the given required type and additional required qualifiers.
 
 Type Parameters:
 
 U - the required type
 
 Parameters:
 
 subtype - a Class representing the required type
 
 qualifiers - the additional required qualifiers
 
 Returns:
 
 the child Instance
 
 Throws:
 
 java.lang.IllegalArgumentException - if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type
 
 java.lang.IllegalStateException - if the container is already shutdown
 - select
```
 Instance select(TypeLiteral subtype,
 java.lang.annotation.Annotation... qualifiers)
```
 Obtains a child Instance for the given required type and additional required qualifiers.
 
 Type Parameters:
 
 U - the required type
 
 Parameters:
 
 subtype - a TypeLiteral representing the required type
 
 qualifiers - the additional required qualifiers
 
 Returns:
 
 the child Instance
 
 Throws:
 
 java.lang.IllegalArgumentException - if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type
 
 java.lang.IllegalStateException - if the container is already shutdown
 - stream
```
default java.util.stream.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 this Instance 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 parent Instance was injected, or false 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 parent Instance was injected, or false 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 parent Instance was injected, or false 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:
 
 java.lang.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 qualifiers
 
 AmbiguousResolutionException - if there is more than one bean given type and qualifiers
 - handles
```
java.lang.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, each Iterable.iterator() produces a new set of handles.
 
 Returns:
 
 a new iterable
 - handlesStream
```
default java.util.stream.Stream<? extends Instance.Handle<T>> handlesStream()
```
 Returns stream of Instance.Handle objects.
 
 Returns:
 
 a new stream of contextual reference handles

Interface Instance<T>

Nested Class Summary

Method Summary

Methods inherited from interface java.lang.Iterable

Methods inherited from interface jakarta.inject.Provider

Method Detail

select

select

select

stream

isUnsatisfied

isAmbiguous

isResolvable

destroy

getHandle

handles

handlesStream