Package com.nimbusds.oauth2.sdk.http

Class 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 Detail

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

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

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

      • 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:
        URL.openConnection(Proxy)

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

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

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

      • 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

        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

        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.