Package org.rapidcontext.core.web

Class Request

java.lang.Object
org.rapidcontext.core.web.Request
All Implemented Interfaces:
HttpUtil
public class Request extends Object implements HttpUtil
A request wrapper class. This class encapsulates the HTTP servlet request and response objects for simplified handling. It also provides limited support for file uploads.
Version:
1.0

  • Field Details

  • Constructor Details

    • Request

      public Request(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
      Creates a new request wrapper.
      Parameters:
      request - the servlet request
      response - the servlet response

  • Method Details

    • toString

      public String toString()
      Returns a string representation of this request.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this request

    • isFileUpload

      public boolean isFileUpload()
      Checks if this request contains a file upload. These requests must be handled differently from ordinary requests, since the normal request parameter access is limited to query parameters. Files can only be accessed by iterating through them with the getNextFile() method.
      Returns:
      true if this request contains a file upload, or false otherwise
      See Also:

    • hasMethod

      public boolean hasMethod(String method)
      Checks if the request method is the specified one. Normally the "GET" or "POST" methods are used, but other HTTP are sometimes also used (with other expected semantics).
      Parameters:
      method - the HTTP method name
      Returns:
      true if the method is the specified one, or false otherwise

    • hasResponse

      public boolean hasResponse()
      Checks if this request contains a response.
      Returns:
      true if the request contains a response, or false otherwise

    • getUrl

      public final String getUrl()
      Returns the full request URL with protocol, hostname, port and path. No query parameters will be included in the URL, however.
      Returns:
      the full request URL

    • getProtocol

      public final String getProtocol()
      Returns the protocol name in the request.
      Returns:
      the protocol name (i.e. "http" or "https")

    • getHost

      public final String getHost()
      Returns the host name in the request.
      Returns:
      the host name

    • getPort

      public final int getPort()
      Returns the port number in the request.
      Returns:
      the port number

    • getMethod

      public final String getMethod()
      Returns the request method name. Normally this is "GET" or "POST", but other HTTP methods can also be used.
      Returns:
      the request method name

    • getAbsolutePath

      public final String getAbsolutePath()
      Returns the full request path with file name. This path starts with a '/' character and contains the absolute request path, including the servlet path.
      Returns:
      the full request path with file name

    • getPath

      public final String getPath()
      Returns the local request path with file name. This path has been shortened to ONLY include the relevant portions of the path, removing any initial mapping URL portions of the path. A root path may thus be an empty string.
      Returns:
      the local request path

    • setPath

      public void setPath(String path)
      Sets the local request path. Use this method to shorten the request path from any additional prefixes. It can also be used to rewrite one request path into another.
      Parameters:
      path - the new local path, or null to reset

    • matchPath

      public boolean matchPath(String prefix)
      Matches and modifies the request path with the specified path prefix. If a match is found, the prefix is removed from the request path and true is returned. If the prefix ends with a / and the path would match the shorter prefix, a redirect is sent and false is returned.
      Parameters:
      prefix - the path prefix to check
      Returns:
      true if the request path matched the prefix, or false otherwise

    • matchPath

      public boolean matchPath(Pattern prefix)
      Matches and modifies the request path with the specified path prefix regular expression. If a match is found, the matched string is removed from the request path and true is returned. Note that the regex pattern should always start with ^ to anchor at the start of the path.
      Parameters:
      prefix - the path prefix pattern to check
      Returns:
      true if the request path matched, or false otherwise

    • getContentType

      public String getContentType()
      Returns the request content type value. This is normally set to "application/x-www-form-urlencoded" for POST data, but other MIME types may occasionally be used.
      Returns:
      the HTTP content type header value

    • getRemoteAddr

      public String getRemoteAddr()
      Returns the IP address of the request sender.
      Returns:
      the IP address of the request sender

    • getAuth

      public Dict getAuth()
      Returns parsed "Authorization" request header data. The authentication scheme is returned in the "scheme" key and the raw authentication data is provided in the "data" key. Additionally, if the data can be parsed, their corresponding key value pairs are also provided.
      Returns:
      the parsed authentication data, or null if not present

    • getHeader

      public String getHeader(String name)
      Returns an HTTP request header.
      Parameters:
      name - the request header name
      Returns:
      the header value, or null if not set

    • getParameter

      public String getParameter(String name)
      Returns the value of a request parameter.
      Parameters:
      name - the request parameter name
      Returns:
      the request parameter value, or null if no such parameter was found

    • getParameter

      public String getParameter(String name, String defVal)
      Returns the value of a request parameter. If the specified parameter does not exits, a default value will be returned.
      Parameters:
      name - the request parameter name
      defVal - the default parameter value
      Returns:
      the request parameter value, or the default value if no such parameter was found

    • getNextFile

      public org.apache.commons.fileupload.FileItemStream getNextFile() throws IOException
      Returns the next available file item stream in the request. If the request is not a file upload request or no further files are available, null will be returned. Note that file upload requests must be handled differently from ordinary requests, since the normal request parameter access is limited to query parameters. Also, the file items returned from this method are controlled to be actual files, and any other request parameters are simply ignored.

      The recommended way to implement file uploads is by sending them as the sole request parameter in a form and storing the file content for later processing. Preferably the form posting is also performed from an IFRAME in order to process in the background.

      Returns:
      the next file item stream, or null if none is available
      Throws:
      IOException - if the file upload

    • getAttribute

      public Object getAttribute(String name)
      Returns a named request attribute value.
      Parameters:
      name - the attribute name
      Returns:
      the attribute value, or null if not set

    • setAttribute

      public void setAttribute(String name, Object value)
      Sets a request attribute value.
      Parameters:
      name - the attribute name
      value - the attribute value

    • getSessionId

      public String getSessionId()
      Returns the request session id (as sent in an HTTP cookie).
      Returns:
      the session id from the cookie, or null if no session cookie was present

    • getHttpRequest

      public javax.servlet.http.HttpServletRequest getHttpRequest()
      Returns the HTTP request object for direct access to the raw request data.
      Returns:
      the HTTP request object

    • getHttpResponse

      public javax.servlet.http.HttpServletResponse getHttpResponse()
      Returns the HTTP response object for direct access to the raw response data.
      Returns:
      the HTTP response object

    • getProcessTime

      public long getProcessTime()
      Returns the time in milliseconds since this request wrapper was created. The number returned will always be one (1) or greater.
      Returns:
      the approximate request processing time

    • getInputString

      public String getInputString()
      Returns the request input stream data as a string. Once this method has been called, the request input stream cannot be read again. Also, this method should only be called if the request data is required to be in text format.
      Returns:
      the request input stream data as a string

    • getInputStream

      public InputStream getInputStream() throws IOException
      Returns the request input stream. Once the input stream has been read once, it cannot be read again. Also, this method should only be called if the request data is indeed in a binary format.
      Returns:
      the request input stream
      Throws:
      IOException - if the input stream couldn't be read

    • sendClear

      public void sendClear()
      Clears any previously sent but non-committed response. Note that this method DOES NOT clear any response headers or cookies already set.

    • sendAuthenticationRequest

      public void sendAuthenticationRequest(String realm, String nonce)
      Sends a digest authentication request as the request response. Any previous response will be cleared.
      Parameters:
      realm - the security realm to use
      nonce - the generated one-time code to use
      See Also:

    • sendText

      public void sendText(String mimeType, String text)
      Sends the specified text data as the request response. Any previous response will be cleared.
      Parameters:
      mimeType - the data MIME type
      text - the text data to send
      See Also:

    • sendText

      public void sendText(int code, String mimeType, String text)
      Sends the specified text data as the request response. Any previous response will be cleared.
      Parameters:
      code - the HTTP response code to send
      mimeType - the optional MIME type, null for default
      text - the text data to send
      See Also:

    • sendBinary

      public void sendBinary(Binary data)
      Sends the contents of a file as the request response. The file name extension will be used for determining the MIME type for the file contents. Any previous response will be cleared.
      Parameters:
      data - the file containing the response
      See Also:

    • sendRedirect

      public void sendRedirect(String location)
      Redirects this request by sending a temporary redirection URL to the browser. The location specified may be either an absolute or a relative URL. This method will set a request response. Any previous response will be cleared.
      Parameters:
      location - the destination location
      See Also:

    • sendError

      public void sendError(int code)
      Sends the specified error code. This method does not provide any visible error page to the user. Any previous response will be cleared.
      Parameters:
      code - the HTTP response code to send
      See Also:

    • sendError

      public void sendError(int code, String mimeType, String text)
      Sends the specified error code and data as the request response. Any previous response will be cleared.
      Parameters:
      code - the HTTP response code to send
      mimeType - the optional MIME type, null for default
      text - the text data to send (error page content)
      See Also:

    • setResponseHeader

      public void setResponseHeader(String name, String value)
      Sets an HTTP response header value. This method should only be called once a response has been set but before the call to commit(). Normally, this method should be avoided, as the headers set aren't removed unless explicitly overwritten.
      Parameters:
      name - the HTTP header name
      value - the HTTP header value

    • setResponseHeadersOnly

      public void setResponseHeadersOnly(boolean value)
      Sets or clears the response headers only flag. If set, only the HTTP response headers will be sent. No actual data will be transferred.
      Parameters:
      value - the new flag value

    • setSessionId

      public void setSessionId(String sessionId, String path)
      Sets the session id cookie in the HTTP response. This method can also be used to clear the session cookie in the web browser (by setting a null value), or to renew the cookie (by re-setting the same value).
      Parameters:
      sessionId - the session identifier
      path - the cookie path, or null for default

    • dispose

      public void dispose()
      Disposes of all resources used by this request object. This method shouldn't be called until a response has been sent to the client.

    • commit

      public void commit() throws IOException, javax.servlet.ServletException
      Sends the request response to the underlying HTTP response object. This method shouldn't be called more than once per request, and should not be called in case no response has been stored in the request.
      Throws:
      IOException - if an IO error occurred while attempting to commit the response
      javax.servlet.ServletException - if a configuration error was encountered while sending the response