Package org.bzdev.net

Interface HttpServerRequest

All Known Implementing Classes:
WebMap.RequestInfo

public interface HttpServerRequest
Servlet-compatibility interface for HTTP requests. This interface is used by ServletAdapter for arguments of the methods ServletAdapter.doGet(HttpServerRequest,HttpServerResponse), ServletAdapter.doPost(HttpServerRequest,HttpServerResponse), ServletAdapter.doPut(HttpServerRequest,HttpServerResponse), and ServletAdapter.doDelete(HttpServerRequest,HttpServerResponse). HttpServerRequest is modeled after HttpServletRequest, but with several differences. In particular,
See Also:
  • Method Details

    • getAttribute

      Object getAttribute(String name)
      Get an attribute.
      Parameters:
      name - the attribute name
      Returns:
      the attribute
    • setAttribute

      void setAttribute(String name, Object value)
      Set an attribute.
      Parameters:
      name - the attribute name
      value - the attribute value
    • getContextAttribute

      Object getContextAttribute(String name)
      Get a context attribute. A context is an instance of HttpContext when using EmbeddedWebServer and ServletContext when using a servlet (see the the Jarkarta Servlet API v4.0.3 for a description of this class).
      Parameters:
      name - the attribute name
      Returns:
      the attribute
    • setContextAttribute

      void setContextAttribute(String name, Object value)
      Set a context attribute. A context is an instance of HttpContext when using EmbeddedWebServer and ServletContext when using a servlet (see the the Jarkarta Servlet API v4.0.3 for a description of this class).
      Parameters:
      name - the attribute name
      value - the attribute value
    • getProtocol

      String getProtocol()
      Get the protocol used in the request. For example, HTTP/1.1 for HTTP version 1.1
      Returns:
      the protocol in the form PROTOCOL/MAJOR.MINOR
    • getCookies

      ServerCookie[] getCookies()
      Get the cookies for this request.
      Returns:
      a list of cookies
    • getLocale

      Locale getLocale()
      Get the preferred locale for this request. The locale is chosen based on the Accept-Language header.
      Returns:
      the preferred locale
    • getLocales

      Enumeration<Locale> getLocales()
      Get the locales provided by the Accept-Language header, ordered by preference, highest preference first.
      Returns:
      an enumeration for these locales
    • getHeader

      String getHeader(String type)
      Get the value of the request header for the specified type. If there are more then one header with the same type (or name), the first will be returned
      Parameters:
      type - the type (or name) of the header.
      Returns:
      the value of the header; null if there is no values for this type
    • getIntHeader

      default int getIntHeader(String name) throws IllegalArgumentException
      Get a header's value as an integer.
      Parameters:
      name - the name of the header
      Returns:
      the header's value as an integer
      Throws:
      IllegalArgumentException - a header with the given name does not exist or its value is not an integer
    • getDateHeader

      default long getDateHeader(String name) throws IllegalArgumentException
      Get a header's value as a date.
      Parameters:
      name - the name of the header
      Returns:
      the header's value as an date, represented by a long integer giving the number of milliseconds since January 1, 1970, 00:00:00 GMT
      Throws:
      IllegalArgumentException - a header with the given name does not exist or its value is not a date
    • getHeaderNames

      Enumeration<String> getHeaderNames()
      Get an enumeration of all request-header names.
      Returns:
      an enumeration of the names of the request headers; null if not supported
    • getHeaders

      Enumeration<String> getHeaders(String type)
      Get the values of the request headers for the specified type. The enumeration will contain a single element if there is only a single header with specified type. With multiple headers, each header's value is separate element in the enumeration.

      Note: an enumeration is returned for compatibility with the servlet specification

      Parameters:
      type - the type or name of the header.
      Returns:
      an enumeration containing the values of the header; null if there are no values for this type
    • getMethod

      HttpMethod getMethod()
      Get the request method.
      Returns:
      the method.
    • getContextPath

      default String getContextPath()
      Returns a context path. The default implementation returns an empty string. When used by a Servlet, this method should behave identically to the HttpServletRequest method getContextPath().
      Returns:
      the context path
    • getQueryString

      String getQueryString()
      Return the query string
      Returns:
      the query string
    • getParameterMap

      Map<String,String[]> getParameterMap()
      Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with the request. For HTTP, parameters are contained in a URL's query string or posted form data with content type application/x-www-form-urlencoded.
      Returns:
      an immutable java.util.Map containing parameter names as keys and parameter values as map values.
    • getParameter

      default String getParameter(String name)
      Returns the value of a request parameter as a String, or null if the parameter does not exist. Request parameters are extra information sent with the request. For HTTP requests, parameters are contained in the query string or posted form data with content type application/x-www-form-urlencoded.

      Users should only use this method when sure that the parameter has only one value. If the parameter might have more than one value, use getParameterValues(java.lang.String). When used with a multivalued parameter, the value returned is equal to the first value in the array returned by getParameterValues.

      When used with a servlet, if the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getEncodedInputStream or getDecodedInputStream() can interfere with the execution of this method.

      Parameters:
      name - the name of the parameter
      Returns:
      the value of the parameter; null if there is none
    • getParameterValues

      default String[] getParameterValues(String name)
      Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist. For HTTP POST requests, the content must be form data with content type application/x-www-form-urlencoded.

      When used with a servlet, if the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getEncodedInputStream or getDecodedInputStream() can interfere with the execution of this method.

      Parameters:
      name - the name of the parameter
      Returns:
      the values of the parameter
    • getParameterNames

      default Enumeration<String> getParameterNames()
      Returns an Enumeration of String objects containing the names of the parameters contained in this request. If the request has no parameters, the method returns an empty Enumeration. For HTTP POST requests, the content must be form data with content type application/x-www-form-urlencoded.

      When used with a servlet, if the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getEncodedInputStream or getDecodedInputStream() can interfere with the execution of this method.

      Returns:
      an enumeration of parameter names
    • getParameterNameSet

      default Set<String> getParameterNameSet()
      Returns a set of String objects containing the names of the parameters contained in this request. If the request has no parameters, the method returns an empty set. This method is provided as a convenience: unlike enumerations, sets can be used in 'for' loops. For HTTP POST requests, the content must be form data with content type application/x-www-form-urlencoded.

      When used with a servlet, if the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getEncodedInputStream or getDecodedInputStream() can interfere with the execution of this method.

      Returns:
      a set of parameter names
    • getUserPrincipal

      Principal getUserPrincipal()
      Get the Principal for the user authenticating this request.
      Returns:
      the Principal; null if this request has not been authenticated o.
    • getRequestedSessionID

      String getRequestedSessionID()
      Get the session ID specified by a client; The default assumes that session IDs have not been implemented.
      Returns:
      the session ID; null if there is none
    • changeSessionID

      String changeSessionID() throws IllegalStateException
      Change the current session's ID.
      Returns:
      the new session ID
      Throws:
      IllegalStateException - a session does not exist
    • setSessionState

      void setSessionState(Object state) throws IllegalStateException
      Set the current session's state.
      Parameters:
      state - the session state
      Throws:
      IllegalStateException - the session does not exist
    • getSessionState

      Object getSessionState()
      Get the current session state.
      Returns:
      the session state; null if one does not exist.
    • getMaxInactiveInterval

      int getMaxInactiveInterval()
      Get the maximum inactive interval for this request's session.
      Returns:
      the maximum inactive interval in seconds; 0 if no timeout; -1 if there is no session
    • setMaxInactiveInterval

      boolean setMaxInactiveInterval(int interval)
      Set the maximum inactive interval for this request's session.
      Parameters:
      interval - the maximum inactive interval in seconds; 0 if no timeout
      Returns:
      true if this method succeeded; false otherwise (i.e., if there is no session)
    • getRequestURI

      String getRequestURI()
      Get the request URI. This is the first line of an HTTP request. It will not include the server or the method. It does not include a query string
      Returns:
      the request URI
    • getRequestURL

      String getRequestURL()
      Get the URL sent by the client. The URL is reconstructed based on server information.
      Returns:
      the URL
    • isRequestedSessionIDValid

      boolean isRequestedSessionIDValid()
      Determines if the requested session ID is valid. The default assumes that session IDs have not been implemented and thus returns false.
      Returns:
      true if the current session ID is valid; false otherwise
    • isSecure

      boolean isSecure()
      Determine if the request was made over a secure channel. Note: the test is usually based on the protocol being used, not how it is configured.
      Returns:
      if the channel is secure; false otherwise
    • isUserInRole

      boolean isUserInRole(String role)
      Determine if a user is in a specified role. If roles have not been implemented, this method returns false.
      Parameters:
      role - the role
      Returns:
      true if the user is in a specified role; false otherwise
    • getContentType

      String getContentType()
      Get the content type.
      Returns:
      the media type for the content of a request
    • getCharacterEncoding

      String getCharacterEncoding()
      Get the content-type's character encoding
      Returns:
      the character encoding; null if not specified or not applicable
    • getContentLength

      int getContentLength()
      Get the content length. The content length (more or less) is the length in bytes of the content including any content encoding. If compression is used, the content length should be considered to be an estimate of the length, perhaps off by some factor. It can be useful in this case for estimating the size of a ByteArrayBuffer or similar Java classes that can grow if needed but start with an initial size.
      Returns:
      the length of the content; -1 if not known.
    • getContentLengthLong

      long getContentLengthLong()
      Get the content length as a long integer. The content length (more or less) is the length in bytes of the content including any content encoding. If compression is used, the content length should be considered to be an estimate of the length, perhaps off by some factor. It can be useful in this case for estimating the size of a ByteArrayBuffer or similar Java classes that can grow if needed but start with an initial size.
      Returns:
      the length of the content; -1 if not known.
    • getMediaType

      default String getMediaType()
      Get the media type (content type) without any of its parameters.
      Returns:
      the media type without any of its parameters
    • getRemoteAddr

      String getRemoteAddr()
      Return the IP (Internet Protocol) address of the client, last proxy, or router/switch using NAT (Network Address Translation), that sent this request.
      Returns:
      the address
    • getFromHeader

      default String getFromHeader(String key, String parameter)
      Extract parameters from a request header. This method assumes that a header contains a single value and that multiple values would be separated by commas.
      Parameters:
      key - the name of the header (e.g., "content-type")
      parameter - the name of a header parameter (e.g., "charset"); null for the header without its parameters
      Returns:
      the value with quotes and character escapes processed
    • getEncodedInputStream

      InputStream getEncodedInputStream() throws IOException
      Get an input stream that will read data in a request without content decoding. This method is useful when the content will be stored as is - e.g., with compression. One may call getEncodedInputStream() or getDecodedInputStream() but not both. If either is called multiple times, the same input stream will be returned and it may be in a partially-read state. Regardless of which method is used, the stream should be fully read: otherwise the server, or at least the current transaction, may hang.

      When implemented for a servlet, this method should just return the servlet request's getInputStream() method and ensure that getDecodedInputStream() will return null;

      Returns:
      the input stream; null if not available
      Throws:
      IOException - an IO error occurred
    • getDecodedInputStream

      InputStream getDecodedInputStream() throws IOException
      Get an input stream that will read data in a request with content decoding. Any compression (gzip or deflate) will be removed. One may call getEncodedInputStream() or getDecodedInputStream() but not both. If either is called multiple times, the same input stream will be returned and it may be in a partially-read state. Regardless of which method is used, the stream should be fully read: otherwise the server, or at least the current transaction, may hang.

      In a servlet implementation, the following code fragment can be used in implementing this method:

      
           // Need to check that we don't already have a stream.
           // If we don't ...
           String encoding = servletRequest.getHeader("content-encoding");
           InputStream is = servletRequest.getInputStream();
           if (encoding.equalsIgnoreCase("identity")) {
               // nothing to do
           } else if (encoding.equalsIgnoreCase("gzip")) {
               is = new java.util.zip.GZIPInputStream(is);
           } else if (encoding.equalsIgnoreCase("deflate")) {
               is = new java.util.zip.InflaterInputStream(is);
           } else {
             is = null;
           }
           // after adding some bookkeeping to track if we have a stream
           return is;
       
      Returns:
      the input stream; null if not available
      Throws:
      IOException - an IO error occurred