Replace all API links with the correct springsource.org URL

Issue: SPR-10050

Convert all docbook XML files to well-formed docbook 5 syntax:
 - Include xsi:schemaLocation element for tools support
 - Convert all id elements to xml:id
 - Convert all ulink elements to link
 - Simplify <lineannotation> mark-up
 - Fix misplaced </section> tags
 - Fix <interface> tags to <interfacename>
 - Cleanup trailing whitespace and tabs

Issue: SPR-10032

Update reference manual with details of Java configuration @Enable*
annotations. Examples of Java style @Configuration is provided
when appropriate alongside existing XML samples.

Several existing @Configuration samples have been changed to placing
the @Enable annotation below the @Configuration annotation.
This has been done to provide consistency with existing Javadoc.

Issue: SPR-9920

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

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

Problems

 - Eliminate — in favor of —

   — was causing 'no such entity' errors during docbook
   processing; — produces the equivalent output.

 - Fix column issues in appendices

   column counts were set to 3, when they are in fact 4. This passed
   under DocBook 4 and Spring Build for unknown reasons, but caused a
   hard stop under DocBook 5 and the docbook-reference-plugin.

 - Add jdbc callout section in docbook 5-friendly style

   use <co/> tags as advertised in DocBook documentation.

 - Set correct widths for PDF ref doc images

   images were rendering larger than the PDF page; just set all to
   width=400 and everything looks good.

Polish

 - Update reference doc copyright to 2012

 - Remove "work-in-progress" language from ref docs

 - Update maven URLs to repo.springsource.org

 - Update javadoc urls from 3.0.x/javadoc-api => current/api

 - Replace hardcoded "3.1" with ${version} in ref doc

For compatibility with Gradle docbook-reference-plugin, which cannot
handle DocBook 4.

This change eliminates the spring-framework-reference subproject, moving
these sources into the root project's own src directory.

This makes sense because the reference docs span all submodules, and
also because api Javadoc is created at the root project level as well.
This means that both api and reference documentation output will now
reside in the root project's 'build' directory. This is more consistent
and easy to discover.

* documented that @Async can't be used in conjunction with lifecycle callbacks such as @PostConstruct
* provide sample for workaround
* added semantic markup for code

updated reference documentation now that the <executor/> and <scheduler/> element's 'size' attribute has been renamed to 'pool-size'