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

Supported timeouts:

• On HTTP connect
• On HTTP response read

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.
HTTPRequest(javax.servlet.http.HttpServletRequest sr) Creates a new HTTP request from the specified HTTP servlet 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.
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.
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.
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.

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.

HTTPRequest

public HTTPRequest(javax.servlet.http.HttpServletRequest sr)
            throws java.io.IOException

Creates a new HTTP request from the specified HTTP servlet request.

Parameters:

sr - The servlet request. Must not be null.

Throws:

java.lang.IllegalArgumentException - The the servlet request method is not GET, POST, PUT or DELETE or the content type header value couldn't be parsed.

java.io.IOException - For a POST or PUT body that couldn't be read due to an I/O exception.

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.

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.

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.

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.

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.