com.nimbusds.oauth2.sdk.http

Class HTTPRequest

java.lang.Object

com.nimbusds.oauth2.sdk.http.HTTPRequest

@ThreadSafe
public class HTTPRequest
extends java.lang.Object

HTTP request with support for the parameters required to construct an OAuth 2.0 request message.

Supported HTTP methods:

• HTTP GET
• HTTP POST
• HTTP PUT
• HTTP DELETE

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HTTPRequest.Method Enumeration of the HTTP methods used in OAuth 2.0 requests.

Constructor Summary

Constructors

Constructor and Description
HTTPRequest(HTTPRequest.Method method, java.net.URL url) Creates a new minimally specified HTTP request.

Method Summary

Methods

Modifier and Type	Method and Description
void	ensureContentType() Ensures this HTTP message has a Content-Type header value.
void	ensureContentType(javax.mail.internet.ContentType contentType) Ensures this HTTP message has the specified Content-Type header value.
void	ensureMethod(HTTPRequest.Method expectedMethod) Ensures this HTTP request has the specified method.
java.lang.String	getAccept() Gets the Accept header value.
java.lang.String	getAuthorization() Gets the Authorization header value.
int	getConnectTimeout() Gets the HTTP connect timeout.
javax.mail.internet.ContentType	getContentType() Gets the Content-Type header value.
static javax.net.ssl.HostnameVerifier	getDefaultHostnameVerifier() Returns the default hostname verifier for all HTTPS requests.
static javax.net.ssl.SSLSocketFactory	getDefaultSSLSocketFactory() Returns the default SSL socket factory for all HTTPS requests.
boolean	getFollowRedirects() Gets the boolean setting whether HTTP redirects (requests with response code 3xx) should be automatically followed.
java.lang.String	getFragment() Gets the raw (undecoded) request fragment.
java.lang.String	getHeader(java.lang.String name) Gets a HTTP header value.
java.util.Map<java.lang.String,java.lang.String>	getHeaders() Returns the HTTP headers.
HTTPRequest.Method	getMethod() Gets the request method.
java.lang.String	getQuery() Gets the raw (undecoded) query string if the request is HTTP GET or the entity body if the request is HTTP POST.
net.minidev.json.JSONObject	getQueryAsJSONObject() Gets the request query or entity body as a JSON Object.
java.util.Map<java.lang.String,java.lang.String>	getQueryParameters() Gets the request query as a parameter map.
int	getReadTimeout() Gets the HTTP response read timeout.
java.net.URL	getURL() Gets the request URL.
HTTPResponse	send() Sends this HTTP request to the request URL and retrieves the resulting HTTP response.
HTTPResponse	send(javax.net.ssl.HostnameVerifier hostnameVerifier, javax.net.ssl.SSLSocketFactory sslSocketFactory) Sends this HTTP request to the request URL and retrieves the resulting HTTP response.
void	setAccept(java.lang.String accept) Sets the Accept header value.
void	setAuthorization(java.lang.String authz) Sets the Authorization header value.
void	setConnectTimeout(int connectTimeout) Sets the HTTP connect timeout.
void	setContentType(javax.mail.internet.ContentType ct) Sets the Content-Type header value.
void	setContentType(java.lang.String ct) Sets the Content-Type header value.
static void	setDefaultHostnameVerifier(javax.net.ssl.HostnameVerifier defaultHostnameVerifier) Sets the default hostname verifier for all HTTPS requests.
static void	setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory sslSocketFactory) Sets the default SSL socket factory for all HTTPS requests.
void	setFollowRedirects(boolean follow) Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed.
void	setFragment(java.lang.String fragment) Sets the raw (undecoded) request fragment.
void	setHeader(java.lang.String name, java.lang.String value) Sets a HTTP header value.
void	setQuery(java.lang.String query) Sets the raw (undecoded) query string if the request is HTTP GET or the entity body if the request is HTTP POST.
void	setReadTimeout(int readTimeout) Sets the HTTP response read timeout.
java.net.HttpURLConnection	toHttpURLConnection() Returns an established HTTP URL connection for this HTTP request.
java.net.HttpURLConnection	toHttpURLConnection(javax.net.ssl.HostnameVerifier hostnameVerifier, javax.net.ssl.SSLSocketFactory sslSocketFactory) Returns an established HTTP URL connection for this HTTP request.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTTPRequest

public HTTPRequest(HTTPRequest.Method method,
           java.net.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.

Method Detail

getMethod

public HTTPRequest.Method getMethod()

Gets the request method.

Returns:

The request method.

getURL

public java.net.URL getURL()

Gets the request URL.

Returns:

The request URL.

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 java.lang.String getAuthorization()

Gets the Authorization header value.

Returns:

The Authorization header value, null if not specified.

setAuthorization

public void setAuthorization(java.lang.String authz)

Sets the Authorization header value.

Parameters:

authz - The Authorization header value, null if not specified.

getAccept

public java.lang.String getAccept()

Gets the Accept header value.

Returns:

The Accept header value, null if not specified.

setAccept

public void setAccept(java.lang.String accept)

Sets the Accept header value.

Parameters:

accept - The Accept header value, null if not specified.

getQuery

public java.lang.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(java.lang.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 java.util.Map<java.lang.String,java.lang.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 java.lang.String getFragment()

Gets the raw (undecoded) request fragment.

Returns:

The request fragment, null if not specified.

setFragment

public void setFragment(java.lang.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 read 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.

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.

getDefaultHostnameVerifier

public static javax.net.ssl.HostnameVerifier getDefaultHostnameVerifier()

Returns the default hostname verifier for all HTTPS requests.

Returns:

The hostname verifier.

setDefaultHostnameVerifier

public static void setDefaultHostnameVerifier(javax.net.ssl.HostnameVerifier defaultHostnameVerifier)

Sets the default hostname verifier for all HTTPS requests. May be overridden on a individual request basis.

Parameters:

defaultHostnameVerifier - The hostname verifier. Must not be null.

getDefaultSSLSocketFactory

public static javax.net.ssl.SSLSocketFactory getDefaultSSLSocketFactory()

Returns the default SSL socket factory for all HTTPS requests.

Returns:

The SSL socket factory.

setDefaultSSLSocketFactory

public static void setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory sslSocketFactory)

Sets the default SSL socket factory for all HTTPS requests. May be overridden on a individual request basis.

Parameters:

sslSocketFactory - The SSL socket factory. Must not be null.

toHttpURLConnection

public java.net.HttpURLConnection toHttpURLConnection()
                                               throws java.io.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:

java.io.IOException - If the HTTP request couldn't be made, due to a network or other error.

toHttpURLConnection

public java.net.HttpURLConnection toHttpURLConnection(javax.net.ssl.HostnameVerifier hostnameVerifier,
                                             javax.net.ssl.SSLSocketFactory sslSocketFactory)
                                               throws java.io.IOException

Returns an established HTTP URL connection for this HTTP request.

Parameters:

hostnameVerifier - The hostname verifier for HTTPS requests. Disregarded for plain HTTP requests. If null the default hostname verifier will apply.

sslSocketFactory - The SSL socket factory for HTTPS requests. Disregarded for plain HTTP requests. If null the default SSL socket factory will apply.

Returns:

The HTTP URL connection, with the request sent and ready to read the response.

Throws:

java.io.IOException - If the HTTP request couldn't be made, due to a network or other error.

send

public HTTPResponse send()
                  throws java.io.IOException

Sends this HTTP request to the request URL and retrieves the resulting HTTP response.

Returns:

The resulting HTTP response.

Throws:

java.io.IOException - If the HTTP request couldn't be made, due to a network or other error.

send

public HTTPResponse send(javax.net.ssl.HostnameVerifier hostnameVerifier,
                javax.net.ssl.SSLSocketFactory sslSocketFactory)
                  throws java.io.IOException

Sends this HTTP request to the request URL and retrieves the resulting HTTP response.

Parameters:

hostnameVerifier - The hostname verifier for HTTPS requests. Disregarded for plain HTTP requests. If null the default hostname verifier will apply.

sslSocketFactory - The SSL socket factory for HTTPS requests. Disregarded for plain HTTP requests. If null the default SSL socket factory will apply.

Returns:

The resulting HTTP response.

Throws:

java.io.IOException - If the HTTP request couldn't be made, due to a network or other error.

getContentType

public javax.mail.internet.ContentType getContentType()

Gets the Content-Type header value.

Returns:

The Content-Type header value, null if not specified.

setContentType

public void setContentType(javax.mail.internet.ContentType ct)

Sets the Content-Type header value.

Parameters:

ct - The Content-Type header value, null if not specified.

setContentType

public void setContentType(java.lang.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.

ensureContentType

public void ensureContentType()
                       throws ParseException

Ensures this HTTP message has a Content-Type header value.

Throws:

ParseException - If the Content-Type header is missing.

ensureContentType

public void ensureContentType(javax.mail.internet.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.

getHeader

public java.lang.String getHeader(java.lang.String name)

Gets a HTTP header value.

Parameters:

name - The header name. Must not be null.

Returns:

The header value, null if not specified.

setHeader

public void setHeader(java.lang.String name,
             java.lang.String value)

Sets a HTTP header value.

Parameters:

name - The header name. Must not be null.

value - The header value. If null and a header with the same name is specified, it will be deleted.

getHeaders

public java.util.Map<java.lang.String,java.lang.String> getHeaders()

Returns the HTTP headers.

Returns:

The HTTP headers.