Interface RESTRequest


public interface RESTRequest

This interface encapsulates the artifacts pertaining to an HTTP request.

Implementations of this interface are not guaranteed to be thread safe, and live only until the corresponding RESTHandler.handleRequest(RESTRequest, RESTResponse) method returns.

  • Method Summary

    Modifier and Type
    Method
    Description
    Returns the request URL, exactly as the request would have been made it.
    Gets the content type of the request sent to the server.
    Returns the context path component of the request URL.
    This method gives access to incoming REST headers.
    This method gives access to the incoming REST body, if any.
    This method gives access to the InputStream.
    Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.
    Returns an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language header.
    Fetches the HTTP method (ie: GET, POST,DELETE, OPTIONS, PUT) corresponding to this REST request.
    Fetches the value of a parameter.
    Fetches a map that contains all the requested parameters.
    Fetches the values of a parameter.
    getPart(String partName)
    To be used in conjunction with isMultiPartRequest, which should always be called before this method.
    Returns the path component of the request URL relative to the IBM API context root.
    Returns the actual value of a path variable in the incoming request.
    Returns the query string of the request URL.
    Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.
    Returns the fully qualified name of the client or the last proxy that sent the request.
    int
    Returns the Internet Protocol (IP) source port of the client or last proxy that sent the request.
     
    Returns the URI component of the request URL.
    Returns the URL component of the request URL.
    Returns a java.security.Principal object containing the name of the current authenticated user.
    boolean
    Returns true if this is a multipart form request.
    boolean
    Returns a boolean indicating whether the authenticated user is included in the specified logical "role".
  • Method Details

    • getInput

      Reader getInput() throws IOException
      This method gives access to the incoming REST body, if any.
      Returns:
      a Reader over the payload.
      Throws:
      IOException - if an I/O exception occurred.
    • getInputStream

      InputStream getInputStream() throws IOException
      This method gives access to the InputStream.
      Returns:
      the InputStream for the payload.
      Throws:
      IOException - if an I/O exception occurred.
    • getHeader

      String getHeader(String key)
      This method gives access to incoming REST headers.
      Parameters:
      key - representing the header.
      Returns:
      a matching value for the key, or null otherwise.
    • getMethod

      String getMethod()
      Fetches the HTTP method (ie: GET, POST,DELETE, OPTIONS, PUT) corresponding to this REST request.
      Returns:
      a java.lang.String representation of the HTTP method.
    • getCompleteURL

      String getCompleteURL()

      Returns the request URL, exactly as the request would have been made it. This includes the protocol, host, port, path and query string (if specified).

      For example: if the requested URL is https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2 then this method returns https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2

      Returns:
      The complete URL used for the request
    • getURL

      String getURL()

      Returns the URL component of the request URL. The query string is not included.

      For example: if the requested URL is https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2 then this method returns https://localhost:9443/ibm/api/myRoot/myPath

      Returns:
      The URL of the request
    • getURI

      String getURI()

      Returns the URI component of the request URL. The query string is not included.

      For example: if the requested URL is https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2 then this method returns /ibm/api/myRoot/myPath.

      Returns:
      The URI of the request
    • getContextPath

      String getContextPath()

      Returns the context path component of the request URL.

      For example: if the requested URL is https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2 then this method returns /ibm/api.

      Returns:
      The context path of the request
    • getPath

      String getPath()

      Returns the path component of the request URL relative to the IBM API context root. The query string is not included.

      For example: if the requested URL is https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2 then this method returns /myRoot/myPath

      Returns:
      The requested path relative to the IBM API context root of the request
    • getQueryString

      String getQueryString()

      Returns the query string of the request URL.

      For example: if the requested URL is https://localhost:9443/ibm/api/myRoot/myPath?param1=value1,param2=value2 then this method returns param1=value1,param2=value2.

      Returns:
      The query parameters of the request
    • getParameter

      String getParameter(String name)
      Fetches the value of a parameter. If the parameter contains multiple values the first one will be returned, but in that case the caller should preferrably use getParameterMap()
      Parameters:
      name - a java.lang.String representing the key of the parameter to be fetched.
      Returns:
      a java.lang.String representation of the parameter value or null if the parameter was not found.
    • getParameterValues

      String[] getParameterValues(String name)
      Fetches the values of a parameter.
      Parameters:
      name - a java.lang.String representing the key of the parameter to be fetched.
      Returns:
      a java.lang.String[] representation of the parameter values or null if the parameter was not found.
    • getParameterMap

      Map<String,String[]> getParameterMap()
      Fetches a map that contains all the requested parameters. The entry value is a java.lang.String array because there could be multiple values for the same parameter.
      Returns:
      a java.util.Map containing all requested parameter keys and their corresponding value(s).
    • getUserPrincipal

      Principal getUserPrincipal()
      Returns a java.security.Principal object containing the name of the current authenticated user. If the user has not been authenticated, the method returns null.
      Returns:
      a java.security.Principal containing the name of the user making this request; null if the user has not been authenticated
    • isUserInRole

      boolean isUserInRole(String role)
      Returns a boolean indicating whether the authenticated user is included in the specified logical "role". If the user has not been authenticated, the method returns false
      Parameters:
      role - a String specifying the name of the role
      Returns:
      a boolean indicating whether the user making this request belongs to a given role; false if the user has not been authenticated
    • getPathVariable

      String getPathVariable(String variable)
      Returns the actual value of a path variable in the incoming request. Path variables are specified within the registered URL of a RESTHandler.

      Example: A RESTHandler could register a root "/myRoot/{city}/schools/{school}", which would match to an incoming request of "/myRoot/Burlington/schools/NotreDame", and thus getPathVariable("city") returns Burlington while getPathVariable("school") returns NotreDame.

      Parameters:
      variable - represents the name of the variable to fetch
      Returns:
      the value in the incoming URL that matched the variable, or null if this variable did not match to the incoming URL.
    • getLocale

      Locale getLocale()
      Returns the preferred Locale that the client will accept content in, based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns the default locale for the server.
      Returns:
      the preferred Locale for the client
    • getLocales

      Enumeration<Locale> getLocales()
      Returns an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns an Enumeration containing one Locale, the default locale for the server.
      Returns:
      an Enumeration of preferred Locale objects for the client
    • getRemoteAddr

      String getRemoteAddr()
      Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.
      Returns:
      a String containing the IP address of the client that sent the request
    • getRemoteHost

      String getRemoteHost()
      Returns the fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP address.
      Returns:
      a String containing the fully qualified name of the client
    • getRemotePort

      int getRemotePort()
      Returns the Internet Protocol (IP) source port of the client or last proxy that sent the request.
      Returns:
      an integer specifying the port number
    • getPart

      InputStream getPart(String partName) throws IOException
      To be used in conjunction with isMultiPartRequest, which should always be called before this method. This method will throw an exception if the request is not a multipart request.
      Parameters:
      partName - multipart form part name
      Returns:
      InputStream of the part if it exists or null otherwise
      Throws:
      IOException
    • isMultiPartRequest

      boolean isMultiPartRequest()
      Returns true if this is a multipart form request. To be used in conjunction with getPart().
      Returns:
      true if this is a multipart request, false otherwise.
    • getContentType

      String getContentType()
      Gets the content type of the request sent to the server.
      Returns:
      contentType a String specifying the MIME type of the content.
    • getSessionId

      String getSessionId()