public interface HttpServerRequest extends ReadStream<Buffer>
Instances are created for each request and passed to the user via a handler.
Each instance of this class is associated with a corresponding HttpServerResponse
instance via
response()
.
It implements ReadStream
so it can be used with
Pipe
to pipe data with flow control.
Modifier and Type | Field and Description |
---|---|
static Handler<HttpServerRequest> |
DEFAULT_INVALID_REQUEST_HANDLER
The default invalid request handler, it uses the
decoderResult() cause and the request information
to determine the status code of the response to be sent. |
Modifier and Type | Method and Description |
---|---|
String |
absoluteURI() |
Future<Buffer> |
body()
Convenience method for receiving the entire request body in one piece.
|
default HttpServerRequest |
body(Handler<AsyncResult<Buffer>> handler)
Same as
body() but with an handler called when the operation completes |
default HttpServerRequest |
bodyHandler(Handler<Buffer> bodyHandler)
Convenience method for receiving the entire request body in one piece.
|
long |
bytesRead() |
HttpConnection |
connection() |
default int |
cookieCount() |
default Map<String,Cookie> |
cookieMap()
Deprecated.
the implementation made a wrong assumption that cookies could be identified only by their name. The RFC
states that the tuple of
<name, domain, path> is the unique identifier.
When more than one cookie has the same name, the map will hold that lost one to be parsed and any previously parsed
value will be silently overwritten. |
Set<Cookie> |
cookies()
Returns a modifiable set of parsed cookies from the
COOKIE header. |
Set<Cookie> |
cookies(String name)
Returns a read only set of parsed cookies that match the given name, or an empty set.
|
HttpServerRequest |
customFrameHandler(Handler<HttpFrame> handler)
Set a custom frame handler.
|
io.netty.handler.codec.DecoderResult |
decoderResult() |
Future<Void> |
end()
Returns a future signaling when the request has been fully received successfully or failed.
|
default void |
end(Handler<AsyncResult<Void>> handler)
Same as
end() but with an handler called when the operation completes |
HttpServerRequest |
endHandler(Handler<Void> endHandler)
Set an end handler.
|
HttpServerRequest |
exceptionHandler(Handler<Throwable> handler)
Set an exception handler on the read stream.
|
HttpServerRequest |
fetch(long amount)
Fetch the specified
amount of elements. |
MultiMap |
formAttributes()
Returns a map of all form attributes in the request.
|
Cookie |
getCookie(String name)
Get the cookie with the specified name.
|
Cookie |
getCookie(String name,
String domain,
String path)
Get the cookie with the specified
<name, domain, path> . |
String |
getFormAttribute(String attributeName)
Return the first form attribute value with the specified name
|
default String |
getHeader(CharSequence headerName)
Return the first header value with the specified name
|
default String |
getHeader(String headerName)
Return the first header value with the specified name
|
default String |
getParam(String paramName)
Return the first param value with the specified name
|
default String |
getParam(String paramName,
String defaultValue)
Return the first param value with the specified name or
defaultValue when the query param is not present |
String |
getParamsCharset() |
HttpServerRequest |
handler(Handler<Buffer> handler)
Set a data handler.
|
MultiMap |
headers() |
String |
host() |
boolean |
isEnded()
Has the request ended? I.e.
|
boolean |
isExpectMultipart() |
default boolean |
isSSL() |
default SocketAddress |
localAddress() |
HttpMethod |
method() |
MultiMap |
params() |
String |
path() |
HttpServerRequest |
pause()
Pause the
ReadStream , it sets the buffer in fetch mode and clears the actual demand. |
X509Certificate[] |
peerCertificateChain()
Note: Java SE 5+ recommends to use javax.net.ssl.SSLSession#getPeerCertificates() instead of
of javax.net.ssl.SSLSession#getPeerCertificateChain() which this method is based on.
|
String |
query() |
default SocketAddress |
remoteAddress() |
HttpServerResponse |
response() |
HttpServerRequest |
resume()
Resume reading, and sets the buffer in
flowing mode. |
default HttpServerRequest |
routed(String route)
Marks this request as being routed to the given route.
|
String |
scheme() |
HttpServerRequest |
setExpectMultipart(boolean expect)
Call this with true if you are expecting a multi-part body to be submitted in the request.
|
HttpServerRequest |
setParamsCharset(String charset)
Override the charset to use for decoding the query parameter map, when none is set,
UTF8 is used. |
default SSLSession |
sslSession() |
default int |
streamId() |
default StreamPriority |
streamPriority() |
HttpServerRequest |
streamPriorityHandler(Handler<StreamPriority> handler)
Set an handler for stream priority changes
|
Future<NetSocket> |
toNetSocket()
Like
toNetSocket(Handler) but returns a Future of the asynchronous result |
default void |
toNetSocket(Handler<AsyncResult<NetSocket>> handler)
Establish a TCP tunnel with the client.
|
Future<ServerWebSocket> |
toWebSocket()
Like
toWebSocket(Handler) but returns a Future of the asynchronous result |
default void |
toWebSocket(Handler<AsyncResult<ServerWebSocket>> handler)
Upgrade the connection of the current request to a WebSocket.
|
HttpServerRequest |
uploadHandler(Handler<HttpServerFileUpload> uploadHandler)
Set an upload handler.
|
String |
uri() |
HttpVersion |
version() |
pipe, pipeTo, pipeTo
static final Handler<HttpServerRequest> DEFAULT_INVALID_REQUEST_HANDLER
decoderResult()
cause and the request information
to determine the status code of the response to be sent.
io.netty.handler.codec.TooLongFrameException
and the error message
starts with An HTTP line is larger than the REQUEST_URI_TOO_LONG
status is sent io.netty.handler.codec.TooLongFrameException
and the error message
starts with HTTP header is larger than the REQUEST_HEADER_FIELDS_TOO_LARGE
status is sentBAD_REQUEST
status is sentHttpServerRequest exceptionHandler(Handler<Throwable> handler)
ReadStream
exceptionHandler
in interface ReadStream<Buffer>
exceptionHandler
in interface StreamBase
handler
- the exception handlerHttpServerRequest handler(Handler<Buffer> handler)
ReadStream
handler
in interface ReadStream<Buffer>
HttpServerRequest pause()
ReadStream
ReadStream
, it sets the buffer in fetch
mode and clears the actual demand.
While it's paused, no data will be sent to the data handler
.
pause
in interface ReadStream<Buffer>
HttpServerRequest resume()
ReadStream
flowing
mode.
If the ReadStream
has been paused, reading will recommence on it.resume
in interface ReadStream<Buffer>
HttpServerRequest fetch(long amount)
ReadStream
amount
of elements. If the ReadStream
has been paused, reading will
recommence with the specified amount
of items, otherwise the specified amount
will
be added to the current stream demand.fetch
in interface ReadStream<Buffer>
HttpServerRequest endHandler(Handler<Void> endHandler)
ReadStream
endHandler
in interface ReadStream<Buffer>
HttpVersion version()
HttpMethod method()
default boolean isSSL()
NetSocket
is encrypted via SSL/TLSString scheme()
String uri()
String path()
String query()
String host()
long bytesRead()
HttpServerResponse response()
HttpServerResponse
instance attached to it. This is used
to send the response back to the client.MultiMap headers()
default String getHeader(String headerName)
headerName
- the header namedefault String getHeader(CharSequence headerName)
headerName
- the header nameHttpServerRequest setParamsCharset(String charset)
UTF8
is used.charset
- the charset to use for decoding query paramsString getParamsCharset()
MultiMap params()
default String getParam(String paramName)
paramName
- the param namedefault String getParam(String paramName, String defaultValue)
defaultValue
when the query param is not presentparamName
- the param namedefaultValue
- the default value, must be non-nulldefaultValue
when not presentdefault SocketAddress remoteAddress()
null
(e.g a server bound on a domain socket).
If useProxyProtocol
is set to true
, the address returned will be of the actual connecting client.default SocketAddress localAddress()
null
(e.g a server bound on a domain socket)
If useProxyProtocol
is set to true
, the address returned will be of the proxy.default SSLSession sslSession()
SSLSession
X509Certificate[] peerCertificateChain() throws SSLPeerUnverifiedException
sslSession()
to
access that method.SSLPeerUnverifiedException
- SSL peer's identity has not been verified.SSLSession.getPeerCertificateChain()
,
sslSession()
String absoluteURI()
default HttpServerRequest bodyHandler(Handler<Buffer> bodyHandler)
This saves the user having to manually setting a data and end handler and append the chunks of the body until the whole body received. Don't use this if your request body is large - you could potentially run out of RAM.
bodyHandler
- This handler will be called after all the body has been receiveddefault HttpServerRequest body(Handler<AsyncResult<Buffer>> handler)
body()
but with an handler
called when the operation completesFuture<Buffer> body()
This saves you having to manually set a dataHandler and an endHandler and append the chunks of the body until the whole body received. Don't use this if your request body is large - you could potentially run out of RAM.
default void end(Handler<AsyncResult<Void>> handler)
end()
but with an handler
called when the operation completesFuture<Void> end()
default void toNetSocket(Handler<AsyncResult<NetSocket>> handler)
This must be called only for CONNECT
HTTP method or for HTTP connection upgrade, before any response is sent.
Calling this sends a 200
response for a CONNECT
or a 101
for a connection upgrade wit
no content-length
header set and then provides the NetSocket
for handling the created tunnel.
Any HTTP header set on the response before calling this method will be sent.
server.requestHandler(req -> { if (req.method() == HttpMethod.CONNECT) { // Send a 200 response to accept the connect NetSocket socket = req.netSocket(); socket.handler(buff -> { socket.write(buff); }); } ... });
handler
- the completion handlerFuture<NetSocket> toNetSocket()
toNetSocket(Handler)
but returns a Future
of the asynchronous resultHttpServerRequest setExpectMultipart(boolean expect)
expect
- true - if you are expecting a multi-part bodyboolean isExpectMultipart()
setExpectMultipart(boolean)
.HttpServerRequest uploadHandler(Handler<HttpServerFileUpload> uploadHandler)
MultiMap formAttributes()
Be aware that the attributes will only be available after the whole body has been received, i.e. after the request end handler has been called.
setExpectMultipart(boolean)
must be called first before trying to get the form attributes.
String getFormAttribute(String attributeName)
attributeName
- the attribute namedefault int streamId()
default void toWebSocket(Handler<AsyncResult<ServerWebSocket>> handler)
This is an alternative way of handling WebSockets and can only be used if no WebSocket handler is set on the
HttpServer
, and can only be used during the upgrade request during the WebSocket handshake.
Both handler(Handler)
and endHandler(Handler)
will be set to get the full body of the
request that is necessary to perform the WebSocket handshake.
If you need to do an asynchronous upgrade, i.e not performed immediately in your request handler,
you need to pause()
the request in order to not lose HTTP events necessary to upgrade the
request.
handler
- the completion handlerFuture<ServerWebSocket> toWebSocket()
toWebSocket(Handler)
but returns a Future
of the asynchronous resultboolean isEnded()
HttpServerRequest customFrameHandler(Handler<HttpFrame> handler)
HttpConnection connection()
HttpConnection
associated with this requestdefault StreamPriority streamPriority()
null
HttpServerRequest streamPriorityHandler(Handler<StreamPriority> handler)
This is not implemented for HTTP/1.x.
handler
- the handler to be called when stream priority changesio.netty.handler.codec.DecoderResult decoderResult()
HttpServer.invalidRequestHandler(io.vertx.core.Handler<io.vertx.core.http.HttpServerRequest>)
Cookie getCookie(String name)
Cookie
that matches the given name, to get all cookies for this name
see: cookies(String)
name
- the cookie namenull
if not found.Cookie getCookie(String name, String domain, String path)
<name, domain, path>
.name
- the cookie namedomain
- the cookie domainpath
- the cookie pathnull
if not found.default int cookieCount()
@Deprecated default Map<String,Cookie> cookieMap()
<name, domain, path>
is the unique identifier.
When more than one cookie has the same name, the map will hold that lost one to be parsed and any previously parsed
value will be silently overwritten.Set<Cookie> cookies(String name)
<name, domain, path>
tuple.
The set entries are references to the request original set. This means that performing property changes in the
cookie objects will affect the original object too.
NOTE: the returned Set
is read-only. This means any attempt to modify (add or remove to the set), will
throw UnsupportedOperationException
.name
- the name to be matchesSet<Cookie> cookies()
COOKIE
header. Several cookies may share the
same name but have different keys. A cookie is unique by its <name, domain, path>
tuple.
Request cookies are directly linked to response cookies. Any modification to a cookie object in the returned set
will mark the cookie to be included in the HTTP response. Removing a cookie from the set, will also mean that it
will be removed from the response, regardless if it was modified or not.default HttpServerRequest routed(String route)
route
- The route this request has been routed to.Copyright © 2023 Eclipse. All rights reserved.