Interface Request

All Superinterfaces:
Attributes, Content.Source
All Known Subinterfaces:
Request.ServeAs, ServerUpgradeRequest, ServerUpgradeRequest
All Known Implementing Classes:
ContextHandler.CoreContextRequest, ContextHandler.CoreContextRequest, ContextRequest, ErrorHandler.ErrorRequest, GzipRequest, HeaderWrappingRequest, PathMappingsHandler.PathSpecRequest, Request.AttributesWrapper, Request.Wrapper, RewriteEncodingRule.EncodingHandler, RewriteEncodingRule.VaryHandler, RewriteLanguageRule.LanguageHandler, RewriteLanguageRule.VaryHandler, Rule.Handler, Rule.HttpURIHandler, SecureRequestCustomizer.SecureRequest, SecureRequestCustomizer.SecureRequestWithSslSessionData, ServletContextRequest, ServletContextRequest, ServletCoreRequest, ServletCoreRequest, ServletCoreRequest, ServletCoreRequest, SessionHandler.SessionRequest, StatisticsHandler.MinimumDataRateHandler.MinimumDataRateRequest
public interface Request extends Attributes, Content.Source

The representation of an HTTP request, for any protocol version (HTTP/1.1, HTTP/2, HTTP/3).

The typical idiom to read request content is the following:

public boolean handle(Request request, Response response, Callback callback)
{
    // Reject requests not appropriate for this handler.
    if (!request.getHttpURI().getPath().startsWith("/yourPath"))
        return false;

    while (true)
    {
        Content.Chunk chunk = request.read();
        if (chunk == null)
        {
            // The chunk is not currently available, demand to be called back.
            request.demand(() -> handle(request, response, callback));
            return true;
        }

        if (Content.Chunk.isError(chunk))
        {
            Throwable failure = error.getCause();

            // Handle errors.
            // If the chunk is not last, then the error can be ignored and reading can be tried again.
            // Otherwise, if the chunk is last, or we do not wish to ignore a non-last error, then
            // mark the handling as complete, either generating a custom
            // response and succeeding the callback, or failing the callback.
            callback.failed(failure);
            return true;
        }

        if (chunk instanceof Trailers trailers)
        {
            HttpFields fields = trailers.getTrailers();

            // Handle trailers.

            // Generate a response.

            // Mark the handling as complete.
            callback.succeeded();

            return true;
        }

        // Normal chunk, process it.
        processChunk(chunk);
        // Release the content after processing.
        chunk.release();

        // Reached end-of-file?
        if (chunk.isLast())
        {
            // Generate a response.

            // Mark the handling as complete.
            callback.succeeded();

            return true;
        }
    }
}

  • Field Details

    • LOG

      static final org.slf4j.Logger LOG

    • DEFAULT_LOCALES

      static final List<Locale> DEFAULT_LOCALES

  • Method Details

    • getId

      String getId()
      an ID unique within the lifetime scope of the ConnectionMetaData.getId()). This may be a protocol ID (e.g. HTTP/2 stream ID) or it may be unrelated to the protocol.
      See Also:

    • getComponents

      Components getComponents()
      Returns:
      the Components to be used with this Request.

    • getConnectionMetaData

      ConnectionMetaData getConnectionMetaData()
      Returns:
      the ConnectionMetaData associated to this Request

    • getMethod

      String getMethod()
      Returns:
      the HTTP method of this Request

    • getHttpURI

      HttpURI getHttpURI()
      Returns:
      the HTTP URI of this Request
      See Also:

    • getContext

      Context getContext()
      Get the Context associated with this Request.

      Note that a Request should always have an associated Context since if the Request is not being handled by a ContextHandler then the Context from Server.getContext() will be used.

      Returns:
      the Context associated with this Request. Never null.
      See Also:

    • getContextPath

      static String getContextPath(Request request)
      Get the context path of this Request. This is equivalent to request.getContext().getContextPath().
      Parameters:
      request - The request to get the context path from.
      Returns:
      The encoded context path of the Context or null.
      See Also:

    • getPathInContext

      static String getPathInContext(Request request)

      Returns the canonically encoded path of the URI, scoped to the current context.

      For example, when the request has a Context with contextPath=/ctx and the request's HttpURI canonical path is canonicalPath=/ctx/foo, then pathInContext=/foo.

      Returns:
      The part of the canonically encoded path of the URI after any context path prefix has been removed.
      See Also:

    • getHeaders

      HttpFields getHeaders()
      Returns:
      the HTTP headers of this Request

    • demand

      void demand(Runnable demandCallback)

      Demands to invoke the given demand callback parameter when a chunk of content is available.

      See how to use this method idiomatically.

      Implementations guarantee that calls to this method are safely reentrant so that stack overflows are avoided in the case of mutual recursion between the execution of the Runnable callback and a call to this method. Invocations of the passed Runnable are serialized and a callback for demand call is not invoked until any previous demand callback has returned. Thus the Runnable should not block waiting for a callback of a future demand call.

      The demand callback may be invoked spuriously: a subsequent call to Content.Source.read() may return null.

      Calling this method establishes a pending demand, which is fulfilled when the demand callback is invoked.

      Calling this method when there is already a pending demand results in an IllegalStateException to be thrown.

      If the invocation of the demand callback throws an exception, then Content.Source.fail(Throwable) is called.

      Specified by:
      demand in interface Content.Source
      Parameters:
      demandCallback - the demand callback to invoke when there is a content chunk available.
      See Also:

    • getTrailers

      HttpFields getTrailers()
      Returns:
      the HTTP trailers of this Request, or null if they are not present

    • getTimeStamp

      static long getTimeStamp(Request request)

      Get the millisecond timestamp at which the request was created, obtained with System.currentTimeMillis(). This method should be used for wall clock time, rather than getHeadersNanoTime(), which is appropriate for measuring latencies.

      Returns:
      The timestamp that the request was received/created in milliseconds

    • getBeginNanoTime

      long getBeginNanoTime()

      Get the nanoTime at which the request arrived to a connector, obtained via System.nanoTime(). This method can be used when measuring latencies.

      Returns:
      The nanoTime at which the request was received/created in nanoseconds

    • getHeadersNanoTime

      long getHeadersNanoTime()

      Get the nanoTime at which the request headers were parsed, obtained via System.nanoTime(). This method can be used when measuring latencies.

      Returns:
      The nanoTime at which the request was ready in nanoseconds

    • isSecure

      boolean isSecure()

    • read

      Content.Chunk read()

      Reads a chunk of content.

      See how to use this method idiomatically.

      The returned chunk could be:

      • null, to signal that there isn't a chunk of content available
      • an Content.Chunk instance with non null Content.Chunk.getFailure(), to signal that there was a failure trying to produce a chunk of content, or that the content production has been failed externally
      • a Content.Chunk instance, containing the chunk of content.

      Once a read returns an Content.Chunk instance with non-null Content.Chunk.getFailure() then if the failure is last further reads will continue to return the same failure chunk instance, otherwise further read() operations may return different non-failure chunks.

      Once a read returns a last chunk, further reads will continue to return a last chunk (although the instance may be different).

      The content reader code must ultimately arrange for a call to Retainable.release() on the returned Content.Chunk.

      Additionally, prior to the ultimate call to Retainable.release(), the reader code may make additional calls to Retainable.retain(), that must ultimately be matched by a correspondent number of calls to Retainable.release().

      Concurrent reads from different threads are not recommended, as they are inherently in a race condition.

      Reads performed outside the invocation context of a demand callback are allowed. However, reads performed with a pending demand are inherently in a race condition (the thread that reads with the thread that invokes the demand callback).

      In addition, the returned Content.Chunk may be a Trailers instance, in case of request content trailers.

      Specified by:
      read in interface Content.Source
      Returns:
      a chunk of content, possibly a failure instance, or null
      See Also:

    • consumeAvailable

      boolean consumeAvailable()
      Consume any available content. This bypasses any request wrappers to process the content in read() and reads directly from the HttpStream. This reads until there is no content currently available, or it reaches EOF. The HttpConfiguration.setMaxUnconsumedRequestContentReads(int) configuration can be used to configure how many reads will be attempted by this method.
      Returns:
      true if the content was fully consumed.

    • push

      default void push(MetaData.Request resource)

      Pushes the given resource to the client.

      Parameters:
      resource - the resource to push
      Throws:
      UnsupportedOperationException - if the push functionality is not supported
      See Also:

    • addIdleTimeoutListener

      void addIdleTimeoutListener(Predicate<TimeoutException> onIdleTimeout)

      Adds a listener for idle timeouts.

      The listener is a predicate function that should return true to indicate that the idle timeout should be handled by the container as a fatal failure (see addFailureListener(Consumer)); or false to ignore that specific timeout and for another timeout to occur after another idle period.

      Idle timeout listeners are only invoked if there are no pending demand(Runnable) or Response.write(boolean, ByteBuffer, Callback) operations.

      Listeners are processed in the same order they are added, and the first that returns true stops the processing of subsequent listeners, which are therefore not invoked.

      Parameters:
      onIdleTimeout - the idle timeout listener as a predicate function
      See Also:

    • addFailureListener

      void addFailureListener(Consumer<Throwable> onFailure)

      Adds a listener for asynchronous fatal failures.

      When a listener is called, the effects of the failure have already taken place:

      Listeners are processed in the same order they are added.

      Parameters:
      onFailure - the failure listener as a consumer function
      See Also:

    • getTunnelSupport

      TunnelSupport getTunnelSupport()

    • addHttpStreamWrapper

      void addHttpStreamWrapper(Function<HttpStream, HttpStream> wrapper)
      Add a HttpStream.Wrapper to the current HttpStream.
      Parameters:
      wrapper - A function that wraps the passed stream.
      See Also:

    • addCompletionListener

      static void addCompletionListener(Request request, Consumer<Throwable> listener)

      Adds a completion listener that is an optimized equivalent to overriding the Callback.succeeded() and Callback.failed(Throwable) methods of a HttpStream.Wrapper created by a call to addHttpStreamWrapper(Function).

      Because adding completion listeners relies on HttpStream wrapping, the completion listeners are invoked in reverse order they are added.

      In the case of a failure, the Throwable cause is passed to the listener, but unlike addFailureListener(Consumer) listeners, which are called when the failure occurs, completion listeners are called only once the HttpStream is completed at the very end of processing.

      Parameters:
      listener - A Consumer of Throwable to call when the request handling is complete. The listener is passed a null Throwable on success.
      See Also:

    • getSession

      Session getSession(boolean create)

      Get a Session associated with the request. Sessions may not be supported by a given configuration, in which case null will be returned.

      Parameters:
      create - True if the session should be created for the request.
      Returns:
      The session associated with the request or null.

    • asReadOnly

      static Request asReadOnly(Request request)
      Returns a copy of the request that throws UnsupportedOperationException from all mutative methods.
      Returns:
      a copy of the request

    • getHostName

      static String getHostName(InetSocketAddress inetSocketAddress)

    • getLocalAddr

      static String getLocalAddr(Request request)

    • getLocalPort

      static int getLocalPort(Request request)

    • getRemoteAddr

      static String getRemoteAddr(Request request)

    • getRemotePort

      static int getRemotePort(Request request)

    • getServerName

      static String getServerName(Request request)
      Get the logical name the request was sent to, which may be from the authority of the request; the configured server authority; the actual network name of the server;
      Parameters:
      request - The request to get the server name of
      Returns:
      The logical server name or null if it cannot be determined.

    • getServerPort

      static int getServerPort(Request request)
      Get the logical port a request was received on, which may be from the authority of the request; the configured server authority; the default port for the scheme; or the actual network port.
      Parameters:
      request - The request to get the port of
      Returns:
      The port for the request if it can be determined, otherwise -1

    • getLocales

      static List<Locale> getLocales(Request request)

    • asInputStream

      static InputStream asInputStream(Request request)

    • getCharset

      static Charset getCharset(Request request) throws IllegalCharsetNameException, UnsupportedCharsetException
      Get a Charset from the request HttpHeader.CONTENT_TYPE, if any.
      Parameters:
      request - The request.
      Returns:
      A Charset or null
      Throws:
      IllegalCharsetNameException - If the charset name is illegal
      UnsupportedCharsetException - If no support for the charset is available

    • extractQueryParameters

      static Fields extractQueryParameters(Request request)

    • extractQueryParameters

      static Fields extractQueryParameters(Request request, Charset charset)

    • getParameters

      static Fields getParameters(Request request) throws Exception
      Throws:
      Exception

    • getParametersAsync

      @Deprecated(forRemoval=true, since="12.0.16") static CompletableFuture<Fields> getParametersAsync(Request request)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use onParameters(Request, Promise.Invocable) instead.

    • onParameters

      static void onParameters(Request request, Promise.Invocable<Fields> promise)
      Asynchronous version of getParameters(Request).
      Parameters:
      request - the request
      promise - the promise that will be completed with the parameters

    • getCookies

      static List<HttpCookie> getCookies(Request request)

    • getMultiPartConfig

      static MultiPartConfig.Builder getMultiPartConfig(Request request, Path location)

      Get a MultiPartConfig.Builder given a Request and a location.

      If the location is null this will extract the Context temp directory from the request. The maxHeaderSize, MultiPartCompliance, ComplianceViolation.Listener are also extracted from the request. Additional settings can be configured through the MultiPartConfig.Builder which is returned.

      Parameters:
      request - the request.
      location - the temp directory location, or null to use the context default.
      Returns:
      a MultiPartConfig with settings extracted from the request.

    • toRedirectURI

      @Deprecated static String toRedirectURI(Request request, String location)
      Deprecated.
      use Response.toRedirectURI(Request, String)
      Generate a proper "Location" header for redirects.
      Parameters:
      request - the request the redirect should be based on (needed when relative locations are provided, so that server name, scheme, port can be built out properly)
      location - the location URL to redirect to (can be a relative path)
      Returns:
      the full redirect "Location" URL (including scheme, host, port, path, etc...)

    • serveAs

      static Request serveAs(Request request, HttpURI uri)
      Return a request with its HttpURI changed to the supplied target. If the passed request or any of the requests that it wraps implements Request.ServeAs then Request.ServeAs.wrap(Request, HttpURI) will be used to do the wrap, otherwise a simple Request.Wrapper may be returned.
      Parameters:
      request - the original request.
      uri - the new URI to target.
      Returns:
      the possibly wrapped request to target the new URI.

    • as

      static <T> T as(Request request, Class<T> type)
      Unwrap a Request back to the given type.
      Parameters:
      request - the possibly wrapped request to unwrap
      type - the type to unwrap to
      Returns:
      the request unwrapped back to the given type or null if it cannot be unwrapped to the supplied type.

    • asInContext

      static <T extends Request> T asInContext(Request request, Class<T> type)
      Unwrap a Request back to the given type, ensuring that we do not cross a context boundary (as might be the case during cross-context dispatch).
      Parameters:
      request - the possibly wrapped request to unwrap
      type - the type to unwrap to
      Returns:
      the request unwrapped back to the given type, or null if it cannot be unwrapped to that type or a context boundary is crossed.

    • get

      static <T,R> R get(Request request, Class<T> type, Function<T,R> getter)

    • unWrap

      static Request unWrap(Request request)

    • getContentBytesRead

      static long getContentBytesRead(Request request)

    • newHttpURIFrom

      static HttpURI newHttpURIFrom(Request request, String newEncodedPathInContext)

      Creates a new HttpURI from the given Request's HttpURI and the given path in context.

      For example, for contextPath=/ctx, request.httpURI=http://host/ctx/path?a=b, and newPathInContext=/newPath, the returned HttpURI is http://host/ctx/newPath?a=b.

      Parameters:
      request - The request to base the new HttpURI on.
      newEncodedPathInContext - The new path in context for the new HttpURI
      Returns:
      A new immutable HttpURI with the path in context replaced, but query string and path parameters retained.

    • getAuthenticationState

      static Request.AuthenticationState getAuthenticationState(Request request)
      Parameters:
      request - The request to enquire.
      Returns:
      the minimal Request.AuthenticationState of the request, or null if no authentication in process.

    • setAuthenticationState

      static void setAuthenticationState(Request request, Request.AuthenticationState state)
      Parameters:
      request - The request to enquire.
      state - the Request.AuthenticationState of the request, or null if no authentication in process.