Interface OAuthConsumer

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbstractOAuthConsumer, CommonsHttpOAuthConsumer, DefaultOAuthConsumer

public interface OAuthConsumer
extends Serializable

Exposes a simple interface to sign HTTP requests using a given OAuth token and secret. Refer to OAuthProvider how to retrieve a valid token and token secret.

HTTP messages are signed as follows:

// exchange the arguments with the actual token/secret pair
OAuthConsumer consumer = new DefaultOAuthConsumer("1234", "5678");

URL url = new URL("http://example.com/protected.xml");
HttpURLConnection request = (HttpURLConnection) url.openConnection();

consumer.sign(request);

request.connect();

Method Summary

Modifier and Type	Method	Description
String	getConsumerKey()
String	getConsumerSecret()
HttpParameters	getRequestParameters()	Returns all parameters collected from the HTTP request during message signing (this means the return value may be NULL before a call to sign(HttpRequest)), plus all required OAuth parameters that were added because the request didn't contain them beforehand.
String	getToken()
String	getTokenSecret()
void	setAdditionalParameters(HttpParameters additionalParameters)	Allows you to add parameters (typically OAuth parameters such as oauth_callback or oauth_verifier) which will go directly into the signer, i.e.
void	setMessageSigner(OAuthMessageSigner messageSigner)	Sets the message signer that should be used to generate the OAuth signature.
void	setSendEmptyTokens(boolean enable)	Causes the consumer to always include the oauth_token parameter to be sent, even if blank.
void	setSigningStrategy(SigningStrategy signingStrategy)	Defines which strategy should be used to write a signature to an HTTP request.
void	setTokenWithSecret(String token, String tokenSecret)	Sets the OAuth token and token secret used for message signing.
HttpRequest	sign(Object request)	Signs the given HTTP request by writing an OAuth signature (and other required OAuth parameters) to it.
String	sign(String url)	"Signs" the given URL by appending all OAuth parameters to it which are required for message signing.
HttpRequest	sign(HttpRequest request)	Signs the given HTTP request by writing an OAuth signature (and other required OAuth parameters) to it.

Method Details

setMessageSigner

void setMessageSigner(OAuthMessageSigner messageSigner)

Sets the message signer that should be used to generate the OAuth signature.

Parameters:

messageSigner - the signer

See Also:

• HmacSha1MessageSigner
• PlainTextMessageSigner

setAdditionalParameters

void setAdditionalParameters(HttpParameters additionalParameters)

Allows you to add parameters (typically OAuth parameters such as oauth_callback or oauth_verifier) which will go directly into the signer, i.e. you don't have to put them into the request first. The consumer's SigningStrategy will then take care of writing them to the correct part of the request before it is sent. This is useful if you want to pre-set custom OAuth parameters. Note that these parameters are expected to already be percent encoded -- they will be simply merged as-is. BE CAREFUL WITH THIS METHOD! Your service provider may decide to ignore any non-standard OAuth params when computing the signature.

Parameters:

additionalParameters - the parameters

setSigningStrategy

void setSigningStrategy(SigningStrategy signingStrategy)

Defines which strategy should be used to write a signature to an HTTP request.

Parameters:

signingStrategy - the strategy

See Also:

• AuthorizationHeaderSigningStrategy
• QueryStringSigningStrategy

setSendEmptyTokens

void setSendEmptyTokens(boolean enable)

Causes the consumer to always include the oauth_token parameter to be sent, even if blank. If you're seeing 401s during calls to OAuthProvider.retrieveRequestToken(OAuthConsumer, String, String...), try setting this to true.

Parameters:

enable - true or false

sign

HttpRequest sign(HttpRequest request)
          throws OAuthMessageSignerException,
OAuthExpectationFailedException,
OAuthCommunicationException

Signs the given HTTP request by writing an OAuth signature (and other required OAuth parameters) to it. Where these parameters are written depends on the current SigningStrategy.

Parameters:

request - the request to sign

Returns:

the request object passed as an argument

Throws:

OAuthMessageSignerException

OAuthExpectationFailedException

OAuthCommunicationException

sign

HttpRequest sign(Object request)
          throws OAuthMessageSignerException,
OAuthExpectationFailedException,
OAuthCommunicationException

Signs the given HTTP request by writing an OAuth signature (and other required OAuth parameters) to it. Where these parameters are written depends on the current SigningStrategy.

This method accepts HTTP library specific request objects; the consumer implementation must ensure that only those request types are passed which it supports.

Parameters:

request - the request to sign

Returns:

the request object passed as an argument

Throws:

OAuthMessageSignerException

OAuthExpectationFailedException

OAuthCommunicationException

sign

String sign(String url)
     throws OAuthMessageSignerException,
OAuthExpectationFailedException,
OAuthCommunicationException

"Signs" the given URL by appending all OAuth parameters to it which are required for message signing. The assumed HTTP method is GET. Essentially, this is equivalent to signing an HTTP GET request, but it can be useful if your application requires clickable links to protected resources, i.e. when your application does not have access to the actual request that is being sent.

Parameters:

url - the input URL. May have query parameters.

Returns:

the input URL, with all necessary OAuth parameters attached as a query string. Existing query parameters are preserved.

Throws:

OAuthMessageSignerException

OAuthExpectationFailedException

OAuthCommunicationException

setTokenWithSecret

void setTokenWithSecret(String token,
 String tokenSecret)

Sets the OAuth token and token secret used for message signing.

Parameters:

token - the token

tokenSecret - the token secret

getToken

String getToken()

getTokenSecret

String getTokenSecret()

getConsumerKey

String getConsumerKey()

getConsumerSecret

String getConsumerSecret()

getRequestParameters

HttpParameters getRequestParameters()

Returns all parameters collected from the HTTP request during message signing (this means the return value may be NULL before a call to sign(HttpRequest)), plus all required OAuth parameters that were added because the request didn't contain them beforehand. In other words, this is the exact set of parameters that were used for creating the message signature.

Returns:

the request parameters used for message signing