ClassPathScanningCandidateComponentProvider (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.context.annotation

## Class ClassPathScanningCandidateComponentProvider

- java.lang.Object
- - org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider

- All Implemented Interfaces:
    Aware, ResourceLoaderAware, EnvironmentCapable
  Direct Known Subclasses:
    ClassPathBeanDefinitionScanner

      public class ClassPathScanningCandidateComponentProvider
      extends Object
      implements EnvironmentCapable, ResourceLoaderAware

  A component provider that scans the classpath from a base package. It then applies exclude and include filters to the resulting classes to find candidates.

  This implementation is based on Spring's `MetadataReader` facility, backed by an ASM `ClassReader`.

  Since:
    2.5
  Author:
    Mark Fisher, Juergen Hoeller, Ramnivas Laddad, Chris Beams
  See Also:
    `MetadataReaderFactory`, `AnnotationMetadata`, `ScannedGenericBeanDefinition`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ClassPathScanningCandidateComponentProvider(boolean useDefaultFilters)` Create a ClassPathScanningCandidateComponentProvider.
    `ClassPathScanningCandidateComponentProvider(boolean useDefaultFilters, Environment environment)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addExcludeFilter(TypeFilter excludeFilter)` Add an exclude type filter to the front of the exclusion list.
    `void` | `addIncludeFilter(TypeFilter includeFilter)` Add an include type filter to the end of the inclusion list.
    `void` | `clearCache()` Clear the underlying metadata cache, removing all cached class metadata.
    `Set<BeanDefinition>` | `findCandidateComponents(String basePackage)` Scan the class path for candidate components.
    `Environment` | `getEnvironment()` Return the Environment for this object
    `MetadataReaderFactory` | `getMetadataReaderFactory()` Return the MetadataReaderFactory used by this component provider.
    `ResourceLoader` | `getResourceLoader()` Return the ResourceLoader that this component provider uses.
    `protected boolean` | `isCandidateComponent(AnnotatedBeanDefinition beanDefinition)` Determine whether the given bean definition qualifies as candidate.
    `protected boolean` | `isCandidateComponent(MetadataReader metadataReader)` Determine whether the given class does not match any exclude filter and does match at least one include filter.
    `protected void` | `registerDefaultFilters()` Register the default filter for `@Component`.
    `void` | `resetFilters(boolean useDefaultFilters)` Reset the configured type filters.
    `protected String` | `resolveBasePackage(String basePackage)` Resolve the specified base package into a pattern specification for the package search path.
    `void` | `setEnvironment(Environment environment)` Set the Environment to use when resolving placeholders and evaluating `@Profile`-annotated component classes.
    `void` | `setMetadataReaderFactory(MetadataReaderFactory metadataReaderFactory)` Set the `MetadataReaderFactory` to use.
    `void` | `setResourceLoader(ResourceLoader resourceLoader)` Set the ResourceLoader to use for resource locations.
    `void` | `setResourcePattern(String resourcePattern)` Set the resource pattern to use when scanning the classpath.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### logger

          protected final Log logger

  - ### Constructor Detail

    - #### ClassPathScanningCandidateComponentProvider

          public ClassPathScanningCandidateComponentProvider(boolean useDefaultFilters)

      Create a ClassPathScanningCandidateComponentProvider.
      Parameters:
        `useDefaultFilters` - whether to register the default filters for the `@Component`, `@Repository`, `@Service`, and `@Controller` stereotype annotations
      See Also:
        `registerDefaultFilters()`

    - #### ClassPathScanningCandidateComponentProvider

          public ClassPathScanningCandidateComponentProvider(boolean useDefaultFilters,
                                                     Environment environment)

  - ### Method Detail

    - #### setResourceLoader

          public void setResourceLoader(ResourceLoader resourceLoader)

      Set the ResourceLoader to use for resource locations. This will typically be a ResourcePatternResolver implementation.

      Default is PathMatchingResourcePatternResolver, also capable of resource pattern resolving through the ResourcePatternResolver interface.

      Specified by:
        `setResourceLoader` in interface `ResourceLoaderAware`
      Parameters:
        `resourceLoader` - ResourceLoader object to be used by this object
      See Also:
        `ResourcePatternResolver`, `PathMatchingResourcePatternResolver`

    - #### getResourceLoader

          public final ResourceLoader getResourceLoader()

      Return the ResourceLoader that this component provider uses.

    - #### setMetadataReaderFactory

          public void setMetadataReaderFactory(MetadataReaderFactory metadataReaderFactory)

      Set the `MetadataReaderFactory` to use.

      Default is a `CachingMetadataReaderFactory` for the specified resource loader.

      Call this setter method after `setResourceLoader(org.springframework.core.io.ResourceLoader)` in order for the given MetadataReaderFactory to override the default factory.

    - #### getMetadataReaderFactory

          public final MetadataReaderFactory getMetadataReaderFactory()

      Return the MetadataReaderFactory used by this component provider.

    - #### setEnvironment

          public void setEnvironment(Environment environment)

      Set the Environment to use when resolving placeholders and evaluating `@Profile`-annotated component classes.

      The default is a `StandardEnvironment`

      Parameters:
        `environment` - the Environment to use

    - #### getEnvironment

          public final Environment getEnvironment()

      Description copied from interface: `EnvironmentCapable`
      Return the Environment for this object
      Specified by:
        `getEnvironment` in interface `EnvironmentCapable`

    - #### setResourcePattern

          public void setResourcePattern(String resourcePattern)

      Set the resource pattern to use when scanning the classpath. This value will be appended to each base package name.
      See Also:
        `findCandidateComponents(String)`, `DEFAULT_RESOURCE_PATTERN`

    - #### addIncludeFilter

          public void addIncludeFilter(TypeFilter includeFilter)

      Add an include type filter to the end of the inclusion list.

    - #### addExcludeFilter

          public void addExcludeFilter(TypeFilter excludeFilter)

      Add an exclude type filter to the front of the exclusion list.

    - #### resetFilters

          public void resetFilters(boolean useDefaultFilters)

      Reset the configured type filters.
      Parameters:
        `useDefaultFilters` - whether to re-register the default filters for the `@Component`, `@Repository`, `@Service`, and `@Controller` stereotype annotations
      See Also:
        `registerDefaultFilters()`

    - #### registerDefaultFilters

          protected void registerDefaultFilters()

      Register the default filter for `@Component`.

      This will implicitly register all annotations that have the `@Component` meta-annotation including the `@Repository`, `@Service`, and `@Controller` stereotype annotations.

      Also supports Java EE 6's `ManagedBean` and JSR-330's `Named` annotations, if available.

    - #### findCandidateComponents

          public Set<BeanDefinition> findCandidateComponents(String basePackage)

      Scan the class path for candidate components.
      Parameters:
        `basePackage` - the package to check for annotated classes
      Returns:
        a corresponding Set of autodetected bean definitions

    - #### resolveBasePackage

          protected String resolveBasePackage(String basePackage)

      Resolve the specified base package into a pattern specification for the package search path.

      The default implementation resolves placeholders against system properties, and converts a "."-based package path to a "/"-based resource path.

      Parameters:
        `basePackage` - the base package as specified by the user
      Returns:
        the pattern specification to be used for package searching

    - #### isCandidateComponent

          protected boolean isCandidateComponent(MetadataReader metadataReader)
                                          throws IOException

      Determine whether the given class does not match any exclude filter and does match at least one include filter.
      Parameters:
        `metadataReader` - the ASM ClassReader for the class
      Returns:
        whether the class qualifies as a candidate component
      Throws:
        `IOException`

    - #### isCandidateComponent

          protected boolean isCandidateComponent(AnnotatedBeanDefinition beanDefinition)

      Determine whether the given bean definition qualifies as candidate.

      The default implementation checks whether the class is concrete (i.e. not abstract and not an interface). Can be overridden in subclasses.

      Parameters:
        `beanDefinition` - the bean definition to check
      Returns:
        whether the bean definition qualifies as a candidate component

    - #### clearCache

          public void clearCache()

      Clear the underlying metadata cache, removing all cached class metadata.