001/* 002 * Copyright 2002-2020 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.context.annotation; 018 019import java.lang.annotation.Documented; 020import java.lang.annotation.ElementType; 021import java.lang.annotation.Repeatable; 022import java.lang.annotation.Retention; 023import java.lang.annotation.RetentionPolicy; 024import java.lang.annotation.Target; 025 026import org.springframework.beans.factory.support.BeanNameGenerator; 027import org.springframework.core.annotation.AliasFor; 028import org.springframework.core.type.filter.TypeFilter; 029 030/** 031 * Configures component scanning directives for use with @{@link Configuration} classes. 032 * Provides support parallel with Spring XML's {@code <context:component-scan>} element. 033 * 034 * <p>Either {@link #basePackageClasses} or {@link #basePackages} (or its alias 035 * {@link #value}) may be specified to define specific packages to scan. If specific 036 * packages are not defined, scanning will occur from the package of the 037 * class that declares this annotation. 038 * 039 * <p>Note that the {@code <context:component-scan>} element has an 040 * {@code annotation-config} attribute; however, this annotation does not. This is because 041 * in almost all cases when using {@code @ComponentScan}, default annotation config 042 * processing (e.g. processing {@code @Autowired} and friends) is assumed. Furthermore, 043 * when using {@link AnnotationConfigApplicationContext}, annotation config processors are 044 * always registered, meaning that any attempt to disable them at the 045 * {@code @ComponentScan} level would be ignored. 046 * 047 * <p>See {@link Configuration @Configuration}'s Javadoc for usage examples. 048 * 049 * @author Chris Beams 050 * @author Juergen Hoeller 051 * @author Sam Brannen 052 * @since 3.1 053 * @see Configuration 054 */ 055@Retention(RetentionPolicy.RUNTIME) 056@Target(ElementType.TYPE) 057@Documented 058@Repeatable(ComponentScans.class) 059public @interface ComponentScan { 060 061 /** 062 * Alias for {@link #basePackages}. 063 * <p>Allows for more concise annotation declarations if no other attributes 064 * are needed — for example, {@code @ComponentScan("org.my.pkg")} 065 * instead of {@code @ComponentScan(basePackages = "org.my.pkg")}. 066 */ 067 @AliasFor("basePackages") 068 String[] value() default {}; 069 070 /** 071 * Base packages to scan for annotated components. 072 * <p>{@link #value} is an alias for (and mutually exclusive with) this 073 * attribute. 074 * <p>Use {@link #basePackageClasses} for a type-safe alternative to 075 * String-based package names. 076 */ 077 @AliasFor("value") 078 String[] basePackages() default {}; 079 080 /** 081 * Type-safe alternative to {@link #basePackages} for specifying the packages 082 * to scan for annotated components. The package of each class specified will be scanned. 083 * <p>Consider creating a special no-op marker class or interface in each package 084 * that serves no purpose other than being referenced by this attribute. 085 */ 086 Class<?>[] basePackageClasses() default {}; 087 088 /** 089 * The {@link BeanNameGenerator} class to be used for naming detected components 090 * within the Spring container. 091 * <p>The default value of the {@link BeanNameGenerator} interface itself indicates 092 * that the scanner used to process this {@code @ComponentScan} annotation should 093 * use its inherited bean name generator, e.g. the default 094 * {@link AnnotationBeanNameGenerator} or any custom instance supplied to the 095 * application context at bootstrap time. 096 * @see AnnotationConfigApplicationContext#setBeanNameGenerator(BeanNameGenerator) 097 * @see AnnotationBeanNameGenerator 098 * @see FullyQualifiedAnnotationBeanNameGenerator 099 */ 100 Class<? extends BeanNameGenerator> nameGenerator() default BeanNameGenerator.class; 101 102 /** 103 * The {@link ScopeMetadataResolver} to be used for resolving the scope of detected components. 104 */ 105 Class<? extends ScopeMetadataResolver> scopeResolver() default AnnotationScopeMetadataResolver.class; 106 107 /** 108 * Indicates whether proxies should be generated for detected components, which may be 109 * necessary when using scopes in a proxy-style fashion. 110 * <p>The default is defer to the default behavior of the component scanner used to 111 * execute the actual scan. 112 * <p>Note that setting this attribute overrides any value set for {@link #scopeResolver}. 113 * @see ClassPathBeanDefinitionScanner#setScopedProxyMode(ScopedProxyMode) 114 */ 115 ScopedProxyMode scopedProxy() default ScopedProxyMode.DEFAULT; 116 117 /** 118 * Controls the class files eligible for component detection. 119 * <p>Consider use of {@link #includeFilters} and {@link #excludeFilters} 120 * for a more flexible approach. 121 */ 122 String resourcePattern() default ClassPathScanningCandidateComponentProvider.DEFAULT_RESOURCE_PATTERN; 123 124 /** 125 * Indicates whether automatic detection of classes annotated with {@code @Component} 126 * {@code @Repository}, {@code @Service}, or {@code @Controller} should be enabled. 127 */ 128 boolean useDefaultFilters() default true; 129 130 /** 131 * Specifies which types are eligible for component scanning. 132 * <p>Further narrows the set of candidate components from everything in {@link #basePackages} 133 * to everything in the base packages that matches the given filter or filters. 134 * <p>Note that these filters will be applied in addition to the default filters, if specified. 135 * Any type under the specified base packages which matches a given filter will be included, 136 * even if it does not match the default filters (i.e. is not annotated with {@code @Component}). 137 * @see #resourcePattern() 138 * @see #useDefaultFilters() 139 */ 140 Filter[] includeFilters() default {}; 141 142 /** 143 * Specifies which types are not eligible for component scanning. 144 * @see #resourcePattern 145 */ 146 Filter[] excludeFilters() default {}; 147 148 /** 149 * Specify whether scanned beans should be registered for lazy initialization. 150 * <p>Default is {@code false}; switch this to {@code true} when desired. 151 * @since 4.1 152 */ 153 boolean lazyInit() default false; 154 155 156 /** 157 * Declares the type filter to be used as an {@linkplain ComponentScan#includeFilters 158 * include filter} or {@linkplain ComponentScan#excludeFilters exclude filter}. 159 */ 160 @Retention(RetentionPolicy.RUNTIME) 161 @Target({}) 162 @interface Filter { 163 164 /** 165 * The type of filter to use. 166 * <p>Default is {@link FilterType#ANNOTATION}. 167 * @see #classes 168 * @see #pattern 169 */ 170 FilterType type() default FilterType.ANNOTATION; 171 172 /** 173 * Alias for {@link #classes}. 174 * @see #classes 175 */ 176 @AliasFor("classes") 177 Class<?>[] value() default {}; 178 179 /** 180 * The class or classes to use as the filter. 181 * <p>The following table explains how the classes will be interpreted 182 * based on the configured value of the {@link #type} attribute. 183 * <table border="1"> 184 * <tr><th>{@code FilterType}</th><th>Class Interpreted As</th></tr> 185 * <tr><td>{@link FilterType#ANNOTATION ANNOTATION}</td> 186 * <td>the annotation itself</td></tr> 187 * <tr><td>{@link FilterType#ASSIGNABLE_TYPE ASSIGNABLE_TYPE}</td> 188 * <td>the type that detected components should be assignable to</td></tr> 189 * <tr><td>{@link FilterType#CUSTOM CUSTOM}</td> 190 * <td>an implementation of {@link TypeFilter}</td></tr> 191 * </table> 192 * <p>When multiple classes are specified, <em>OR</em> logic is applied 193 * — for example, "include types annotated with {@code @Foo} OR {@code @Bar}". 194 * <p>Custom {@link TypeFilter TypeFilters} may optionally implement any of the 195 * following {@link org.springframework.beans.factory.Aware Aware} interfaces, and 196 * their respective methods will be called prior to {@link TypeFilter#match match}: 197 * <ul> 198 * <li>{@link org.springframework.context.EnvironmentAware EnvironmentAware}</li> 199 * <li>{@link org.springframework.beans.factory.BeanFactoryAware BeanFactoryAware} 200 * <li>{@link org.springframework.beans.factory.BeanClassLoaderAware BeanClassLoaderAware} 201 * <li>{@link org.springframework.context.ResourceLoaderAware ResourceLoaderAware} 202 * </ul> 203 * <p>Specifying zero classes is permitted but will have no effect on component 204 * scanning. 205 * @since 4.2 206 * @see #value 207 * @see #type 208 */ 209 @AliasFor("value") 210 Class<?>[] classes() default {}; 211 212 /** 213 * The pattern (or patterns) to use for the filter, as an alternative 214 * to specifying a Class {@link #value}. 215 * <p>If {@link #type} is set to {@link FilterType#ASPECTJ ASPECTJ}, 216 * this is an AspectJ type pattern expression. If {@link #type} is 217 * set to {@link FilterType#REGEX REGEX}, this is a regex pattern 218 * for the fully-qualified class names to match. 219 * @see #type 220 * @see #classes 221 */ 222 String[] pattern() default {}; 223 224 } 225 226}