This commit fixes an issue where DataBufferUtils.join() would not
release databuffers that preceded an error signal.

Issue: SPR-17025

Issue: SPR-17188

Fix checkstyle violations for javadoc.

Issue: SPR-16968

(cherry picked from commit a2765c00)

This commit introduces DataBuffer.asInputStream(boolean), that can
release the underlying buffer when the stream is closed.

Furthermore, this commit adds additional javadoc.

Issue: SPR-16444

Issue: SPR-16337

Issue: SPR-16365

Fixed by creating `Callable`-based variants, as explained in the JIRA
issue.

Issue: SPR-16403

Use DataBufferUtils.compose instead of writeAggregator to combine
multiple data buffers into one, as the write aggregator would not work
when the initial data buffer did not have enough capacity to contain
all subsequent buffers.

Removed writeAggregator, as it is no longer needed.

Issue: SPR-16365

Added a utility method that composes data buffers into a single buffer.
Depending on the `DataBuffer` implementation, the returned buffer may be
a single buffer containing all data of the provided buffers, or it may
be a true composite that contains references to the buffers.

Issue: SPR-16365

As a consequence of dropping CompositeByteBuf (see prior commit),
DataBuffers fluxes that are aggregated with Flux.reduce(BiFunction) are
now required to be released, as the composite no longer holds a
reference to subsequent data buffers.

For this purpose, DataBufferUtils now has a writeAggregator that can be
used with Flux.reduce, and that released the subsequent buffers
properly.

Issue: SPR-16351

Prior to this commit, NettyDataBuffer had a optimization in
write(ByteBuf...), where it used a CompositeByteBuf to hold the original
and the parameter buffer.
Unfortunately, this procedure has nasty consequences when splicing
buffers (see https://stackoverflow.com/a/48111196/839733).

As of this commit, NettyDataBuffer stopped using CompositeByteBuf, and
 simply does ByteBuf.write().

Issue: SPR-16351

Issue: SPR-16156

This commit uses the existing CompositeByteBuf if present, as opposed
to creating a new composite for every call to
NettyDataBuffer.write(ByteBuf...)

Issue: SPR-16180

This commit introduces various improvements in DataBuffer:

- DataBuffer now exposes its read and write position, as well as its
capacity and writable byte count.
- Added DataBuffer.asByteBuffer(int, int)
- DataBufferUtils.read now reads directly into a DataBuffer, rather than
copying a ByteBuffer into a DataBuffer
- TomcatHttpHandler now reads directly into a DataBuffer

Issues: SPR-16068 SPR-16070

This commit introduces the following changes.

1) It adds a new Spring @NonNull annotation which allows to apply
@NonNullApi semantic on a specific element, like @Nullable does.
Combined with @Nullable, it allows partial null-safety support when
package granularity is too broad.

2) @Nullable and @NonNull can apply to ElementType.TYPE_USE in order
to be used on generic type arguments (SPR-15942).

3) Annotations does not apply to ElementType.TYPE_PARAMETER anymore
since it is not supported yet (applicability for such use case is
controversial and need to be discussed).

4) @NonNullApi does not apply to ElementType.FIELD anymore since in a
lot of use cases (private, protected) it is not part for the public API
+ its usage should remain opt-in. A dedicated @NonNullFields annotation
has been added in order to set fields default to non-nullable.

5) Updated Javadoc and reference documentation.

Issue: SPR-15756

This commit fixes an issue in the DataBufferUtils.write variant that
takes a AsynchronousFileChannel.

Issue: SPR-15798

Currently ResourceEncoder and ResourceRegionEncoder use DataBufferUtils
to read resource with an AsynchronousFileChannel if it is a file or
otherwise fallback on getting the channel from the resource.

The same is now required in other places where a Resource needs to be
read and is also generally useful.

Issue: SPR-15773

This commit changes the write methods to return `Flux<DataBuffer>`
instead of `Mono<Void>`, giving access to the original buffers,
so that they can decided whether the buffers need to be closed or not.

Issue: SPR-15726

This commit adds an overloaded write method to `DataBufferUtils`. There
are three parameter variants: `OutputStream`, `WritableByteChannel`, and
`AsynchronousFileChannel`.

Issue: SPR-15726

This commit introduces a JUnit rule that detects ByteBuf leaks in
subclasses of AbstractDataBufferAllocatingTestCase.

This commits extends nullability declarations to the field level, formalizing the interaction between methods and their underlying fields and therefore avoiding any nullability mismatch.

Issue: SPR-15720

Issue: SPR-15686

This commit improves the capacity calculation for the DefaultDataBuffer,
so that the capacity typically doubles instead of improving by the
minimal required amount.

Issue: SPR-15647

Beyond just formally declaring the current behavior, this revision actually enforces non-null behavior in selected signatures now, not tolerating null values anymore when not explicitly documented. It also changes some utility methods with historic null-in/null-out tolerance towards enforced non-null return values, making them a proper citizen in non-null assignments.

Some issues are left as to-do: in particular a thorough revision of spring-test, and a few tests with unclear failures (ignored as "TODO: NULLABLE") to be sorted out in a follow-up commit.

Issue: SPR-15540

This commit introduces 2 new @Nullable and @NonNullApi
annotations that leverage JSR 305 (dormant but available via
Findbugs jsr305 dependency and already used by libraries
like OkHttp) meta-annotations to specify explicitly
null-safety of Spring Framework parameters and return values.

In order to avoid adding too much annotations, the
default is set at package level with @NonNullApi and
@Nullable annotations are added when needed at parameter or
return value level. These annotations are intended to be used
on Spring Framework itself but also by other Spring projects.

@Nullable annotations have been introduced based on Javadoc
and search of patterns like "return null;". It is expected that
nullability of Spring Framework API will be polished with
complementary commits.

In practice, this will make the whole Spring Framework API
null-safe for Kotlin projects (when KT-10942 will be fixed)
since Kotlin will be able to leverage these annotations to
know if a parameter or a return value is nullable or not. But
this is also useful for Java developers as well since IntelliJ
IDEA, for example, also understands these annotations to
generate warnings when unsafe nullable usages are detected.

Issue: SPR-15540

Issue: SPR-15318

Currently the BOM versions are:

* reactor-core 3.0.6.BUILD-SNAPSHOT
* reactor-netty 0.6.2.BUILD-SNAPSHOT

This commit fixes as well a few deprecations in reactor-core.

This commit adds an overloaded DataBufferUtils.read method that operates
on a AsynchronousFileChannel (as opposed to a ReadableByteChannel, which
already existed). This commit also uses said method in the Resource
encoders, if the Resource is a file.

This commit adds a ByteArrayDecoder and ByteArrayEncoder.

DefaultDataBuffer.grow(int):
- Copy only the remaining data
- Update readPosition/writePosition