The following style updates have been made in anticipation of
substantive changes in subsequent commits:

 - organize imports
 - correct whitespace errors (leading spaces in code, tabs in Javadoc)
 - wrap Javadoc at 90 chars; make imperative ("Return" vs. "Returns")
 - use conventional constructor argument wrapping

A serialVersionUID has also been added to RestClientException and its
ResourceAccessException subclass for consistency with the rest of that
same exception hierarchy.

Issue: SPR-7938

 - Explicitly specify compile-time dependencies on other spring-*
   modules, primarily for accuracy in pom generation and ensuring
   minimal dependencies for users of spring-aspects.

 - Remove use of p: namespace from annotation-cache-aspectj.xml to
   avoid parser-related test failures under Eclipse (likely due to
   classpath differences between Gradle and Eclipse).

The spring-intstrument jar should have a 'Premain-Class:' manifest
entry in order to enable use as a Java agent. This entry was present in
versions 3.1.1 and earlier, but due to build infrastructure changes
starting in 3.2.x this entry was missed. It is now back in place as
expected.

Issue: SPR-9458

Gradle-generated poms thoroughly tested against 3.1.1 versions, with an
eye toward making as many spring-* dependencies optional as possible.

All spring-* modules now declare a Gradle dependency on any other
spring-* module where there is a direct compile-time usage of the
sources in that module. Previously, dependency declarations were
minimal, letting transitive resolution do most of the work. However,
this creates less than ideal poms and is generally not very
informative.

So for example, spring-jdbc uses spring-core, spring-beans and
spring-tx classes directly. Therefore it has the following declarations:

  compile project(":spring-core")
  compile project(":spring-beans")
  compile project(":spring-tx")

spring-core depends on spring-asm, but spring-jdbc does not use
spring-asm classes directly. Therefore spring-jdbc does not declare a
dependency on spring-asm. Transitive resolution is fine in such a case.

As for optional dependencies, it is a matter of degrees what
constitutes optional. A rule of thumb is whether there are legitimate
and likely use cases in which the module can be used without needing
the dependency. spring-jdbc has only one compile-time dependency on
spring-context classes, and that's in JndiDataSourceLookup. It is
certainly reasonable to imagine using spring-jdbc without JNDI,
therefore the spring-context dependency is declared optional as
follows:

  compile(project(":spring-context"), optional) // for JndiDataSourceLookup

Avoid Eclipse classpath conflicts between test versions of @Qualified
and @Autowired living in spring-core and actual versions living in
spring-beans.

In Spring 3.1 the spring-test Maven artifact did not have a required
dependency on spring-core, but there is practically no part of
spring-test that can be used without spring-core. Most test utilities
that are intended to be stand-alone utilities in fact use utility
classes from spring-core (e.g., ReflectionTestUtils). Even some of the
web mocks/stubs use spring-core (e.g., DelegatingServletInputStream).

In addition, the current Gradle build configuration for the spring-test
module is very simplistic -- in that it does not explicitly list any
optional dependencies such as the Servlet and Portlet APIs -- and it
defines a 'compile' dependency on spring-webmvc-portlet.

The resulting Maven dependencies in the generated POM are therefore not
what a typical consumer of the spring-test artifact would reasonably
expect.

To address these issues, the Gradle build configuration for the
spring-test module now explicitly defines the following 'compile'
dependencies:

 - spring-core
 - spring-webmvc, optional
 - spring-webmvc-portlet, optional
 - junit, optional
 - testng, optional
 - servlet-api, optional
 - jsp-api, optional
 - portlet-api, optional
 - activation, provided

The only required dependency is now spring-core; all other dependencies
are 'optional'.

Issue: SPR-8861

EhCacheFactoryBean now applies listeners and enabled/disabled flags to
existing cache regions as well.

Issue: SPR-9392

Issue: SPR-8774

StandardServletMultipartResolver#cleanupMultipart now takes care to
delete only actual file parts for Resin compatibility.

Issue: SPR-9299

ServletContextResource#getFile now falls back to #getRealPath for
non-existent files

Issue: SPR-8461

 - Improve wording & grammar in SmartValidator Javadoc
 - Suppress 'rawtypes' warnings in SpringValidatorAdapter

* SPR-6870:
  Cache by-type lookups in DefaultListableBeanFactory
  Polish

Prior to this change, by-type lookups using DLBF#getBeanNamesForType
required traversal of all bean definitions within the bean factory
in order to inspect their bean class for assignability to the target
type. These operations are comparatively expensive and when there are a
large number of beans registered within the container coupled with a
large number of by-type lookups at runtime, the performance impact can
be severe. The test introduced here demonstrates such a scenario clearly.

This performance problem is likely to manifest in large Spring-based
applications using non-singleton beans, particularly request-scoped
beans that may be created and wired many thousands of times per second.

This commit introduces a simple ConcurrentHashMap-based caching strategy
for by-type lookups; container-wide assignability checks happen only
once on the first by-type lookup and are afterwards cached by type
with the values in the map being an array of all bean names assignable
to that type. This means that at runtime when creating and autowiring
non-singleton beans, the cost of by-type lookups is reduced to that of
ConcurrentHashMap#get.

Issue: SPR-6870

Issue: SPR-6870

Previously (since Spring 3.1.1) RecursiveAnnotationAttributesVisitor
logs at level WARN when ASM parsing encounters an annotation or an (enum
used within an annotation) that cannot be classloaded. This is not
necessarily indicative of an error, e.g. JSR-305 annotations such as
@Nonnull may be used only for static analysis purposes, but because
these annotations have runtime retention, they remain present in the
bytecode. Per section 9.6.1.2 of the JLS, "An annotation that is present
in the binary may or may not be available at run-time via the reflective
libraries of the Java platform."

This commit lowers the log level of these messages from warn to debug,
but leaves at warn level other messages dealing with the ability
reflectively read enum values from within annotations.

Issue: SPR-9233

The following syntax is now supported

  <beans profile="p1,!p2">

  @Profile("p1", "!p2")

indicating that the <beans> element or annotated component should
be processed only if profile 'p1' is active or profile 'p2' is not
active.

Issue: SPR-8728

* SPR-9439:
  Introduce ConfigurableWebEnvironment
  Introduce ConfigurableEnvironment#merge
  Polish

Changes introduced in Spring 3.1 for Environment support inadvertently
established a cyclic dependency between the
org.springframework.web.context and
org.springframework.web.context.support packages, specifically through
web.context.ContextLoader's invocation of
web.context.support.WebApplicationContextUtils#initServletPropertySources.

This commit introduces ConfigurableWebEnvironment to break this cyclic
dependency. All web.context.ConfigurableWebApplicationContext types now
return web.context.ConfigurableWebEnvironment from their #getEnvironment
methods; web.context.support.StandardServletEnvironment now implements
ConfigurableWebEnvironment and makes the call to
web.context.support.WebApplicationContextUtils#initServletPropertySources
within its implementation of #initPropertySources. This means that
web.context.ContextLoader now invokes
web.context.ConfigurableWebEnvironment#initPropertySources instead of
web.context.support.WebApplicationContextUtils#initServletPropertySources
and thus the cycle is broken.

Issue: SPR-9439

Prior to this change, AbstractApplicationContext#setParent replaced the
child context's Environment with the parent's Environment if available.
This has the negative effect of potentially changing the type of the
child context's Environment, and in any case causes property sources
added directly against the child environment to be ignored. This
situation could easily occur if a WebApplicationContext child had a
non-web ApplicationContext set as its parent. In this case the parent
Environment type would (likely) be StandardEnvironment, while the child
Environment type would (likely) be StandardServletEnvironment. By
directly inheriting the parent environment, critical property sources
such as ServletContextPropertySource are lost entirely.

This commit introduces the concept of merging an environment through
the new ConfigurableEnvironment#merge method. Instead of replacing the
child's environment with the parent's,
AbstractApplicationContext#setParent now merges property sources as
well as active and default profile names from the parent into the
child. In this way, distinct environment objects are maintained with
specific types and property sources preserved. See #merge Javadoc for
additional details.

Issue: SPR-9444, SPR-9439

Issue: SPR-9439

@EnableSpringConfigured and its @Import'ed
SpringConfiguredConfiguration @Configuration class inadvertently
established a package cycle between beans.factory.aspectj and
context.annotation due to SpringConfiguredConfiguration's
dependency on annotations such as @Configuration, @Bean and @Role.

This commit fixes this architecture bug by moving
@EnableSpringConfigured and SpringConfiguredConfiguration from the
beans.factory.aspectj package to the context.annotation package where
they belong.

This change is assumed to be very low impact as @EnableSpringConfigured
was introduced in 3.1.0 and relocation is happening as quickly as
possible in 3.1.2. @EnableSpringConfigured is assumed to be infrequently
used at this point, and for those that are the migration path
is straightforward. When upgrading from Spring 3.1.0 or 3.1.1, update
import statements in any affected @Configuration classes to reflect the
new packaging.

Issue: SPR-9441

Commit 096693c4 refactored and
deprecated TransactionAspectUtils, moving its #qualifiedBeanOfType
and related methods into BeanFactoryUtils. This created a package cycle
between beans.factory and beans.factory.annotation due to use of the
beans.factory.annotation.Qualifier annotation in these methods.

This commit breaks the package cycle by introducing
beans.factory.annotation.BeanFactoryAnnotationUtils and moving these
@Qualifier-related methods to it. It is intentionally similar in name
and style to the familiar BeanFactoryUtils class for purposes of
discoverability.

There are no backward-compatibilty concerns associated with this change
as the cycle was introduced, caught and now fixed before a release.

Issue: SPR-6847

As of Spring 3.1 URI variables can be used for data binding purposes in
addition to request parameters (including query string and form params)

In some cases URI variables and request params can overlap (e.g. form
contains a child entity with an entityId as hidden form input while the
URI contains the entityId of the parent entity) and that can lead to
surprises if the application already exists.

This change ensures that request parameters are used first and URI
vars are added only if they don't overlap. Ideally however an
application should not use the same uri variable name as the name of
a request parameter where they don't refer to the same value.

Issue: SPR-9349

* SPR-7022:
  Support initial delay attribute for scheduled tasks
  Polish scheduled task execution infrastructure

java.util.concurrent's ScheduledExecutorService and its #schedule*
methods allow for an 'initialDelay' parameter in milliseconds.
Similarly, Spring's TaskExecutor abstraction allows for a concrete
'startTime' expressed as a Date. However, Spring's <task:scheduled> XML
element and @Scheduled annotation have, to date, not allowed for an
initial delay parameter that can be propagated down to the underlying
TaskScheduler/ScheduledExecutorService.

This commit introduces initial-delay and #initialDelay attributes to
task:scheduled and @Scheduled respectively, both indicating the number
of milliseconds to wait before the first invocation of the method in
question. Specifying a delay in this fashion is only valid in
conjunction with fixed-rate and fixed-delay tasks (i.e. not with cron
or trigger tasks).

The principal changes required to support these new attributes lie in
ScheduledTaskRegistrar, which previously supported registration of
tasks in the form of a Runnable and a Long parameter indicating (in the
case of fixed-rate and fixed-delay tasks), the interval with which the
task should be executed. In order to accommodate a third (and optional)
'initialDelay' parameter, the IntervalTask class has been added as a
holder for the Runnable to be executed, the interval in which to run
it, and the optional initial delay. For symmetry, a TriggerTask and
CronTask have also been added, the latter subclassing the former. And a
'Task' class has been added as a common ancestor for all the above.

One oddity of the implementation is in the naming of the new
setters in ScheduledTaskRegistrar. Prior to this commit, the setters
were named #setFixedDelayTasks, #setFixedRateTasks, etc, each accepting
a Map<Runnable, long>. In adding new setters for each task type, each
accepting a List<IntervalTask>, List<CronTask> etc, naturally the
approach would be to use method overloading and to introduce methods
of the same name but with differing parameter types. Unfortunately
however, Spring does not support injection against overloaded methods
(due to fundamental limitations of the underlying JDK Introspector).
This is not a problem when working with the ScheduledTaskRegistrar
directly, e.g. from within a @Configuration class that implements
SchedulingConfigurer, but is a problem from the point of view of the
ScheduledTasksBeanDefinitionParser which parses the <task:scheduled>
element - here the ScheduledTaskRegistrar is treated as a Spring bean
and is thus subject to these limitations. The solution to this problem
was simply to avoid overloading altogether, thus the naming of the new
methods ending in "List", e.g. #setFixedDelayTasksList, etc. These
methods exist primarily for use by the BeanDefinitionParser and are
not really intended for use by application developers. The Javadoc for
each of the new methods makes note of this.

Issue: SPR-7022

In anticipation of substantive changes required to implement "initial
delay" support in the <task:scheduled> element and @Scheduled
annotation, the following updates have been made to the components and
infrastructure supporting scheduled task execution:

 - Fix code style violations
 - Fix compiler warnings
 - Add Javadoc where missing, update to use {@code} tags, etc.
 - Organize imports to follow conventions

* SPR-9300:
  Add convenient WebAppInitializer base classes

This commit introduces three abstract WebApplicationInitializers, to be
used in the typical setup of a Spring-based web application.

 - AbstractContextLoaderInitializer provides an abstract base class for
   registering a ContextLoaderListener.

 - AbstractDispatcherServletInitializer provides an abstract base class
   for registering a DispatcherServlet, with an optional root context.

 - AbstractAnnotationConfigDispatcherServletInitializer provides an
   abstract base class for registering a DispatcherServlet and optional
   ContextLoaderListener based on annotated (e.g. @Configuration)
   classes.

Issue: SPR-9300

Prove that Async#value is respected even when using @Async as a meta
annotation.

Issue: SPR-6847

* SPR-6847:
  Support executor qualification with @Async#value
  Polish async method execution infrastructure
  Refactor and deprecate TransactionAspectUtils

Prior to this change, Spring's @Async annotation support was tied to a
single AsyncTaskExecutor bean, meaning that all methods marked with
@Async were forced to use the same executor. This is an undesirable
limitation, given that certain methods may have different priorities,
etc. This leads to the need to (optionally) qualify which executor
should handle each method.

This is similar to the way that Spring's @Transactional annotation was
originally tied to a single PlatformTransactionManager, but in Spring
3.0 was enhanced to allow for a qualifier via the #value attribute, e.g.

  @Transactional("ptm1")
  public void m() { ... }

where "ptm1" is either the name of a PlatformTransactionManager bean or
a qualifier value associated with a PlatformTransactionManager bean,
e.g. via the <qualifier> element in XML or the @Qualifier annotation.

This commit introduces the same approach to @Async and its relationship
to underlying executor beans. As always, the following syntax remains
supported

  @Async
  public void m() { ... }

indicating that calls to #m will be delegated to the "default" executor,
i.e. the executor provided to

  <task:annotation-driven executor="..."/>

or the executor specified when authoring a @Configuration class that
implements AsyncConfigurer and its #getAsyncExecutor method.

However, it now also possible to qualify which executor should be used
on a method-by-method basis, e.g.

  @Async("e1")
  public void m() { ... }

indicating that calls to #m will be delegated to the executor bean
named or otherwise qualified as "e1". Unlike the default executor
which is specified up front at configuration time as described above,
the "e1" executor bean is looked up within the container on the first
execution of #m and then cached in association with that method for the
lifetime of the container.

Class-level use of Async#value behaves as expected, indicating that all
methods within the annotated class should be executed with the named
executor. In the case of both method- and class-level annotations, any
method-level #value overrides any class level #value.

This commit introduces the following major changes:

 - Add @Async#value attribute for executor qualification

 - Introduce AsyncExecutionAspectSupport as a common base class for
   both MethodInterceptor- and AspectJ-based async aspects. This base
   class provides common structure for specifying the default executor
   (#setExecutor) as well as logic for determining (and caching) which
   executor should execute a given method (#determineAsyncExecutor) and
   an abstract method to allow subclasses to provide specific strategies
   for executor qualification (#getExecutorQualifier).

 - Introduce AnnotationAsyncExecutionInterceptor as a specialization of
   the existing AsyncExecutionInterceptor to allow for introspection of
   the @Async annotation and its #value attribute for a given method.
   Note that this new subclass was necessary for packaging reasons -
   the original AsyncExecutionInterceptor lives in
   org.springframework.aop and therefore does not have visibility to
   the @Async annotation in org.springframework.scheduling.annotation.
   This new subclass replaces usage of AsyncExecutionInterceptor
   throughout the framework, though the latter remains usable and
   undeprecated for compatibility with any existing third-party
   extensions.

 - Add documentation to spring-task-3.2.xsd and reference manual
   explaining @Async executor qualification

 - Add tests covering all new functionality

Note that the public API of all affected components remains backward-
compatible.

Issue: SPR-6847

In anticipation of substantive changes required to implement @Async
executor qualification, the following updates have been made to the
components and infrastructure supporting @Async functionality:

 - Fix trailing whitespace and indentation errors
 - Fix generics warnings
 - Add Javadoc where missing, update to use {@code} tags, etc.
 - Avoid NPE in AopUtils#canApply
 - Organize imports to follow conventions
 - Remove System.out.println statements from tests
 - Correct various punctuation and grammar problems

TransactionAspectUtils contains a number of methods useful in
retrieving a bean by type+qualifier. These methods are functionally
general-purpose save for the hard coding of PlatformTransactionManager
class literals throughout.

This commit generifies these methods and moves them into
BeanFactoryUtils primarily in anticipation of their use by async method
execution interceptors and aspects when performing lookups for qualified
executor beans e.g. via @Async("qualifier").

The public API of TransactionAspectUtils remains backward compatible;
all methods within have been deprecated, and all calls to those methods
throughout the framework refactored to use the new BeanFactoryUtils
variants instead.

The reference manual previously did not mention the applicability of
JSR-250 lifecycle annotations within the TestContext framework. The
lacking documentation here has lead to misunderstandings of the support
provided for @PostConstruct and @PreDestroy in test classes.

The testing chapter of the reference manual has therefore been updated
to explicitly define the limited support for these annotations.

Also introduced Jsr250LifecycleTests for empirical verification of the 
expected behavior.

Issue: SPR-4868