com.ibm.wsspi.rest.handler

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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method and Description
      java.lang.String getCompleteURL()
      Returns the request URL, exactly as the request would have been made it.
      java.lang.String getContentType()
      Gets the content type of the request sent to the server.
      java.lang.String getContextPath()
      Returns the context path component of the request URL.
      java.lang.String getHeader(java.lang.String key)
      This method gives access to incoming REST headers.
      java.io.Reader getInput()
      This method gives access to the incoming REST body, if any.
      java.io.InputStream getInputStream()
      This method gives access to the InputStream.
      java.util.Locale getLocale()
      Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.
      java.util.Enumeration<java.util.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.
      java.lang.String getMethod()
      Fetches the HTTP method (ie: GET, POST,DELETE, OPTIONS, PUT) corresponding to this REST request.
      java.lang.String getParameter(java.lang.String name)
      Fetches the value of a parameter.
      java.util.Map<java.lang.String,java.lang.String[]> getParameterMap()
      Fetches a map that contains all the requested parameters.
      java.lang.String[] getParameterValues(java.lang.String name)
      Fetches the values of a parameter.
      java.io.InputStream getPart(java.lang.String partName)
      To be used in conjunction with isMultiPartRequest, which should always be called before this method.
      java.lang.String getPath()
      Returns the path component of the request URL relative to the IBM API context root.
      java.lang.String getPathVariable(java.lang.String variable)
      Returns the actual value of a path variable in the incoming request.
      java.lang.String getQueryString()
      Returns the query string of the request URL.
      java.lang.String getRemoteAddr()
      Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.
      java.lang.String getRemoteHost()
      Returns the fully qualified name of the client or the last proxy that sent the request.
      int getRemotePort()
      Returns the Internet Protocol (IP) source port of the client or last proxy that sent the request.
      java.lang.String getSessionId() 
      java.lang.String getURI()
      Returns the URI component of the request URL.
      java.lang.String getURL()
      Returns the URL component of the request URL.
      java.security.Principal getUserPrincipal()
      Returns a java.security.Principal object containing the name of the current authenticated user.
      boolean isMultiPartRequest()
      Returns true if this is a multipart form request.
      boolean isUserInRole(java.lang.String role)
      Returns a boolean indicating whether the authenticated user is included in the specified logical "role".
    • Method Detail

      • getInput

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

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

        java.lang.String getHeader(java.lang.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

        java.lang.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

        java.lang.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

        java.lang.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

        java.lang.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

        java.lang.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

        java.lang.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

        java.lang.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

        java.lang.String getParameter(java.lang.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

        java.lang.String[] getParameterValues(java.lang.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

        java.util.Map<java.lang.String,java.lang.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

        java.security.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(java.lang.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

        java.lang.String getPathVariable(java.lang.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

        java.util.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

        java.util.Enumeration<java.util.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

        java.lang.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

        java.lang.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

        java.io.InputStream getPart(java.lang.String partName)
                             throws java.io.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:
        java.io.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

        java.lang.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

        java.lang.String getSessionId()