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 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 returnshttps://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 returnshttps://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 returnsparam1=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 usegetParameterMap()
- 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()
-
-