Spring Framework 4.2 RC1 introduced support for synthesizing an
annotation from an existing annotation in order to provide additional
functionality above and beyond that provided by Java. Specifically,
such synthesized annotations provide support for @AliasFor semantics.
As luck would have it, the same principle can be used to synthesize an
annotation from any map of attributes, and in particular, from an
instance of AnnotationAttributes.

The following highlight the major changes in this commit toward
achieving this goal.

- Introduced AnnotationAttributeExtractor abstraction and refactored
  SynthesizedAnnotationInvocationHandler to delegate to an
  AnnotationAttributeExtractor.

- Extracted code from SynthesizedAnnotationInvocationHandler into new
  AbstractAliasAwareAnnotationAttributeExtractor and
  DefaultAnnotationAttributeExtractor implementation classes.

- Introduced MapAnnotationAttributeExtractor for synthesizing an
  annotation that is backed by a map or AnnotationAttributes instance.

- Introduced a variant of synthesizeAnnotation() in AnnotationUtils
  that accepts a map.

- Introduced findAnnotation(*) methods in AnnotatedElementUtils that
  synthesize merged AnnotationAttributes back into an annotation of the
  target type.

The following classes have been refactored to use the new support for
synthesizing AnnotationAttributes back into an annotation.

- ApplicationListenerMethodAdapter
- TestAnnotationUtils
- AbstractTestContextBootstrapper
- ActiveProfilesUtils
- ContextLoaderUtils
- DefaultActiveProfilesResolver
- DirtiesContextTestExecutionListener
- TestPropertySourceAttributes
- TestPropertySourceUtils
- TransactionalTestExecutionListener
- MetaAnnotationUtils
- MvcUriComponentsBuilder
- RequestMappingHandlerMapping

In addition, this commit also includes changes to ensure that arrays
returned by synthesized annotations are properly cloned first.

Issue: SPR-13067

Prior to this commit, when a nested array of annotations was
synthesized while adapting values within an AnnotationAttributes map,
the array was improperly replaced with an array of type Annotation[]
instead of an array of the concrete annotation type, which can lead to
unexpected run-time exceptions.

This commit fixes this bug by replacing annotations in the existing
array with synthesized versions of those annotations, thereby retaining
the original array's component type.

Issue: SPR-13077

This commit introduces support in AnnotationAttributes for retrieving
nested annotations that is on par with the existing type-safe support
for retrieving nested AnnotationAttributes.

Issue: SPR-13074

AnnotationAttributes has existed for several years, but none of the
"get" methods that make up its public API are documented. In many
cases, the behavior can be inferred from the name of the method, but
for some methods there are "hidden gems" and unexpected behavior
lurking behind the scenes.

This commit addresses this issue by documenting all public methods. In
addition, the hidden support for converting single elements into
single-element arrays has also been documented and tested.

Issue: SPR-13072

Issue: SPR-11513

Issue: SPR-11512

Issue: SPR-11512

Issue: SPR-11512

Issue: SPR-11512

Issue: SPR-11512

Issue: SPR-13066

Issue: SPR-11512

Issue: SPR-13065

This commit also introduces a cache for attribute alias metadata.

Issue: SPR-11512

Issue: SPR-11512

Issue: SPR-13064

Issue: SPR-11512

Issue: SPR-11512

Issue: SPR-13060

Includes an optimization for simple ByteBuffer duplication.

Issue: SPR-13056

Enable public visibility on SynthetizedAnnotation to allow annotation
outside its package to be proxied properly. This commit is pending a
unit test that actually reproduces the problem.

Issue: SPR-13057

This commit introduces first-class support for aliases for annotation
attributes. Specifically, this commit introduces a new @AliasFor
annotation that can be used to declare a pair of aliased attributes
within a single annotation or an alias from an attribute in a custom
composed annotation to an attribute in a meta-annotation.

To support @AliasFor within annotation instances, AnnotationUtils has
been overhauled to "synthesize" any annotations returned by "get" and
"find" searches. A SynthesizedAnnotation is an annotation that is
wrapped in a JDK dynamic proxy which provides run-time support for
@AliasFor semantics. SynthesizedAnnotationInvocationHandler is the
actual handler behind the proxy.

In addition, the contract for @AliasFor is fully validated, and an
AnnotationConfigurationException is thrown in case invalid
configuration is detected.

For example, @ContextConfiguration from the spring-test module is now
declared as follows:

    public @interface ContextConfiguration {

        @AliasFor(attribute = "locations")
        String[] value() default {};

        @AliasFor(attribute = "value")
        String[] locations() default {};

        // ...
    }

The following annotations and their related support classes have been
modified to use @AliasFor.

- @ManagedResource
- @ContextConfiguration
- @ActiveProfiles
- @TestExecutionListeners
- @TestPropertySource
- @Sql
- @ControllerAdvice
- @RequestMapping

Similarly, support for AnnotationAttributes has been reworked to
support @AliasFor as well. This allows for fine-grained control over
exactly which attributes are overridden within an annotation hierarchy.
In fact, it is now possible to declare an alias for the 'value'
attribute of a meta-annotation.

For example, given the revised declaration of @ContextConfiguration
above, one can now develop a composed annotation with a custom
attribute override as follows.

    @ContextConfiguration
    public @interface MyTestConfig {

        @AliasFor(
           annotation = ContextConfiguration.class,
           attribute = "locations"
        )
        String[] xmlFiles();

        // ...
    }

Consequently, the following are functionally equivalent.

- @MyTestConfig(xmlFiles = "test.xml")
- @ContextConfiguration("test.xml")
- @ContextConfiguration(locations = "test.xml").

Issue: SPR-11512, SPR-11513

Issue: SPR-12926

ByteBufferConverter also defensively returns the rewind result now.

Issue: SPR-13031

Issue: SPR-13024

Provide Converter implementations for Charset, Currency and TimeZone as
related PropertyEditors are available for those.

Issue: SPR-13020

Prior to this commit, the documentation in AnnotationUtils was
inconsistent, and at times even misleading, with regard to finding
annotations that are "present" or "directly present" on annotated
elements.

This commit defines the terminology used within AnnotationUtils and
introduces the explicit notion of "meta-present" to denote that
annotations are present within annotation hierarchies above annotated
elements.

Issue: SPR-13030

This commit updates the "get semantics" search algorithm used in
`AnnotatedElementUtils` so that locally declared 'composed annotations'
are favored over inherited annotations.

Specifically, the internal `searchWithGetSemantics()` method now
searches locally declared annotations before searching inherited
annotations.

All TODOs in `AnnotatedElementUtilsTests` have been completed, and all
ignored tests have been reinstated.

Issue: SPR-11598

Issue: SPR-13016

This commit improves the documentation for AnnotationUtils and
AnnotatedElementUtils by explaining that the scope of most annotation
searches is limited to finding the first such annotation, resulting in
additional such annotations being silently ignored.

Issue: SPR-13015

Issue: SPR-13007

In general, the Spring Framework aims to construct error message
strings only if an actual error has occurred. This seems to be the
common pattern in the codebase and saves both CPU and memory. However,
there are some places where eager error message formatting occurs
unnecessarily.

This commit addresses this issue in the following classes:
AdviceModeImportSelector, AnnotationAttributes, and
ReadOnlySystemAttributesMap.

The change in ReadOnlySystemAttributesMap also avoids a potential
NullPointerException.

Issue: SPR-13007

Prior to this commit, the `getAnnotation()` method in `TypeDescriptor`
only supported a single level of meta-annotations. In other words, the
annotation hierarchy would not be exhaustively searched.

This commit provides support for arbitrary levels of meta-annotations
in `TypeDescriptor` by delegating to `AnnotationUtils.findAnnotation()`
within `TypeDescriptor.getAnnotation()`.

Issue: SPR-12793