root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

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
This commit is contained in:
Sam Brannen 2019-03-09 16:30:30 +01:00
parent c04eaf6b84
commit b109f140a7
3 changed files with 34 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
spring-context/src/main/resources/org/springframework/context/config/spring-context.xsd
View File

@ -515,7 +515,7 @@
<xsd:documentation><![CDATA[
Controls the type of filtering to apply to the expression.
"annotation" indicates an annotation to be present at the type level in target components;
"annotation" indicates an annotation to be present or meta-present at the type level in target components;
"assignable" indicates a class (or interface) that the target components are assignable to (extend/implement);
"aspectj" indicates an AspectJ type pattern expression to be matched by the target components;
"regex" indicates a regex pattern to be matched by the target components' class names;

26
spring-core/src/main/java/org/springframework/core/type/filter/AnnotationTypeFilter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2018 the original author or authors.
* Copyright 2002-2019 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.
@ -26,14 +26,20 @@ import org.springframework.lang.Nullable;
import org.springframework.util.ClassUtils;
/**
* A simple filter which matches classes with a given annotation,
* A simple {@link TypeFilter} which matches classes with a given annotation,
* checking inherited annotations as well.
*
* <p>The matching logic mirrors that of {@link java.lang.Class#isAnnotationPresent(Class)}.
* <p>By default, the matching logic mirrors that of
* {@link AnnotationUtils#getAnnotation(java.lang.reflect.AnnotatedElement, Class)},
* supporting annotations that are <em>present</em> or <em>meta-present</em> 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.
* <p>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.
* <p>The filter will not match interfaces.
* @param annotationType the annotation type to match
*/
public AnnotationTypeFilter(Class<? extends Annotation> 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.
* <p>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

32
src/docs/asciidoc/core/core-beans.adoc
View File

@ -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 `<context:include-filter />` or
`<context:exclude-filter />` child elements of the `<context:component-scan>` 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:
</beans>
----
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 `<component-scan/>` 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
`<component-scan/>` element. This effectively disables automatic detection of classes
annotated or meta-annotated with `@Component`, `@Repository`, `@Service`, `@Controller`,
`@RestController`, or `@Configuration`.