Package org.springframework.beans.factory

# Interface ObjectProvider<T>

Type Parameters:
  `T` - the object type

All Superinterfaces:
  `Iterable<T>`, `ObjectFactory<T>`

public interface ObjectProvider<T> extends ObjectFactory<T>, Iterable<T>
A variant of `ObjectFactory` designed specifically for injection points, allowing for programmatic optionality and lenient not-unique handling.

In a `BeanFactory` environment, every `ObjectProvider` obtained from the factory will be bound to its `BeanFactory` for a specific bean type, matching all provider calls against factory-registered bean definitions. Note that all such calls dynamically operate on the underlying factory state, freshly resolving the requested target object on every call.

As of 5.1, this interface extends `Iterable` and provides `Stream` support. It can be therefore be used in `for` loops, provides `Iterable.forEach(java.util.function.Consumer<? super T>)` iteration and allows for collection-style `stream()` access.

As of 6.2, this interface declares default implementations for all methods. This makes it easier to implement in a custom fashion, for example, for unit tests. For typical purposes, implement `stream()` to enable all other methods. Alternatively, you may implement the specific methods that your callers expect, for example, just `getObject()` or `getIfAvailable()`.

Note that `getObject()` never returns `null` - it will throw a `NoSuchBeanDefinitionException` instead -, whereas `getIfAvailable()` will return `null` if no matching bean is present at all. However, both methods will throw a `NoUniqueBeanDefinitionException` if more than one matching bean is found without a clear unique winner (see below). Last but not least, `getIfUnique()` will return `null` both when no matching bean is found and when more than one matching bean is found without a unique winner.

Uniqueness is generally up to the container's candidate resolution algorithm but always honors the "primary" flag (with only one of the candidate beans marked as primary) and the "fallback" flag (with only one of the candidate beans not marked as fallback). The default-candidate flag is consistently taken into account as well, even for non-annotation-based injection points, with a single default candidate winning in case of no clear primary/fallback indication.

Since:
  4.3
Author:
  Juergen Hoeller
See Also:
  - `BeanFactory.getBeanProvider(java.lang.Class<T>)`
  - `Autowired`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Predicate<Class<?>>`
`UNFILTERED`
A predicate for unfiltered type matches, including non-default candidates but still excluding non-autowire candidates when used on injection points.

## Method Summary

Modifier and Type
Method
Description
`default T`
`getIfAvailable()`
Return an instance (possibly shared or independent) of the object managed by this factory.
`default T`
`getIfAvailable(Supplier<T> defaultSupplier)`
Return an instance (possibly shared or independent) of the object managed by this factory.
`default T`
`getIfUnique()`
Return an instance (possibly shared or independent) of the object managed by this factory.
`default T`
`getIfUnique(Supplier<T> defaultSupplier)`
Return an instance (possibly shared or independent) of the object managed by this factory.
`default T`
`getObject()`
Return an instance (possibly shared or independent) of the object managed by this factory.
`default T`
`getObject(Object... args)`
Return an instance (possibly shared or independent) of the object managed by this factory.
`default void`
`ifAvailable(Consumer<T> dependencyConsumer)`
Consume an instance (possibly shared or independent) of the object managed by this factory, if available.
`default void`
`ifUnique(Consumer<T> dependencyConsumer)`
Consume an instance (possibly shared or independent) of the object managed by this factory, if unique.
`default Iterator<T>`
`iterator()`
Return an `Iterator` over all matching object instances, without specific ordering guarantees (but typically in registration order).
`default Stream<T>`
`orderedStream()`
Return a sequential `Stream` over all matching object instances, pre-ordered according to the factory's common order comparator.
`default Stream<T>`
`orderedStream(Predicate<Class<?>> customFilter)`
Return a custom-filtered `Stream` over all matching object instances, pre-ordered according to the factory's common order comparator.
`default Stream<T>`
`orderedStream(Predicate<Class<?>> customFilter, boolean includeNonSingletons)`
Return a custom-filtered `Stream` over all matching object instances, pre-ordered according to the factory's common order comparator.
`default Stream<T>`
`stream()`
Return a sequential `Stream` over all matching object instances, without specific ordering guarantees (but typically in registration order).
`default Stream<T>`
`stream(Predicate<Class<?>> customFilter)`
Return a custom-filtered `Stream` over all matching object instances, without specific ordering guarantees (but typically in registration order).
`default Stream<T>`
`stream(Predicate<Class<?>> customFilter, boolean includeNonSingletons)`
Return a custom-filtered `Stream` over all matching object instances, without specific ordering guarantees (but typically in registration order).

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

## Field Details

### UNFILTERED

static final Predicate<Class<?>> UNFILTERED
A predicate for unfiltered type matches, including non-default candidates but still excluding non-autowire candidates when used on injection points.

Since:
  6.2.3
See Also:
  - `stream(Predicate)`
  - `orderedStream(Predicate)`
  - `BeanDefinition.isAutowireCandidate()`
  - `AbstractBeanDefinition.isDefaultCandidate()`

## Method Details

### getObject

default T getObject() throws BeansException
Description copied from interface: `ObjectFactory`
Return an instance (possibly shared or independent) of the object managed by this factory.

Specified by:
  `getObject` in interface `ObjectFactory<T>`
Returns:
  the resulting instance
Throws:
  `BeansException` - in case of creation errors

### getObject

default T getObject(Object... args) throws BeansException
Return an instance (possibly shared or independent) of the object managed by this factory.

Allows for specifying explicit construction arguments, along the lines of `BeanFactory.getBean(String, Object...)`.

Parameters:
  `args` - arguments to use when creating a corresponding instance
Returns:
  an instance of the bean
Throws:
  `BeansException` - in case of creation errors
See Also:
  - `getObject()`

### getIfAvailable

@Nullable default T getIfAvailable() throws BeansException
Return an instance (possibly shared or independent) of the object managed by this factory.

Returns:
  an instance of the bean, or `null` if not available
Throws:
  `BeansException` - in case of creation errors
See Also:
  - `getObject()`

### getIfAvailable

default T getIfAvailable(Supplier<T> defaultSupplier) throws BeansException
Return an instance (possibly shared or independent) of the object managed by this factory.

Parameters:
  `defaultSupplier` - a callback for supplying a default object if none is present in the factory
Returns:
  an instance of the bean, or the supplied default object if no such bean is available
Throws:
  `BeansException` - in case of creation errors
Since:
  5.0
See Also:
  - `getIfAvailable()`

### ifAvailable

default void ifAvailable(Consumer<T> dependencyConsumer) throws BeansException
Consume an instance (possibly shared or independent) of the object managed by this factory, if available.

Parameters:
  `dependencyConsumer` - a callback for processing the target object if available (not called otherwise)
Throws:
  `BeansException` - in case of creation errors
Since:
  5.0
See Also:
  - `getIfAvailable()`

### getIfUnique

@Nullable default T getIfUnique() throws BeansException
Return an instance (possibly shared or independent) of the object managed by this factory.

Returns:
  an instance of the bean, or `null` if not available or not unique (i.e. multiple candidates found with none marked as primary)
Throws:
  `BeansException` - in case of creation errors
See Also:
  - `getObject()`

### getIfUnique

default T getIfUnique(Supplier<T> defaultSupplier) throws BeansException
Return an instance (possibly shared or independent) of the object managed by this factory.

Parameters:
  `defaultSupplier` - a callback for supplying a default object if no unique candidate is present in the factory
Returns:
  an instance of the bean, or the supplied default object if no such bean is available or if it is not unique in the factory (i.e. multiple candidates found with none marked as primary)
Throws:
  `BeansException` - in case of creation errors
Since:
  5.0
See Also:
  - `getIfUnique()`

### ifUnique

default void ifUnique(Consumer<T> dependencyConsumer) throws BeansException
Consume an instance (possibly shared or independent) of the object managed by this factory, if unique.

Parameters:
  `dependencyConsumer` - a callback for processing the target object if unique (not called otherwise)
Throws:
  `BeansException` - in case of creation errors
Since:
  5.0
See Also:
  - `getIfUnique()`

### iterator

default Iterator<T> iterator()
Return an `Iterator` over all matching object instances, without specific ordering guarantees (but typically in registration order).

Specified by:
  `iterator` in interface `Iterable<T>`
Since:
  5.1
See Also:
  - `stream()`

### stream

default Stream<T> stream()
Return a sequential `Stream` over all matching object instances, without specific ordering guarantees (but typically in registration order).

Note: The result may be filtered by default according to qualifiers on the injection point versus target beans and the general autowire candidate status of matching beans. For custom filtering against type-matching candidates, use `stream(Predicate)` instead (potentially with `UNFILTERED`).

Since:
  5.1
See Also:
  - `iterator()`
  - `orderedStream()`

### orderedStream

default Stream<T> orderedStream()
Return a sequential `Stream` over all matching object instances, pre-ordered according to the factory's common order comparator.

In a standard Spring application context, this will be ordered according to `Ordered` conventions, and in case of annotation-based configuration also considering the `Order` annotation, analogous to multi-element injection points of list/array type.

The default method applies an `OrderComparator` to the `stream()` method. You may override this to apply an `AnnotationAwareOrderComparator` if necessary.

Note: The result may be filtered by default according to qualifiers on the injection point versus target beans and the general autowire candidate status of matching beans. For custom filtering against type-matching candidates, use `stream(Predicate)` instead (potentially with `UNFILTERED`).

Since:
  5.1
See Also:
  - `stream()`
  - `OrderComparator`

### stream

default Stream<T> stream(Predicate<Class<?>> customFilter)
Return a custom-filtered `Stream` over all matching object instances, without specific ordering guarantees (but typically in registration order).

Parameters:
  `customFilter` - a custom type filter for selecting beans among the raw bean type matches (or `UNFILTERED` for all raw type matches without any default filtering)
Since:
  6.2.3
See Also:
  - `stream()`
  - `orderedStream(Predicate)`

### orderedStream

default Stream<T> orderedStream(Predicate<Class<?>> customFilter)
Return a custom-filtered `Stream` over all matching object instances, pre-ordered according to the factory's common order comparator.

Parameters:
  `customFilter` - a custom type filter for selecting beans among the raw bean type matches (or `UNFILTERED` for all raw type matches without any default filtering)
Since:
  6.2.3
See Also:
  - `orderedStream()`
  - `stream(Predicate)`

### stream

default Stream<T> stream(Predicate<Class<?>> customFilter, boolean includeNonSingletons)
Return a custom-filtered `Stream` over all matching object instances, without specific ordering guarantees (but typically in registration order).

Parameters:
  `customFilter` - a custom type filter for selecting beans among the raw bean type matches (or `UNFILTERED` for all raw type matches without any default filtering)
  `includeNonSingletons` - whether to include prototype or scoped beans too or just singletons (also applies to FactoryBeans)
Since:
  6.2.5
See Also:
  - `stream(Predicate)`
  - `orderedStream(Predicate, boolean)`

### orderedStream

default Stream<T> orderedStream(Predicate<Class<?>> customFilter, boolean includeNonSingletons)
Return a custom-filtered `Stream` over all matching object instances, pre-ordered according to the factory's common order comparator.

Parameters:
  `customFilter` - a custom type filter for selecting beans among the raw bean type matches (or `UNFILTERED` for all raw type matches without any default filtering)
  `includeNonSingletons` - whether to include prototype or scoped beans too or just singletons (also applies to FactoryBeans)
Since:
  6.2.5
See Also:
  - `orderedStream()`
  - `stream(Predicate)`