Package com.nimbusds.oauth2.sdk.http

Class HTTPRequest

    • 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 a URL and not null.

    • Method Detail

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

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

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

      • setFragment

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

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

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

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

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