Package com.nimbusds.oauth2.sdk.http

Class HTTPRequest

java.lang.Object
com.nimbusds.oauth2.sdk.http.HTTPRequest
All Implemented Interfaces:
ReadOnlyHTTPMessage, ReadOnlyHTTPRequest
@ThreadSafe public class HTTPRequest extends Object implements ReadOnlyHTTPRequest
HTTP request with support for the parameters required to construct an OAuth 2.0 request message.

Supported HTTP methods:

Supported request headers:

  • Content-Type
  • Authorization
  • Accept
  • Etc.

Supported timeouts:

  • On HTTP connect
  • On HTTP response read

HTTP 3xx redirection: follow (default) / don't follow

  • Constructor Details

    • HTTPRequest

      public HTTPRequest(HTTPRequest.Method method, URL url)
      Creates a new minimally specified HTTP request.
      Parameters:
      method - The HTTP request method. Must not be null.
      url - The HTTP request URL. Must not be null.

    • HTTPRequest

      public HTTPRequest(HTTPRequest.Method method, URI uri)
      Creates a new minimally specified HTTP request.
      Parameters:
      method - The HTTP request method. Must not be null.
      uri - The HTTP request URI. Must be a URL and not null.

  • Method Details

    • getMethod

      public HTTPRequest.Method getMethod()
      Gets the request method.
      Specified by:
      getMethod in interface ReadOnlyHTTPRequest
      Returns:
      The request method.

    • getURL

      public URL getURL()
      Gets the request URL.
      Specified by:
      getURL in interface ReadOnlyHTTPRequest
      Returns:
      The request URL.

    • getURI

      public URI getURI()
      Gets the request URL as URI.
      Specified by:
      getURI in interface ReadOnlyHTTPRequest
      Returns:
      The request URL as URI.

    • ensureMethod

      public void ensureMethod(HTTPRequest.Method expectedMethod) throws ParseException
      Ensures this HTTP request has the specified method.
      Parameters:
      expectedMethod - The expected method. Must not be null.
      Throws:
      ParseException - If the method doesn't match the expected.

    • getAuthorization

      public String getAuthorization()
      Gets the Authorization header value.
      Returns:
      The Authorization header value, null if not specified.

    • setAuthorization

      public void setAuthorization(String authz)
      Sets the Authorization header value.
      Parameters:
      authz - The Authorization header value, null if not specified.

    • getDPoP

      public com.nimbusds.jwt.SignedJWT getDPoP()
      Gets the DPoP header value.
      Returns:
      The DPoP header value, null if not specified or parsing failed.

    • getPoPWithException

      public com.nimbusds.jwt.SignedJWT getPoPWithException() throws ParseException
      Gets the DPoP header value.
      Returns:
      The DPoP header value, null if not specified.
      Throws:
      ParseException - If JWT parsing failed.

    • setDPoP

      public void setDPoP(com.nimbusds.jwt.SignedJWT dPoPJWT)
      Sets the DPoP header value.
      Parameters:
      dPoPJWT - The DPoP header value, null if not specified.

    • getAccept

      public String getAccept()
      Gets the Accept header value.
      Returns:
      The Accept header value, null if not specified.

    • setAccept

      public void setAccept(String accept)
      Sets the Accept header value.
      Parameters:
      accept - The Accept header value, null if not specified.

    • appendQueryParameters

      public void appendQueryParameters(Map<String,List<String>> queryParams)
      Appends the specified query parameters to the current HTTP request URL query.

      If the current URL has a query string the new query is appended with `&` in front.

      Parameters:
      queryParams - The query parameters to append, empty or null if nothing to append.
      Throws:
      IllegalArgumentException - If the URL composition failed.

    • appendQueryString

      public void appendQueryString(String queryString)
      Appends the specified raw (encoded) query string to the current HTTP request URL query.

      If the current URL has a query string the new query is appended with `&` in front.

      The '?' character preceding the query string must not be included.

      Example query string to append: 

       client_id=123&logout_hint=eepaeph8siot&state=shah2key
      Parameters:
      queryString - The query string to append, blank or null if nothing to append.
      Throws:
      IllegalArgumentException - If the URL composition failed.

    • getQuery

      @Deprecated public String getQuery()
      Deprecated.
      Use getURL().
      Gets the raw (encoded) query string if the request is HTTP GET or the entity body if the request is HTTP POST.

      Note that the '?' character preceding the query string in GET requests is not included in the returned string.

      Example query string (line breaks for clarity): 

       response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
      Returns:
      For HTTP GET requests the URL query string, for HTTP POST requests the body. null if not specified.

    • setQuery

      @Deprecated public void setQuery(String query)
      Deprecated.
      Use appendQueryString(String).
      Sets the raw (encoded) query string if the request is HTTP GET or the entity body if the request is HTTP POST.

      Note that the '?' character preceding the query string in GET requests must not be included.

      Example query string (line breaks for clarity): 

       response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
      Parameters:
      query - For HTTP GET requests the URL query string, for HTTP POST requests the body. null if not specified.

    • getQueryStringParameters

      public Map<String,List<String>> getQueryStringParameters()
      Gets the query string as a parameter map. The parameters are decoded according to application/x-www-form-urlencoded.
      Returns:
      The query string parameters to, decoded. If none the map will be empty.

    • getQueryParameters

      @Deprecated public Map<String,List<String>> getQueryParameters()
      Deprecated.
      Use getQueryStringParameters().
      Gets the request query as a parameter map. The parameters are decoded according to application/x-www-form-urlencoded.
      Returns:
      The request query parameters, decoded. If none the map will be empty.

    • getQueryAsJSONObject

      @Deprecated public net.minidev.json.JSONObject getQueryAsJSONObject() throws ParseException
      Deprecated.
      Use getBodyAsJSONObject().
      Gets the request query or entity body as a JSON Object.
      Returns:
      The request query or entity body as a JSON object.
      Throws:
      ParseException - If the Content-Type header isn't application/json, the request query or entity body is null, empty or couldn't be parsed to a valid JSON object.

    • getFragment

      @Deprecated public String getFragment()
      Deprecated.
      Use getURL().
      Gets the raw (encoded) fragment of the URL.
      Returns:
      The fragment, null if not specified.

    • setFragment

      public void setFragment(String fragment)
      Sets the raw (encoded) fragment of the URL.
      Parameters:
      fragment - The fragment, null if not specified.

    • getConnectTimeout

      public int getConnectTimeout()
      Description copied from interface: ReadOnlyHTTPRequest
      Gets the HTTP connect timeout.
      Specified by:
      getConnectTimeout in interface ReadOnlyHTTPRequest
      Returns:
      The HTTP connect timeout, in milliseconds. Zero implies no timeout.

    • setConnectTimeout

      public void setConnectTimeout(int connectTimeout)
      Sets the HTTP connect timeout.
      Parameters:
      connectTimeout - The HTTP connect timeout, in milliseconds. Zero implies no timeout. Must not be negative.

    • getReadTimeout

      public int getReadTimeout()
      Description copied from interface: ReadOnlyHTTPRequest
      Gets the HTTP response read timeout.
      Specified by:
      getReadTimeout in interface ReadOnlyHTTPRequest
      Returns:
      The HTTP response read timeout, in milliseconds. Zero implies no timeout.

    • setReadTimeout

      public void setReadTimeout(int readTimeout)
      Sets the HTTP response read timeout.
      Parameters:
      readTimeout - The HTTP response read timeout, in milliseconds. Zero implies no timeout. Must not be negative.

    • getProxy

      public Proxy getProxy()
      Returns the proxy to use for this HTTP request.
      Returns:
      The connection specific proxy for this request, null for the default proxy strategy.

    • setProxy

      public void setProxy(Proxy proxy)
      Tunnels this HTTP request via the specified Proxy by directly configuring the proxy on the URLConnection. The proxy is only used for this instance and bypasses any other proxy settings (such as set via System properties or ProxySelector). Supplying null (the default) reverts to the default proxy strategy of URLConnection. If the goal is to avoid using a proxy at all supply Proxy.NO_PROXY.
      Parameters:
      proxy - The connection specific proxy to use, null to use the default proxy strategy.
      See Also:

    • getFollowRedirects

      public boolean getFollowRedirects()
      Gets the boolean setting whether HTTP redirects (requests with response code 3xx) should be automatically followed.
      Returns:
      true if HTTP redirects are automatically followed, else false.

    • setFollowRedirects

      public void setFollowRedirects(boolean follow)
      Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed.
      Parameters:
      follow - true if HTTP redirects are automatically followed, else false.

    • getClientX509Certificate

      public X509Certificate getClientX509Certificate()
      Gets the received validated client X.509 certificate for a received HTTPS request.
      Returns:
      The client X.509 certificate, null if not specified.

    • setClientX509Certificate

      public void setClientX509Certificate(X509Certificate clientX509Certificate)
      Sets the received validated client X.509 certificate for a received HTTPS request.
      Parameters:
      clientX509Certificate - The client X.509 certificate, null if not specified.

    • getClientX509CertificateSubjectDN

      public String getClientX509CertificateSubjectDN()
      Gets the subject DN of a received validated client X.509 certificate for a received HTTPS request.
      Returns:
      The subject DN, null if not specified.

    • setClientX509CertificateSubjectDN

      public void setClientX509CertificateSubjectDN(String subjectDN)
      Sets the subject DN of a received validated client X.509 certificate for a received HTTPS request.
      Parameters:
      subjectDN - The subject DN, null if not specified.

    • getClientX509CertificateRootDN

      public String getClientX509CertificateRootDN()
      Gets the root issuer DN of a received validated client X.509 certificate for a received HTTPS request.
      Returns:
      The root DN, null if not specified.

    • setClientX509CertificateRootDN

      public void setClientX509CertificateRootDN(String rootDN)
      Sets the root issuer DN of a received validated client X.509 certificate for a received HTTPS request.
      Parameters:
      rootDN - The root DN, null if not specified.

    • getHostnameVerifier

      public HostnameVerifier getHostnameVerifier()
      Gets the hostname verifier for outgoing HTTPS requests.
      Returns:
      The hostname verifier, null implies use of the default one.

    • setHostnameVerifier

      public void setHostnameVerifier(HostnameVerifier hostnameVerifier)
      Sets the hostname verifier for outgoing HTTPS requests.
      Parameters:
      hostnameVerifier - The hostname verifier, null implies use of the default one.

    • getSSLSocketFactory

      public SSLSocketFactory getSSLSocketFactory()
      Gets the SSL factory for outgoing HTTPS requests.
      Returns:
      The SSL factory, null implies of the default one.

    • setSSLSocketFactory

      public void setSSLSocketFactory(SSLSocketFactory sslSocketFactory)
      Sets the SSL factory for outgoing HTTPS requests. Use the TLS utility to set a custom trust store for server and CA certificates and / or a custom key store for client private keys and certificates, also to select a specific TLS protocol version.
      Parameters:
      sslSocketFactory - The SSL factory, null implies use of the default one.

    • getDefaultHostnameVerifier

      public static HostnameVerifier getDefaultHostnameVerifier()
      Returns the default hostname verifier for all outgoing HTTPS requests.
      Returns:
      The hostname verifier.

    • setDefaultHostnameVerifier

      public static void setDefaultHostnameVerifier(HostnameVerifier defaultHostnameVerifier)
      Sets the default hostname verifier for all outgoing HTTPS requests. Can be overridden on a individual request basis.
      Parameters:
      defaultHostnameVerifier - The hostname verifier. Must not be null.

    • getDefaultSSLSocketFactory

      public static SSLSocketFactory getDefaultSSLSocketFactory()
      Returns the default SSL socket factory for all outgoing HTTPS requests.
      Returns:
      The SSL socket factory.

    • setDefaultSSLSocketFactory

      public static void setDefaultSSLSocketFactory(SSLSocketFactory sslSocketFactory)
      Sets the default SSL socket factory for all outgoing HTTPS requests. Can be overridden on a individual request basis. Use the TLS utility to set a custom trust store for server and CA certificates and / or a custom key store for client private keys and certificates, also to select a specific TLS protocol version.
      Parameters:
      sslSocketFactory - The SSL socket factory. Must not be null.

    • toHttpURLConnection

      @Deprecated public HttpURLConnection toHttpURLConnection(HostnameVerifier hostnameVerifier, SSLSocketFactory sslSocketFactory) throws IOException
      Deprecated.
      Returns an established HTTP URL connection for this HTTP request. Deprecated as of v5.31, use toHttpURLConnection() with setHostnameVerifier(javax.net.ssl.HostnameVerifier) and setSSLSocketFactory(javax.net.ssl.SSLSocketFactory) instead.
      Parameters:
      hostnameVerifier - The hostname verifier for outgoing HTTPS requests, null implies use of the default one.
      sslSocketFactory - The SSL socket factory for HTTPS requests, null implies use of the default one.
      Returns:
      The HTTP URL connection, with the request sent and ready to read the response.
      Throws:
      IOException - If the HTTP request couldn't be made, due to a network or other error.

    • toHttpURLConnection

      public HttpURLConnection toHttpURLConnection() throws IOException
      Returns an established HTTP URL connection for this HTTP request.
      Returns:
      The HTTP URL connection, with the request sent and ready to read the response.
      Throws:
      IOException - If the HTTP request couldn't be made, due to a network or other error.

    • send

      @Deprecated public HTTPResponse send(HostnameVerifier hostnameVerifier, SSLSocketFactory sslSocketFactory) throws IOException
      Deprecated.
      Sends this HTTP request to the request URL and retrieves the resulting HTTP response. Deprecated as of v5.31, use toHttpURLConnection() with setHostnameVerifier(javax.net.ssl.HostnameVerifier) and setSSLSocketFactory(javax.net.ssl.SSLSocketFactory) instead.
      Parameters:
      hostnameVerifier - The hostname verifier for outgoing HTTPS requests, null implies use of the default one.
      sslSocketFactory - The SSL socket factory for HTTPS requests, null implies use of the default one.
      Returns:
      The resulting HTTP response.
      Throws:
      IOException - If the HTTP request couldn't be made, due to a network or other error.

    • send

      public HTTPResponse send() throws IOException
      Sends this HTTP request to the URL and retrieves the resulting HTTP response.
      Returns:
      The resulting HTTP response.
      Throws:
      IOException - If the HTTP request couldn't be sent, due to a network or another error.

    • send

      public HTTPResponse send(HTTPRequestSender httpRequestSender) throws IOException
      Sends this HTTP request to the URL and retrieves the resulting HTTP response.
      Parameters:
      httpRequestSender - The HTTP request sender. Must not be null.
      Returns:
      The resulting HTTP response.
      Throws:
      IOException - If the HTTP request couldn't be sent, due to a network or another error.

    • getEntityContentType

      public com.nimbusds.common.contenttype.ContentType getEntityContentType()
      Gets the Content-Type header value.
      Returns:
      The Content-Type header value, null if not specified or parsing failed.

    • setEntityContentType

      public void setEntityContentType(com.nimbusds.common.contenttype.ContentType ct)
      Sets the Content-Type header value.
      Parameters:
      ct - The Content-Type header value, null if not specified.

    • setContentType

      public void setContentType(String ct) throws ParseException
      Sets the Content-Type header value.
      Parameters:
      ct - The Content-Type header value, null if not specified.
      Throws:
      ParseException - If the header value couldn't be parsed to a valid content type.

    • ensureEntityContentType

      public void ensureEntityContentType() throws ParseException
      Ensures this HTTP message has a Content-Type header value.
      Throws:
      ParseException - If the Content-Type header is missing.

    • ensureEntityContentType

      public void ensureEntityContentType(com.nimbusds.common.contenttype.ContentType contentType) throws ParseException
      Ensures this HTTP message has the specified Content-Type header value. This method compares only the primary type and subtype; any content type parameters, such as charset, are ignored.
      Parameters:
      contentType - The expected content type. Must not be null.
      Throws:
      ParseException - If the Content-Type header is missing or its primary and subtype don't match.

    • ensureEntityContentType

      public void ensureEntityContentType(com.nimbusds.common.contenttype.ContentType contentType, String subTypeSuffix) throws ParseException
      Ensures this HTTP message has the specified Content-Type header value. This method compares only the primary type and subtype; any content type parameters, such as charset, are ignored.
      Parameters:
      contentType - The expected content type. Must not be null.
      subTypeSuffix - Acceptable sub type suffix if the expected content type doesn't match, null if not specified.
      Throws:
      ParseException - If the Content-Type header is missing or its primary and subtype don't match.

    • getHeaderValue

      public String getHeaderValue(String name)
      Gets an HTTP header's value.
      Parameters:
      name - The header name. Must not be null.
      Returns:
      The first header value, null if not specified.

    • getHeaderValues

      public List<String> getHeaderValues(String name)
      Gets an HTTP header's value(s).
      Parameters:
      name - The header name. Must not be null.
      Returns:
      The header value(s), null if not specified.

    • setHeader

      public void setHeader(String name, String... values)
      Sets an HTTP header.
      Parameters:
      name - The header name. Must not be null.
      values - The header value(s). If null and a header with the same name is specified, it will be deleted.

    • getHeaderMap

      public Map<String,List<String>> getHeaderMap()
      Description copied from interface: ReadOnlyHTTPMessage
      Returns the HTTP headers.
      Specified by:
      getHeaderMap in interface ReadOnlyHTTPMessage
      Returns:
      The HTTP headers.

    • getBody

      public String getBody()
      Description copied from interface: ReadOnlyHTTPMessage
      Get the HTTP message body.
      Specified by:
      getBody in interface ReadOnlyHTTPMessage
      Returns:
      The HTTP message body, null if not specified.

    • setBody

      public void setBody(String body)
      Sets the HTTP message body.
      Parameters:
      body - The HTTP message body, null if not specified.

    • getBodyAsFormParameters

      public Map<String,List<String>> getBodyAsFormParameters() throws ParseException
      Gets the response body as a form parameters map.
      Returns:
      The form parameters as a map.
      Throws:
      ParseException - If the Content-Type header isn't application/x-www-form-urlencoded or the response couldn't be parsed to a valid form.

    • getBodyAsJSONObject

      public net.minidev.json.JSONObject getBodyAsJSONObject() throws ParseException
      Gets the response body as a JSON object.
      Returns:
      The response body as a JSON object.
      Throws:
      ParseException - If the Content-Type header isn't application/json or has no +json suffix, the response body is null, empty or couldn't be parsed to a valid JSON object.

    • getBodyAsJSONArray

      public net.minidev.json.JSONArray getBodyAsJSONArray() throws ParseException
      Gets the response content as a JSON array.
      Returns:
      The response content as a JSON array.
      Throws:
      ParseException - If the Content-Type header isn't application/json or has no +json suffix, the response content is null, empty or couldn't be parsed to a valid JSON array.

    • getBodyAsJWT

      public com.nimbusds.jwt.JWT getBodyAsJWT() throws ParseException
      Gets the response body as a JSON Web Token (JWT).
      Returns:
      The response body as a JSON Web Token (JWT).
      Throws:
      ParseException - If the Content-Type header isn't application/jwt or has no +jwt suffix, the response content is null, empty or couldn't be parsed to a valid JSON Web Token (JWT).

    • getClientIPAddress

      public String getClientIPAddress()
      Gets the client IP address.
      Returns:
      The client IP address, null if not specified.

    • setClientIPAddress

      public void setClientIPAddress(String clientIPAddress)
      Sets the client IP address.
      Parameters:
      clientIPAddress - The client IP address, null if not specified.