Package com.nimbusds.oauth2.sdk.http

Class HTTPRequest

java.lang.Object
com.nimbusds.oauth2.sdk.http.HTTPRequest
@ThreadSafe public class HTTPRequest extends Object
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 an URL and not null.

  • Method Details

    • getMethod

      public HTTPRequest.Method getMethod()
      Gets the request method.
      Returns:
      The request method.

    • getURL

      public URL getURL()
      Gets the request URL.
      Returns:
      The request URL.

    • getURI

      public URI getURI()
      Gets the request URL as URI.
      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.

    • getQuery

      public String getQuery()
      Gets the raw (undecoded) 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

      public void setQuery(String query)
      Sets the raw (undecoded) 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.

    • getQueryParameters

      public Map<String,List<String>> getQueryParameters()
      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

      public net.minidev.json.JSONObject getQueryAsJSONObject() throws ParseException
      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

      public String getFragment()
      Gets the raw (undecoded) request fragment.
      Returns:
      The request fragment, null if not specified.

    • setFragment

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

    • getConnectTimeout

      public int getConnectTimeout()
      Gets the HTTP connect timeout.
      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()
      Gets the HTTP response read timeout.
      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 - Whether or not to follow HTTP redirects.

    • 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 request URL and retrieves the resulting HTTP response.
      Returns:
      The resulting HTTP response.
      Throws:
      IOException - If the HTTP request couldn't be made, due to a network or other 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.

    • 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()
      Returns the HTTP headers.
      Returns:
      The HTTP headers.

    • 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.