/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory;

import java.util.Iterator;
import java.util.function.Consumer;
import java.util.function.Supplier;
import java.util.stream.Stream;

import org.springframework.beans.BeansException;
import org.springframework.lang.Nullable;

A variant of ObjectFactory designed specifically for injection points, allowing for programmatic optionality and lenient not-unique handling. 
As of 5.1, this interface extends Iterable and provides Stream support. It can be therefore be used in for loops, provides Iterable.forEach iteration and allows for collection-style stream access. 
Author:
Juergen Hoeller
Type parameters:
<T> – the object type
See Also:
BeanFactory.getBeanProvider
Autowired
Since:
4.3/**
 * A variant of {@link ObjectFactory} designed specifically for injection points,
 * allowing for programmatic optionality and lenient not-unique handling.
 *
 * <p>As of 5.1, this interface extends {@link Iterable} and provides {@link Stream}
 * support. It can be therefore be used in {@code for} loops, provides {@link #forEach}
 * iteration and allows for collection-style {@link #stream} access.
 *
 * @author Juergen Hoeller
 * @since 4.3
 * @param <T> the object type
 * @see BeanFactory#getBeanProvider
 * @see org.springframework.beans.factory.annotation.Autowired
 */
public interface ObjectProvider<T> extends ObjectFactory<T>, Iterable<T> {

	
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...). 
Params:
args – arguments to use when creating a corresponding instance
Throws:
BeansException – in case of creation errors
See Also:
ObjectFactory.getObject()
Returns:
an instance of the bean/**
	 * Return an instance (possibly shared or independent) of the object
	 * managed by this factory.
	 * <p>Allows for specifying explicit construction arguments, along the
	 * lines of {@link BeanFactory#getBean(String, Object...)}.
	 * @param args arguments to use when creating a corresponding instance
	 * @return an instance of the bean
	 * @throws BeansException in case of creation errors
	 * @see #getObject()
	 */
	T getObject(Object... args) throws BeansException;

	
Return an instance (possibly shared or independent) of the object
managed by this factory.
Throws:
BeansException – in case of creation errors
See Also:
ObjectFactory.getObject()
Returns:
an instance of the bean, or null if not available/**
	 * Return an instance (possibly shared or independent) of the object
	 * managed by this factory.
	 * @return an instance of the bean, or {@code null} if not available
	 * @throws BeansException in case of creation errors
	 * @see #getObject()
	 */
	@Nullable
	T getIfAvailable() throws BeansException;

	
Return an instance (possibly shared or independent) of the object
managed by this factory.
Params:
defaultSupplier – a callback for supplying a default object
if none is present in the factory
Throws:
BeansException – in case of creation errors
See Also:
getIfAvailable()
Returns:
an instance of the bean, or the supplied default object
if no such bean is available
Since:
5.0/**
	 * Return an instance (possibly shared or independent) of the object
	 * managed by this factory.
	 * @param defaultSupplier a callback for supplying a default object
	 * if none is present in the factory
	 * @return 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 #getIfAvailable()
	 */
	default T getIfAvailable(Supplier<T> defaultSupplier) throws BeansException {
		T dependency = getIfAvailable();
		return (dependency != null ? dependency : defaultSupplier.get());
	}

	
Consume an instance (possibly shared or independent) of the object
managed by this factory, if available.
Params:
dependencyConsumer – a callback for processing the target object
if available (not called otherwise)
Throws:
BeansException – in case of creation errors
See Also:
getIfAvailable()
Since:
5.0/**
	 * Consume an instance (possibly shared or independent) of the object
	 * managed by this factory, if available.
	 * @param dependencyConsumer a callback for processing the target object
	 * if available (not called otherwise)
	 * @throws BeansException in case of creation errors
	 * @since 5.0
	 * @see #getIfAvailable()
	 */
	default void ifAvailable(Consumer<T> dependencyConsumer) throws BeansException {
		T dependency = getIfAvailable();
		if (dependency != null) {
			dependencyConsumer.accept(dependency);
		}
	}

	
Return an instance (possibly shared or independent) of the object
managed by this factory.
Throws:
BeansException – in case of creation errors
See Also:
ObjectFactory.getObject()
Returns:
an instance of the bean, or null if not available or not unique (i.e. multiple candidates found with none marked as primary)/**
	 * Return an instance (possibly shared or independent) of the object
	 * managed by this factory.
	 * @return an instance of the bean, or {@code 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 #getObject()
	 */
	@Nullable
	T getIfUnique() throws BeansException;

	
Return an instance (possibly shared or independent) of the object
managed by this factory.
Params:
defaultSupplier – a callback for supplying a default object
if no unique candidate is present in the factory
Throws:
BeansException – in case of creation errors
See Also:
getIfUnique()
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)
Since:
5.0/**
	 * Return an instance (possibly shared or independent) of the object
	 * managed by this factory.
	 * @param defaultSupplier a callback for supplying a default object
	 * if no unique candidate is present in the factory
	 * @return 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 #getIfUnique()
	 */
	default T getIfUnique(Supplier<T> defaultSupplier) throws BeansException {
		T dependency = getIfUnique();
		return (dependency != null ? dependency : defaultSupplier.get());
	}

	
Consume an instance (possibly shared or independent) of the object
managed by this factory, if unique.
Params:
dependencyConsumer – a callback for processing the target object
if unique (not called otherwise)
Throws:
BeansException – in case of creation errors
See Also:
getIfAvailable()
Since:
5.0/**
	 * Consume an instance (possibly shared or independent) of the object
	 * managed by this factory, if unique.
	 * @param dependencyConsumer a callback for processing the target object
	 * if unique (not called otherwise)
	 * @throws BeansException in case of creation errors
	 * @since 5.0
	 * @see #getIfAvailable()
	 */
	default void ifUnique(Consumer<T> dependencyConsumer) throws BeansException {
		T dependency = getIfUnique();
		if (dependency != null) {
			dependencyConsumer.accept(dependency);
		}
	}

	
Return an Iterator over all matching object instances, without specific ordering guarantees (but typically in registration order). 
See Also:
stream()
Since:
5.1/**
	 * Return an {@link Iterator} over all matching object instances,
	 * without specific ordering guarantees (but typically in registration order).
	 * @since 5.1
	 * @see #stream()
	 */
	@Override
	default Iterator<T> iterator() {
		return stream().iterator();
	}

	
Return a sequential Stream over all matching object instances, without specific ordering guarantees (but typically in registration order). 
See Also:
iterator()
orderedStream()
Since:
5.1/**
	 * Return a sequential {@link Stream} over all matching object instances,
	 * without specific ordering guarantees (but typically in registration order).
	 * @since 5.1
	 * @see #iterator()
	 * @see #orderedStream()
	 */
	default Stream<T> stream() {
		throw new UnsupportedOperationException("Multi element access not supported");
	}

	
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. 
See Also:
stream()
OrderComparator
Since:
5.1/**
	 * Return a sequential {@link Stream} over all matching object instances,
	 * pre-ordered according to the factory's common order comparator.
	 * <p>In a standard Spring application context, this will be ordered
	 * according to {@link org.springframework.core.Ordered} conventions,
	 * and in case of annotation-based configuration also considering the
	 * {@link org.springframework.core.annotation.Order} annotation,
	 * analogous to multi-element injection points of list/array type.
	 * @since 5.1
	 * @see #stream()
	 * @see org.springframework.core.OrderComparator
	 */
	default Stream<T> orderedStream() {
		throw new UnsupportedOperationException("Ordered element access not supported");
	}

}