001/*
002 * Copyright 2002-2019 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.beans.factory.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023import java.lang.annotation.Target;
024
025/**
026 * Marks a constructor, field, setter method, or config method as to be autowired by
027 * Spring's dependency injection facilities. This is an alternative to the JSR-330
028 * {@link javax.inject.Inject} annotation, adding required-vs-optional semantics.
029 *
030 * <p>Only one constructor of any given bean class may declare this annotation with
031 * the 'required' attribute set to {@code true}, indicating <i>the</i> constructor
032 * to autowire when used as a Spring bean. Furthermore, if the 'required' attribute
033 * is set to {@code true}, only a single constructor may be annotated with
034 * {@code @Autowired}. If multiple <i>non-required</i> constructors declare the
035 * annotation, they will be considered as candidates for autowiring. The constructor
036 * with the greatest number of dependencies that can be satisfied by matching beans
037 * in the Spring container will be chosen. If none of the candidates can be satisfied,
038 * then a primary/default constructor (if present) will be used. If a class only
039 * declares a single constructor to begin with, it will always be used, even if not
040 * annotated. An annotated constructor does not have to be public.
041 *
042 * <p>Fields are injected right after construction of a bean, before any config methods
043 * are invoked. Such a config field does not have to be public.
044 *
045 * <p>Config methods may have an arbitrary name and any number of arguments; each of
046 * those arguments will be autowired with a matching bean in the Spring container.
047 * Bean property setter methods are effectively just a special case of such a general
048 * config method. Such config methods do not have to be public.
049 *
050 * <p>In the case of a multi-arg constructor or method, the 'required' attribute is
051 * applicable to all arguments. Individual parameters may be declared as Java-8-style
052 * {@link java.util.Optional}, overriding the base required semantics.
053 *
054 * <p>In case of a {@link java.util.Collection} or {@link java.util.Map} dependency type,
055 * the container autowires all beans matching the declared value type. For such purposes,
056 * the map keys must be declared as type String which will be resolved to the corresponding
057 * bean names. Such a container-provided collection will be ordered, taking into account
058 * {@link org.springframework.core.Ordered}/{@link org.springframework.core.annotation.Order}
059 * values of the target components, otherwise following their registration order in the
060 * container. Alternatively, a single matching target bean may also be a generally typed
061 * {@code Collection} or {@code Map} itself, getting injected as such.
062 *
063 * <p>Note that actual injection is performed through a
064 * {@link org.springframework.beans.factory.config.BeanPostProcessor
065 * BeanPostProcessor} which in turn means that you <em>cannot</em>
066 * use {@code @Autowired} to inject references into
067 * {@link org.springframework.beans.factory.config.BeanPostProcessor
068 * BeanPostProcessor} or
069 * {@link org.springframework.beans.factory.config.BeanFactoryPostProcessor BeanFactoryPostProcessor}
070 * types. Please consult the javadoc for the {@link AutowiredAnnotationBeanPostProcessor}
071 * class (which, by default, checks for the presence of this annotation).
072 *
073 * @author Juergen Hoeller
074 * @author Mark Fisher
075 * @since 2.5
076 * @see AutowiredAnnotationBeanPostProcessor
077 * @see Qualifier
078 * @see Value
079 */
080@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
081@Retention(RetentionPolicy.RUNTIME)
082@Documented
083public @interface Autowired {
084
085        /**
086         * Declares whether the annotated dependency is required.
087         * <p>Defaults to {@code true}.
088         */
089        boolean required() default true;
090
091}