Package io.muserver

Interface MuRequest

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.Object attribute​(java.lang.String key)
      Gets request-specific state that was added with attribute(String, Object).
      void attribute​(java.lang.String key, java.lang.Object value)
      Sets the given object as state associated with the given key that is bound to this request which any subsequent handlers can access.
      java.util.Map<java.lang.String,​java.lang.Object> attributes()
      Returns the map containing all the attributes.
      java.lang.String clientIP()
      Makes a best-effort guess at the client's IP address, taking into account any Forwarded or X-Forwarded-* headers.
      HttpConnection connection()  
      java.lang.String contentType()
      Gets the content type of the request body, for example application/json or null if there is no body.
      java.lang.String contextPath()
      If this handler was added to a ContextHandlerBuilder.context(String) then this will return the value of the context pre-pended with a '/'.
      java.util.Optional<java.lang.String> cookie​(java.lang.String name)
      Gets the value of the client-sent cookie with the given name
      java.util.List<Cookie> cookies()
      Gets all the client-sent cookies
      RequestParameters form()
      Gets the form parameters for this request.
      AsyncHandle handleAsync()
      Specifies that you want to handle this response asynchronously.
      Headers headers()  
      java.util.Optional<java.io.InputStream> inputStream()
      The input stream of the request, if there was a request body.
      boolean isAsync()  
      Method method()  
      java.lang.String protocol()
      The protocol for the request.
      RequestParameters query()
      Gets the querystring parameters for this request.
      java.lang.String readBodyAsString()
      Returns the request body as a string.
      java.lang.String relativePath()
      The path of this request (without query string) relative to the context.
      java.lang.String remoteAddress()
      Gets the address that the request came from.
      MuServer server()  
      java.net.URI serverURI()
      The URI of the request for this server.
      long startTime()  
      UploadedFile uploadedFile​(java.lang.String name)
      Gets the uploaded file with the given name, or null if there is no upload with that name.
      java.util.List<UploadedFile> uploadedFiles​(java.lang.String name)
      Gets all the uploaded files with the given name, or an empty list if none are found.
      java.net.URI uri()
      The URI of the request at the origin.

    • Method Detail

      • contentType

        java.lang.String contentType()

        Gets the content type of the request body, for example application/json or null if there is no body.

        Note: If the Content-Type header included a charset, then this will NOT be returned by this method. In order to get the charset, use request.headers().contentType() and access the charset parameter on that.

        Returns:
        The content type of the request body (specified by the Content-Type request header), or null if there is no body.
        See Also:
        Headers.contentType()

      • startTime

        long startTime()
        Returns:
        The time as epoch millis when this request was received on the server.

      • method

        Method method()
        Returns:
        The request method, e.g. GET or POST

      • uri

        java.net.URI uri()
        The URI of the request at the origin.

        If behind a reverse proxy, this URI should be the URI that the client saw when making the request.

        Returns:
        The full request URI

      • serverURI

        java.net.URI serverURI()
        The URI of the request for this server.

        If behind a reverse proxy, this will be different from uri() as it is the actual server URI rather than what the client sees.

        Returns:
        The full request URI

      • headers

        Headers headers()
        Returns:
        The request headers

      • inputStream

        java.util.Optional<java.io.InputStream> inputStream()

        The input stream of the request, if there was a request body.

        If you call this method and an input stream is available, then you must close the input stream.

        Also note that this can only be read once and cannot be used with readBodyAsString() or form().

        Returns:
        Optional.empty() if there is no request body; otherwise the input stream of the request body.

      • readBodyAsString

        java.lang.String readBodyAsString()
                           throws java.io.IOException
        Returns the request body as a string.

        This is a blocking call which waits until the whole request is available. If you need the raw bytes, or to stream the request body, then use the inputStream() instead.

        The content type of the request body is assumed to be UTF-8 if no encoding is specified

        Note: this can only be read once and cannot be used with inputStream() ()} or form().

        Returns:
        The content of the request body, or an empty string if there is no request body
        Throws:
        java.io.IOException - if there is an exception during reading the request, e.g. if the HTTP connection is stopped during a request

      • uploadedFiles

        java.util.List<UploadedFile> uploadedFiles​(java.lang.String name)
                                    throws java.io.IOException
        Gets all the uploaded files with the given name, or an empty list if none are found.
        Parameters:
        name - The file input name to get
        Returns:
        All the files with the given name
        Throws:
        java.io.IOException - Thrown when there is an error while reading the file, e.g. if a user closes their browser before the upload is complete.

      • uploadedFile

        UploadedFile uploadedFile​(java.lang.String name)
                   throws java.io.IOException

        Gets the uploaded file with the given name, or null if there is no upload with that name.

        If there are multiple files with the same name, the first one is returned.

        Parameters:
        name - The querystring parameter name to get
        Returns:
        The querystring value, or an empty string
        Throws:
        java.io.IOException - Thrown when there is an error while reading the file, e.g. if a user closes their browser before the upload is complete.

      • query

        RequestParameters query()

        Gets the querystring parameters for this request.

        Returns:
        Returns an object allowing you to access the querystring parameters of this request.

      • form

        RequestParameters form()
                throws java.io.IOException

        Gets the form parameters for this request.

        Note: this cannot be called after a call to inputStream() or readBodyAsString()

        Returns:
        Returns an object allowing you to access the form parameters of this request.
        Throws:
        java.io.IOException - Thrown when there is an error while reading the form, e.g. if a user closes their browser before the form is fully read into memory.

      • cookies

        java.util.List<Cookie> cookies()
        Gets all the client-sent cookies
        Returns:
        A list of cookie objects in the order the client sent them

      • cookie

        java.util.Optional<java.lang.String> cookie​(java.lang.String name)
        Gets the value of the client-sent cookie with the given name
        Parameters:
        name - The name of the cookie
        Returns:
        The cookie, or Optional.empty() if there is no cookie with that name.

      • contextPath

        java.lang.String contextPath()

        If this handler was added to a ContextHandlerBuilder.context(String) then this will return the value of the context pre-pended with a '/'.

        For example, if this handler was added to ContextHandlerBuilder.context("some context") this this method will return /some%20context

        Returns:
        The context of the current handler or '/' if there is no context.
        See Also:
        relativePath()

      • relativePath

        java.lang.String relativePath()

        The path of this request (without query string) relative to the context. If this handler is not nested within a context then it simply returns the full path of the request, otherwise it is the path relative to contextPath().

        For example, if there is a context some context and there is a request to /some%20context/some%20path then this method will return /some%20path

        Returns:
        The relative path of this request.
        See Also:
        contextPath()

      • attribute

        java.lang.Object attribute​(java.lang.String key)

        Gets request-specific state that was added with attribute(String, Object).

        An example is getting user information in a view handler that was previously set by an authentication handler.

        Parameters:
        key - The key the object is associated with.
        Returns:
        An object previously set by attribute(String, Object), or null if it was never set.

      • attribute

        void attribute​(java.lang.String key,
               java.lang.Object value)

        Sets the given object as state associated with the given key that is bound to this request which any subsequent handlers can access.

        An example use case is if you have a authentication handler that uses this method to set user information on the request, and then a subsequent handler calls attribute(String) to get the user info.

        Parameters:
        key - The key to associate the value with.
        value - Any object to store as state.

      • attributes

        java.util.Map<java.lang.String,​java.lang.Object> attributes()

        Returns the map containing all the attributes.

        Any changes made with attribute(String, Object) to the map will be reflected on this returned map.

        Returns:
        All attributes set with attribute(String, Object)

      • handleAsync

        AsyncHandle handleAsync()

        Specifies that you want to handle this response asynchronously.

        When finished, call AsyncHandle.complete()

        If called more than once, then the async handle created from the first call is returned.

        Returns:
        An object that you can use to mark the response as complete.

      • remoteAddress

        java.lang.String remoteAddress()
        Gets the address that the request came from. Warning: this may not be the client's address and instead may be an intermediary such as a network gateway.

        This is a convenience method that returns connection().remoteAddress().getHostString()

        If you want to know the client's IP address when reverse proxies are used, consider using clientIP()

        Returns:
        The IP address of the client, or of a gateway with NAT, etc, or null if the client has already disconnected.

      • clientIP

        java.lang.String clientIP()
        Makes a best-effort guess at the client's IP address, taking into account any Forwarded or X-Forwarded-* headers.

        Warning: Forwarded headers supplied from outside the perimeter of your network should not be trusted at it is trivial for clients to specify arbitrary Forwarded headers when making requests. Therefore it may be advisable for reverse proxies at the perimeter of your network to drop any Forwarded headers from untrusted networks before added their own headers.

        If there are no forwarded headers then the IP address of the socket connection is used (i.e. connection().remoteAddress().getHostString()).

        Returns:
        A string containing an IP address.

      • server

        MuServer server()
        Returns:
        Returns a reference to the mu server instance.

      • isAsync

        boolean isAsync()
        Returns:
        Returns try if handleAsync() has been called and this is an async response

      • protocol

        java.lang.String protocol()
        The protocol for the request.
        Returns:
        A string such as HTTP/1.1 or HTTP/2

      • connection

        HttpConnection connection()
        Returns:
        The HTTP connection that this request is sent over.