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 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 |
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.
|
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, pipeTostatic 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)
ReadStreamexceptionHandler in interface ReadStream<Buffer>exceptionHandler in interface StreamBasehandler - the exception handlerHttpServerRequest handler(Handler<Buffer> handler)
ReadStreamhandler in interface ReadStream<Buffer>HttpServerRequest pause()
ReadStreamReadStream, 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()
ReadStreamflowing mode.
If the ReadStream has been paused, reading will recommence on it.resume in interface ReadStream<Buffer>HttpServerRequest fetch(long amount)
ReadStreamamount 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)
ReadStreamendHandler 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 nameMultiMap 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()
SSLSessionX509Certificate[] 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()
nullHttpServerRequest 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 © 2022 Eclipse. All rights reserved.