This commit makes use of the new Supplier<String> variants of utility
methods in org.springframework.util.Assert within the spring-test
module.

Issue: SPR-14450

Issue: SPR-13998

Allow third-parties to contribute ContextCustomizers that can customize
ApplicationContexts created by the Spring TestContext Framework (TCF)
before they are refreshed.

A customizer may be provided via a ContextCustomizerFactory which is
registered with `spring.factories`. Each factory is consulted whenever
a new ApplicationContext needs to be created by the TCF. Factories may
inspect various details about the test and either return a new
ContextCustomizer or null.

ContextCustomizers are similar to ApplicationContextInitializers and
may perform any number of tasks, including bean registration, setting
of active profiles, etc.

Issue: SPR-13998

Prior to this commit, the Spring TestContext Framework did not support
the declaration of both 'locations' and 'classes' within
@ContextConfiguration at the same time.

This commit addresses this in the following manner:

 - ContextConfigurationAttributes no longer throws an
   IllegalArgumentException if both 'locations' and 'classes' are
   supplied to its constructor.

 - Concrete SmartContextLoader implementations now validate the
   supplied MergedContextConfiguration before attempting to load the
   ApplicationContext. See validateMergedContextConfiguration().

 - Introduced tests for hybrid context loaders like the one used in
   Spring Boot. See HybridContextLoaderTests.

 - Updated the Testing chapter of the reference manual so that it no
   longer states that locations and classes cannot be used
   simultaneously, mentioning Spring Boot as well.

 - The Javadoc for @ContextConfiguration has been updated accordingly.

 - Added hasLocations(), hasClasses(), and hasResources() convenience
   methods to MergedContextConfiguration.

Issue: SPR-11634

Issue: SPR-10130

Prior to this commit the Spring TestContext Framework supported creating
only flat, non-hierarchical contexts. There was no easy way to create
contexts with parent-child relationships.

This commit addresses this issue by introducing a new @ContextHierarchy
annotation that can be used in conjunction with @ContextConfiguration
for declaring hierarchies of application contexts, either within a
single test class or within a test class hierarchy. In addition,
@DirtiesContext now supports a new 'hierarchyMode' attribute for
controlling context cache clearing for context hierarchies.

- Introduced a new @ContextHierarchy annotation.
- Introduced 'name' attribute in @ContextConfiguration.
- Introduced 'name' property in ContextConfigurationAttributes.
- TestContext is now aware of @ContextHierarchy in addition to
  @ContextConfiguration.
- Introduced findAnnotationDeclaringClassForTypes() in AnnotationUtils.
- Introduced resolveContextHierarchyAttributes() in ContextLoaderUtils.
- Introduced buildContextHierarchyMap() in ContextLoaderUtils.
- @ContextConfiguration and @ContextHierarchy may not be used as
  top-level, class-level annotations simultaneously.
- Introduced reference to the parent configuration in
  MergedContextConfiguration and WebMergedContextConfiguration.
- Introduced overloaded buildMergedContextConfiguration() methods in
  ContextLoaderUtils in order to handle context hierarchies separately
  from conventional, non-hierarchical contexts.
- Introduced hashCode() and equals() in ContextConfigurationAttributes.
- ContextLoaderUtils ensures uniqueness of @ContextConfiguration
  elements within a single @ContextHierarchy declaration.
- Introduced CacheAwareContextLoaderDelegate that can be used for
  loading contexts with transparent support for interacting with the
  context cache -- for example, for retrieving the parent application
  context in a context hierarchy.
- TestContext now delegates to CacheAwareContextLoaderDelegate for
  loading contexts.
- Introduced getParentApplicationContext() in MergedContextConfiguration
- The loadContext(MergedContextConfiguration) methods in
  AbstractGenericContextLoader and AbstractGenericWebContextLoader now
  set the parent context as appropriate.
- Introduced 'hierarchyMode' attribute in @DirtiesContext with a
  corresponding HierarchyMode enum that defines EXHAUSTIVE and
  CURRENT_LEVEL cache removal modes.
- ContextCache now internally tracks the relationships between contexts
  that make up a context hierarchy. Furthermore, when a context is
  removed, if it is part of a context hierarchy all corresponding
  contexts will be removed from the cache according to the supplied
  HierarchyMode.
- AbstractGenericWebContextLoader will set a loaded context as the
  ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE in the MockServletContext when
  context hierarchies are used if the context has no parent or if the
  context has a parent that is not a WAC.
- Where appropriate, updated Javadoc to refer to the
  ServletTestExecutionListener, which was introduced in 3.2.0.
- Updated Javadoc to avoid and/or suppress warnings in spring-test.
- Suppressed remaining warnings in code in spring-test.

Issue: SPR-5613, SPR-9863

This reverts commit 45fa5082, reversing
changes made to a312d900.

Issue: SPR-10130

Issue: SPR-10128

  find . -type f -name "*.java" -or -name "*.aj" | \
    xargs perl -p -i -e "s/[ \t]*$//g" {} \;

Issue: SPR-10127

 - Support external Javadoc links using Gradle's javadoc.options.links

 - Fix all other Javadoc warnings, such as typos, references to
   non-existent (or no longer existent) types and members, etc,
   including changes related to the Quartz 2.0 upgrade (SPR-8275) and
   adding the HTTP PATCH method (SPR-7985).

 - Suppress all output for project-level `javadoc` tasks in order to
   hide false-negative warnings about cross-module @see and @link
   references (e.g. spring-core having a @see reference to spring-web).
   Use the `--info` (-i) flag to gradle at any time to see project-level
   javadoc warnings without running the entire `api` task. e.g.
   `gradle :spring-core:javadoc -i`

 - Favor root project level `api` task for detection of legitimate
   Javadoc warnings. There are now zero Javadoc warnings across the
   entirety of spring-framework. Goal: keep it that way.

 - Remove all @link and @see references to types and members that exist
   only in Servlet <= 2.5 and Hibernate <= 4.0, favoring 3.0+ and 4.0+
   respectively. This is necessary because only one version of each of
   these dependencies can be present on the global `api` javadoc task's
   classpath. To that end, the `api` task classpath has now been
   customized to ensure that the Servlet 3 API and Hibernate Core 4 jars
   have precedence.

 - SPR-8896 replaced our dependency on aspectjrt with a dependency on
   aspectjweaver, which is fine from a POM point of view, but causes
   a spurious warning to be emitted from the ant iajc task that it
   "cannot find aspectjrt on the classpath" - even though aspectjweaver
   is perfectly sufficient. In the name of keeping the console quiet, a
   new `rt` configuration has been added, and aspectjrt added as a
   dependency to it. In turn, configurations.rt.asPath is appended to
   the iajc classpath during both compileJava and compileTestJava for
   spring-aspects.

Issue: SPR-10078, SPR-8275, SPR-7985, SPR-8896

This commit adds Javadoc documentation for the WebApplicationContext
testing support that was recently introduced in the Spring TestContext
Framework.

Issue: SPR-9864

This commit relocates recently introduced web artifacts in the
TestContext framework to the ~.test.context.web package and renames some
classes for consistency with the existing code base.

 - introduced package-info.java in the web package.

 - ServletTestExecutionListener now extends
   AbstractTestExecutionListener instead of implementing
   TestExecutionListener.

 - relocated AbstractGenericWebContextLoader,
   AnnotationConfigWebContextLoader, XmlWebContextLoader, and
   WebDelegatingSmartContextLoader to the web package.

 - renamed XmlWebContextLoader to GenericXmlWebContextLoader for
   consistency with GenericXmlContextLoader.

 - changed the visibility of AbstractDelegatingSmartContextLoader and
   AnnotationConfigContextLoaderUtils to public.

Issue: SPR-10067

Issue: SPR-9864

Prior to this commit, the Spring TestContext Framework only supported
loading an ApplicationContext in integration tests from either XML or
Java Properties files (since Spring 2.5), and Spring 3.1 introduced
support for loading an ApplicationContext in integration tests from
annotated classes (e.g., @Configuration classes). All of the
ContextLoader implementations used to provide this support load a
GenericApplicationContext. However, a GenericApplicationContext is not
suitable for testing a web application since a web application relies on
an implementation of WebApplicationContext (WAC).

This commit makes it possible to integration test Spring-powered web
applications by adding the following functionality to the Spring
TestContext Framework.

 - Introduced AbstractGenericWebContextLoader and two concrete
   subclasses:
   - XmlWebContextLoader
   - AnnotationConfigWebContextLoader

 - Pulled up prepareContext(context, mergedConfig) from
   AbstractGenericContextLoader into AbstractContextLoader to allow it
   to be shared across web and non-web context loaders.

 - Introduced AnnotationConfigContextLoaderUtils and refactored
   AnnotationConfigContextLoader accordingly. These utils are also used
   by AnnotationConfigWebContextLoader.

 - Introduced a new @WebAppConfiguration annotation to denote that the
   ApplicationContext loaded for a test should be a WAC and to configure
   the base resource path for the root directory of a web application.

 - Introduced WebMergedContextConfiguration which extends
   MergedContextConfiguration with support for a baseResourcePath for
   the root directory of a web application.

 - ContextLoaderUtils.buildMergedContextConfiguration() now builds a
   WebMergedContextConfiguration instead of a standard
   MergedContextConfiguration if @WebAppConfiguration is present on the
   test class.

 - Introduced a configureWebResources() method in
   AbstractGenericWebContextLoader that is responsible for creating a
   MockServletContext with a proper ResourceLoader for the
   resourceBasePath configured in the WebMergedContextConfiguration. The
   resulting mock ServletContext is set in the WAC, and the WAC is
   stored as the Root WAC in the ServletContext.

 - Introduced a WebTestExecutionListener that sets up default thread
   local state via RequestContextHolder before each test method by using
   the MockServletContext already present in the WAC and by creating a
   MockHttpServletRequest, MockHttpServletResponse, and
   ServletWebRequest that is set in the RequestContextHolder. WTEL also
   ensures that the MockHttpServletResponse and ServletWebRequest can be
   injected into the test instance (e.g., via @Autowired) and cleans up
   thread locals after each test method.

 - WebTestExecutionListener is configured as a default
   TestExecutionListener before DependencyInjectionTestExecutionListener

 - Extracted AbstractDelegatingSmartContextLoader from
   DelegatingSmartContextLoader and introduced a new
   WebDelegatingSmartContextLoader.

 - ContextLoaderUtils now selects the default delegating ContextLoader
   class name based on the presence of @WebAppConfiguration on the test
   class.

 - Tests in the spring-test-mvc module no longer use a custom
   ContextLoader to load a WebApplicationContext. Instead, they now
   rely on new core functionality provided in this commit.

Issue: SPR-5243