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 jakarta.inject.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 java.lang.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();

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	Instance.Handle< the required bean type T> This interface represents a contextual reference handle.

Method Summary

Modifier and Type	Method and Description
public void	destroy(T the instance to destroy instance) When called, the container destroys the instance if the active context object for the scope type of the bean supports destroying bean instances.
public Instance.Handle<T>	Returns: a new `Handle` instnace getHandle() Obtains an initialized contextual reference handle for a bean that has the required type and qualifiers and is eligible for injection.
public Iterable<? extends Instance.Handle<T>>	Returns: a new iterable handles() Allows iterating over contextual reference handles for all beans that have the required type and required qualifiers and are eligible for injection.
public default Stream<? extends Instance.Handle<T>>	Returns: a new stream of contextual reference handles handlesStream() Returns stream of `Handle` objects.
public boolean	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. 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.
public default boolean	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. 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.
public boolean	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. 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.
public Instance<T>	Returns: the child `Instance` select(Annotation... the additional required qualifiers qualifiers) Obtains a child `Instance` for the given additional required qualifiers.
public < the required type U extends T> Instance<U>	Returns: the child `Instance` select(Class<U> a `java.lang.Class` representing the required type subtype, Annotation... the additional required qualifiers qualifiers) Obtains a child `Instance` for the given required type and additional required qualifiers.
public < the required type U extends T> Instance<U>	Returns: the child `Instance` select(TypeLiteral<U> a `TypeLiteral` representing the required type subtype, Annotation... the additional required qualifiers qualifiers) Obtains a child `Instance` for the given required type and additional required qualifiers.
public default Stream<T>	Returns: a `Stream` representing the beans associated with this `Instance` object stream() When called, provides back a Stream of the beans available in this Instance.

Inherited from jakarta.inject.Provider:: get
Inherited from java.lang.Iterable:: forEach iterator spliterator

Method Detail

destroy back to summary

destroy	back to summary
public 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:T the instance to destroy Exceptions UnsupportedOperationException: if the active context object for the scope type of the bean does not support destroying bean instances Since 1.1

public 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:T: the instance to destroy

Exceptions

UnsupportedOperationException:: if the active context object for the scope type of the bean does not support destroying bean instances

Since

1.1

getHandle back to summary

getHandle	back to summary
public 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:Instance.Handle<T> a new `Handle` instnace Exceptions UnsatisfiedResolutionException: if there is no bean with given type and qualifiers AmbiguousResolutionException: if there is more than one bean given type and qualifiers

public 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:Instance.Handle<T>

a new Handle instnace

Exceptions

UnsatisfiedResolutionException:: if there is no bean with given type and qualifiers
AmbiguousResolutionException:: if there is more than one bean given type and qualifiers

handles back to summary

handles	back to summary
public 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:Iterable<? extends Instance.Handle<T>> a new iterable

public 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:Iterable<? extends Instance.Handle<T>>: a new iterable

handlesStream back to summary

handlesStream	back to summary
public default Stream<? extends Instance.Handle<T>> handlesStream() Returns stream of `Handle` objects. Returns:Stream<? extends Instance.Handle<T>> a new stream of contextual reference handles

public default Stream<? extends Instance.Handle<T>> handlesStream()

Returns stream of Handle objects.

Returns:Stream<? extends Instance.Handle<T>>: a new stream of contextual reference handles

isAmbiguous back to summary

isAmbiguous	back to summary
public 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:boolean `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.

public 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:boolean: 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 back to summary

isResolvable	back to summary
public 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:boolean `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

public 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:boolean: 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

isUnsatisfied back to summary

isUnsatisfied	back to summary
public 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:boolean `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.

public 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:boolean: 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.

select back to summary

select	back to summary
public Instance<T> select(Annotation... qualifiers) Obtains a child `Instance` for the given additional required qualifiers. Parameters qualifiers:Annotation[] the additional required qualifiers Returns:Instance<T> the child `Instance` Exceptions IllegalArgumentException: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type IllegalStateException: if the container is already shutdown

public Instance<T> select(Annotation... qualifiers)

Obtains a child Instance for the given additional required qualifiers.

Parameters

qualifiers:Annotation[]: the additional required qualifiers

Returns:Instance<T>

the child Instance

Exceptions

IllegalArgumentException:: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type
IllegalStateException:: if the container is already shutdown

select back to summary

select	back to summary
public <U extends T> Instance<U> select(Class<U> subtype, Annotation... qualifiers) Obtains a child `Instance` for the given required type and additional required qualifiers. Parameters <U> the required type subtype:Class<U> a `java.lang.Class` representing the required type qualifiers:Annotation[] the additional required qualifiers Returns:Instance<U> the child `Instance` Exceptions IllegalArgumentException: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type IllegalStateException: if the container is already shutdown

public Instance select(Class subtype, Annotation... qualifiers)

Obtains a child Instance for the given required type and additional required qualifiers.

Parameters

: the required type
subtype:Class: a java.lang.Class representing the required type
qualifiers:Annotation[]: the additional required qualifiers

Returns:Instance

the child Instance

Exceptions

IllegalArgumentException:: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type
IllegalStateException:: if the container is already shutdown

select back to summary

select	back to summary
public <U extends T> Instance<U> select(TypeLiteral<U> subtype, Annotation... qualifiers) Obtains a child `Instance` for the given required type and additional required qualifiers. Parameters <U> the required type subtype:TypeLiteral<U> a `TypeLiteral` representing the required type qualifiers:Annotation[] the additional required qualifiers Returns:Instance<U> the child `Instance` Exceptions IllegalArgumentException: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type IllegalStateException: if the container is already shutdown

public Instance select(TypeLiteral subtype, Annotation... qualifiers)

Obtains a child Instance for the given required type and additional required qualifiers.

Parameters

: the required type
subtype:TypeLiteral: a TypeLiteral representing the required type
qualifiers:Annotation[]: the additional required qualifiers

Returns:Instance

the child Instance

Exceptions

IllegalArgumentException:: if passed two instances of the same non repeating qualifier type, or an instance of an annotation that is not a qualifier type
IllegalStateException:: if the container is already shutdown

stream back to summary

stream	back to summary
public 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:Stream<T> a `Stream` representing the beans associated with this `Instance` object Since 2.0

public 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:Stream<T>: a Stream representing the beans associated with this Instance object
Since: 2.0

jakarta.enterprise.inject back to summary

public Interface Instance.Handle<T>

Type Parameters

extends AutoCloseable

<T>: the required bean type

This interface represents a contextual reference handle.

Allows to inspect the metadata of the relevant bean before resolving its contextual reference and also to destroy the underlying contextual instance.

Author: Matej Novotny

Method Summary

Modifier and Type	Method and Description
public void	close() Redeclares java.lang.AutoCloseable.close. Delegates to `destroy()`.
public void	destroy() Destroy the contextual instance.
public T	Returns: the contextual reference get() The contextual reference is obtained lazily, i.e. when first needed.
public Bean<T>	Returns: the bean metadata getBean()

Method Detail

close back to summary

close	back to summary
public void close() Redeclares java.lang.AutoCloseable.close. Delegates to `destroy()`. Annotations @Override

public void close()

Redeclares java.lang.AutoCloseable.close.

Delegates to destroy().

Annotations

@Override

destroy back to summary

destroy	back to summary
public void destroy() Destroy the contextual instance. It's a no-op if: called multiple times if the producing `Instance` does not exist if the handle does not hold a contextual reference, i.e. `get()` was never called See Also `Instance#destroy(Object)`

public void destroy()

Destroy the contextual instance. It's a no-op if:

called multiple times
if the producing Instance does not exist
if the handle does not hold a contextual reference, i.e. get() was never called

See Also: Instance#destroy(Object)

get back to summary

get	back to summary
public T get() The contextual reference is obtained lazily, i.e. when first needed. Returns:T the contextual reference Exceptions IllegalStateException: If the producing `Instance` does not exist If invoked on `Handle` that previously successfully destroyed its underlying contextual reference See Also `Instance#get()`

public T get()

The contextual reference is obtained lazily, i.e. when first needed.

Returns:T

the contextual reference

Exceptions

IllegalStateException:

If the producing Instance does not exist
If invoked on Handle that previously successfully destroyed its underlying contextual reference

See Also

Instance#get()

getBean	back to summary
public Bean<T> getBean() Returns:Bean<T> the bean metadata

public Interface Instance<T>

Nested and Inner Type Summary

Method Summary

Method Detail

public Interface Instance.Handle<T>

Method Summary

Method Detail