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

This commit turns suspendReading() into a readingPaused() notification
that is invoked after a succession of reads stops because there is no
more demand. Sub-classes can use this notification to suspend, if that
applies to them.

Most importantly the notification is guaranteed not to overlap with
checkOnDataAvailable() which means that suspend does not need to be
atomic and guarded against resume. The two can and do compete all the
time when reading ends with no demand, and a request for demand arrives
concurrently.

Issue: SPR-16207

- When there is no demand for reading, the implementation
should suspend reading otherwise useless events will be
send by Undertow to the registered read listener.
- There is not need to wait for an event for reading/writing after calling
resumeReads/resumeWrites

Issue: SPR-15964

This commit changes the way Undertow's PooledByteBuffers are dealt with.
Previously, these buffers where closed as soon as all data was read. As
of this commit, the UndertowServerHttpRequest returns PooledDataBuffers
from getBody(), so that the buffers are released when release() is
called.

Concrete server and client, reactive request and response
implementations should not have to be accessed outside their package.
They could be seen as private to their HttpHandler adapters and
ClientHttpConnector's respectively.

The one exception, WebSocket upgrades in spring-webflux, is an internal
framework use case, accommodated via downcast + accessors in the
abstract base classes.

Issue: SPR-15869

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

The new structured getPath() method replaces the existing
getContextPath() + getPathWithinApplication().

Issue: SPR-15648

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

When reading more that once for a given request, the position/limit of
the buffer provided by Undertow should be reset in order to use the
full capacity of the buffer.

This commit introduces a new method in HttpRequest:
`String getMethodValue`, which returns the HTTP method as a String.
Furthermore, HttpRequest.getMethod() has been given a default
implementation using this String value in combination with
`HttpMethod.resolve`.

Issue: SPR-15545

Issue: SPR-15576

Issue: SPR-15200

In addition to the updates from PR#1297 this commit adds an integration
test and fixes for the resulting failures with RxNetty, Reactor Netty,
and Undertow.

Also replaced use of URLDecoder which is not for decoding URIs with use
of UriUtils for decoding query parameters.

Issue: SPR-15140

Ensure there is no "?" at the end of the generated URI when there is
no query available.

The Undertow HttpServerExchange has a complete listener which we can
use instead of the close() method UndertowServerHttpRequest.

- lazy allocate the PooledByteBuffer, only if there is a request body
  for reading
- close the PooledByteBuffer once the request finishes

AbstractRequestBodyPublisher and AbstractResponseBodyProcessor are now
used for WebSocket messages too and have been renamed more generally to
AbstractListenerReadPublisher and AbstractListenerWriteProcessor.

Issue: SPR-14527

In preparation for use with WebSockets.

Issue: SPR-14527

This commit replaces the lazy URI and headers initialization in the
reactive ServerHttpRequest in favor of eager initialization at
construction time. Both the URI and headers are nearly guaranteed to
be accessed for every request (URI for application path, headers for
"Origin" header).

Query params are still lazily parsed but parsing is idemptotent and
in the unlikely case of concurrent access (it's the framework that
typically accesses query params) it maybe parsed twice but should
be side effect free still.

Cookies are also parsed lazily and since we delegate to the "native"
request, it depends on the underlying runtime whether synchronization
is needed. This commit adds synchronization for the HttpServletRequest.
At present RxNetty, Reactor, and Undertow implementations provide
thread-safe access to cookies.

Ensure type-level Javadoc in every class, comply with guidelines for
80 char on Javadoc, and minor polish.

The state machine is refactored in order to solve various concurrency
issues.

Refactored Undertow support to register a response listener only when
the body is written to, as opposed to registering it at startup. The
reason for this is that getting the response channel from the
HttpServerExchange commits the status and response, making it impossible
to change them after the fact.

Fixed issue #119.

Consistent initialization of HttpHeaders and the cookies map.
 - allow sub-classes to create instance
 - make unmodifiable

There is now an HttpCookie (simple name-value pair) and separately a
ServerHttpCookie sub-class with additional attributes that a server
can send to clients.

HttpHeaders is no longer the place to access cookies. Instead there is
a read-only HttpCookie map on ServerHttpRequest and a mutable
ServerHttpCookie map on ServerHttpResponse.

Cookies are stored in a map that preserves their order.

-> reactor.Mono : reactor.core.publisher.Mono
-> reactor.Flux : reactor.core.publisher.Flux
-> reactor.Processors : reactor.core.publisher.Processors
-> reactor.Timers : reactor.core.timer.Timers
-> reactor.Subscribers : reactor.core.subscriber.Subscribers

HttpCookie is now immutable with factory methods to create a client
cookie (name-value) vs a server cookie (name-value + attributes)
including a builder for the latter.

Flux and Mono are used both for implementation and exposed at API
level to express 1 versus N semantic and to provide default Rx
operators:
- Flux<T> for multiple values Publisher (issue #48)
- Mono<T> for single value Publisher (issue #50)
- Mono<Void> for Publisher with no value (issue #49)

For those runtimes that don't directly support Reacitve Streams this
commit separates more formally Reactive Streams bridge code out of
the request and response implementations which become simple adapters
to the ServerHttpRequest/Response contracts like their RxNetty and
Reactor Net counterparts.