From b109f140a7be2ccc6f7aad34a9bbe3d4b03da6d4 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 9 Mar 2019 16:30:30 +0100 Subject: [PATCH] Improve documentation for annotation filters with component scanning Prior to this commit the documentation for annotation-based include and exclude filters used with component scanning did not explicitly mention the fact that annotations are considered a match if they are either present or meta-present on candidate classes. This commit improves the documentation in this regard. See gh-22551 --- .../context/config/spring-context.xsd | 2 +- .../type/filter/AnnotationTypeFilter.java | 26 +++++++++------ src/docs/asciidoc/core/core-beans.adoc | 32 ++++++++++--------- 3 files changed, 34 insertions(+), 26 deletions(-) diff --git a/spring-context/src/main/resources/org/springframework/context/config/spring-context.xsd b/spring-context/src/main/resources/org/springframework/context/config/spring-context.xsd index db36518906..ee4df23dec 100644 --- a/spring-context/src/main/resources/org/springframework/context/config/spring-context.xsd +++ b/spring-context/src/main/resources/org/springframework/context/config/spring-context.xsd @@ -515,7 +515,7 @@ The matching logic mirrors that of {@link java.lang.Class#isAnnotationPresent(Class)}. + *

By default, the matching logic mirrors that of + * {@link AnnotationUtils#getAnnotation(java.lang.reflect.AnnotatedElement, Class)}, + * supporting annotations that are present or meta-present for a + * single level of meta-annotations. The search for meta-annotations my be disabled. + * Similarly, the search for annotations on interfaces may optionally be enabled. + * Consult the various constructors in this class for details. * * @author Mark Fisher * @author Ramnivas Laddad * @author Juergen Hoeller + * @author Sam Brannen * @since 2.5 */ public class AnnotationTypeFilter extends AbstractTypeHierarchyTraversingFilter { @@ -44,11 +50,11 @@ public class AnnotationTypeFilter extends AbstractTypeHierarchyTraversingFilter /** - * Create a new AnnotationTypeFilter for the given annotation type. - * This filter will also match meta-annotations. To disable the + * Create a new {@code AnnotationTypeFilter} for the given annotation type. + *

The filter will also match meta-annotations. To disable the * meta-annotation matching, use the constructor that accepts a - * '{@code considerMetaAnnotations}' argument. The filter will - * not match interfaces. + * '{@code considerMetaAnnotations}' argument. + *

The filter will not match interfaces. * @param annotationType the annotation type to match */ public AnnotationTypeFilter(Class annotationType) { @@ -56,8 +62,8 @@ public class AnnotationTypeFilter extends AbstractTypeHierarchyTraversingFilter } /** - * Create a new AnnotationTypeFilter for the given annotation type. - * The filter will not match interfaces. + * Create a new {@code AnnotationTypeFilter} for the given annotation type. + *

The filter will not match interfaces. * @param annotationType the annotation type to match * @param considerMetaAnnotations whether to also match on meta-annotations */ @@ -66,7 +72,7 @@ public class AnnotationTypeFilter extends AbstractTypeHierarchyTraversingFilter } /** - * Create a new {@link AnnotationTypeFilter} for the given annotation type. + * Create a new {@code AnnotationTypeFilter} for the given annotation type. * @param annotationType the annotation type to match * @param considerMetaAnnotations whether to also match on meta-annotations * @param considerInterfaces whether to also match interfaces diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 14932946e2..08e0decc4f 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -5499,7 +5499,7 @@ component-scan element. That means that the two components are autodetected and wired together -- all without any bean configuration metadata provided in XML. NOTE: You can disable the registration of `AutowiredAnnotationBeanPostProcessor` and -`CommonAnnotationBeanPostProcessor` by including the annotation-config attribute +`CommonAnnotationBeanPostProcessor` by including the `annotation-config` attribute with a value of `false`. @@ -5507,13 +5507,14 @@ with a value of `false`. [[beans-scanning-filters]] === Using Filters to Customize Scanning -By default, classes annotated with `@Component`, `@Repository`, `@Service`, -`@Controller`, or a custom annotation that itself is annotated with `@Component` are the -only detected candidate components. However, you can modify and extend this behavior -by applying custom filters. Add them as `includeFilters` or `excludeFilters` -parameters of the `@ComponentScan` annotation (or as `include-filter` or `exclude-filter` -child elements of the `component-scan` element). Each filter element requires the `type` -and `expression` attributes. The following table describes the filtering options: +By default, classes annotated with `@Component`, `@Repository`, `@Service`, `@Controller`, +`@Configuration`, or a custom annotation that itself is annotated with `@Component` are +the only detected candidate components. However, you can modify and extend this behavior +by applying custom filters. Add them as `includeFilters` or `excludeFilters` attributes of +the `@ComponentScan` annotation (or as `` or +`` child elements of the `` element in +XML configuration). Each filter element requires the `type` and `expression` attributes. +The following table describes the filtering options: [[beans-scanning-filters-tbl]] .Filter Types @@ -5522,7 +5523,7 @@ and `expression` attributes. The following table describes the filtering options | annotation (default) | `org.example.SomeAnnotation` -| An annotation to be present at the type level in target components. +| An annotation to be _present_ or _meta-present_ at the type level in target components. | assignable | `org.example.SomeClass` @@ -5534,11 +5535,11 @@ and `expression` attributes. The following table describes the filtering options | regex | `org\.example\.Default.*` -| A regex expression to be matched by the target components class names. +| A regex expression to be matched by the target components' class names. | custom | `org.example.MyTypeFilter` -| A custom implementation of the `org.springframework.core.type .TypeFilter` interface. +| A custom implementation of the `org.springframework.core.type.TypeFilter` interface. |=== The following example shows the configuration ignoring all `@Repository` annotations @@ -5571,10 +5572,11 @@ The following listing shows the equivalent XML: ---- -NOTE: You can also disable the default filters by setting `useDefaultFilters=false` on the annotation or - by providing `use-default-filters="false"` as an attribute of the `` element. This, -in effect, disables automatic detection of classes annotated with `@Component`, `@Repository`, -`@Service`, `@Controller`, or `@Configuration`. +NOTE: You can also disable the default filters by setting `useDefaultFilters=false` on the +annotation or by providing `use-default-filters="false"` as an attribute of the +`` element. This effectively disables automatic detection of classes +annotated or meta-annotated with `@Component`, `@Repository`, `@Service`, `@Controller`, +`@RestController`, or `@Configuration`.