Class AbstractOAuthProvider
- java.lang.Object
-
- oauth.signpost.AbstractOAuthProvider
-
- All Implemented Interfaces:
Serializable
,OAuthProvider
- Direct Known Subclasses:
CommonsHttpOAuthProvider
,DefaultOAuthProvider
public abstract class AbstractOAuthProvider extends Object implements OAuthProvider
ABC for all provider implementations. If you're writing a custom provider, you will probably inherit from this class, since it takes a lot of work from you.- Author:
- Matthias Kaeppler
- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description AbstractOAuthProvider(String requestTokenEndpointUrl, String accessTokenEndpointUrl, String authorizationWebsiteUrl)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected void
closeConnection(HttpRequest request, HttpResponse response)
Called when the connection is being finalized after receiving the response.protected abstract HttpRequest
createRequest(String endpointUrl)
Overrride this method if you want to customize the logic for building a request object for the given endpoint URL.String
getAccessTokenEndpointUrl()
String
getAuthorizationWebsiteUrl()
Map<String,String>
getRequestHeaders()
String
getRequestTokenEndpointUrl()
protected String
getResponseParameter(String key)
Returns a single query parameter as served by the service provider in a token reply.HttpParameters
getResponseParameters()
Any additional non-OAuth parameters returned in the response body of a token request can be obtained through this method.protected void
handleUnexpectedResponse(int statusCode, HttpResponse response)
boolean
isOAuth10a()
void
removeListener(OAuthProviderListener listener)
void
retrieveAccessToken(OAuthConsumer consumer, String oauthVerifier, String... customOAuthParams)
Queries the service provider for an access token.String
retrieveRequestToken(OAuthConsumer consumer, String callbackUrl, String... customOAuthParams)
Queries the service provider for a request token.protected void
retrieveToken(OAuthConsumer consumer, String endpointUrl, HttpParameters customOAuthParams)
Implemented by subclasses.protected abstract HttpResponse
sendRequest(HttpRequest request)
Override this method if you want to customize the logic for how the given request is sent to the server.void
setListener(OAuthProviderListener listener)
void
setOAuth10a(boolean isOAuth10aProvider)
void
setRequestHeader(String header, String value)
Use this method to set custom HTTP headers to be used for the requests which are sent to retrieve tokens.void
setResponseParameters(HttpParameters parameters)
Subclasses must use this setter to preserve any non-OAuth query parameters contained in the server response.
-
-
-
Method Detail
-
retrieveRequestToken
public String retrieveRequestToken(OAuthConsumer consumer, String callbackUrl, String... customOAuthParams) throws OAuthMessageSignerException, OAuthNotAuthorizedException, OAuthExpectationFailedException, OAuthCommunicationException
Description copied from interface:OAuthProvider
Queries the service provider for a request token.Pre-conditions: the given
OAuthConsumer
must have a valid consumer key and consumer secret already set.Post-conditions: the given
OAuthConsumer
will have an unauthorized request token and token secret set.- Specified by:
retrieveRequestToken
in interfaceOAuthProvider
- Parameters:
consumer
- theOAuthConsumer
that should be used to sign the requestcallbackUrl
- Pass an actual URL if your app can receive callbacks and you want to get informed about the result of the authorization process. PassOAuth.OUT_OF_BAND
if the service provider implements OAuth 1.0a and your app cannot receive callbacks. Pass null if the service provider implements OAuth 1.0 and your app cannot receive callbacks. Please note that some services (among them Twitter) will fail authorization if you pass a callback URL but register your application as a desktop app (which would only be able to handle OOB requests).customOAuthParams
- you can pass custom OAuth parameters here which will go directly into the signer, i.e. you don't have to put them into the request first. This is useful for pre-setting OAuth params for signing. Pass them sequentially in key/value order.- Returns:
- The URL to which the user must be sent in order to authorize the consumer. It includes the unauthorized request token (and in the case of OAuth 1.0, the callback URL -- 1.0a clients send along with the token request).
- Throws:
OAuthMessageSignerException
- if signing the request failedOAuthNotAuthorizedException
- if the service provider rejected the consumerOAuthExpectationFailedException
- if required parameters were not correctly set by the consumer or service providerOAuthCommunicationException
- if server communication failed
-
retrieveAccessToken
public void retrieveAccessToken(OAuthConsumer consumer, String oauthVerifier, String... customOAuthParams) throws OAuthMessageSignerException, OAuthNotAuthorizedException, OAuthExpectationFailedException, OAuthCommunicationException
Description copied from interface:OAuthProvider
Queries the service provider for an access token.Pre-conditions: the given
OAuthConsumer
must have a valid consumer key, consumer secret, authorized request token and token secret already set.Post-conditions: the given
OAuthConsumer
will have an access token and token secret set.- Specified by:
retrieveAccessToken
in interfaceOAuthProvider
- Parameters:
consumer
- theOAuthConsumer
that should be used to sign the requestoauthVerifier
- NOTE: Only applies to service providers implementing OAuth 1.0a. Set to null if the service provider is still using OAuth 1.0. The verification code issued by the service provider after the the user has granted the consumer authorization. If the callback method provided in the previous step wasOAuth.OUT_OF_BAND
, then you must ask the user for this value. If your app has received a callback, the verfication code was passed as part of that request instead.customOAuthParams
- you can pass custom OAuth parameters here which will go directly into the signer, i.e. you don't have to put them into the request first. This is useful for pre-setting OAuth params for signing. Pass them sequentially in key/value order.- Throws:
OAuthMessageSignerException
- if signing the request failedOAuthNotAuthorizedException
- if the service provider rejected the consumerOAuthExpectationFailedException
- if required parameters were not correctly set by the consumer or service providerOAuthCommunicationException
- if server communication failed
-
retrieveToken
protected void retrieveToken(OAuthConsumer consumer, String endpointUrl, HttpParameters customOAuthParams) throws OAuthMessageSignerException, OAuthCommunicationException, OAuthNotAuthorizedException, OAuthExpectationFailedException
Implemented by subclasses. The responsibility of this method is to contact the service provider at the given endpoint URL and fetch a request or access token. What kind of token is retrieved solely depends on the URL being used.
Correct implementations of this method must guarantee the following post-conditions:
- the
OAuthConsumer
passed to this method must have a validOAuth.OAUTH_TOKEN
andOAuth.OAUTH_TOKEN_SECRET
set by callingOAuthConsumer.setTokenWithSecret(String, String)
getResponseParameters()
must return the set of query parameters served by the service provider in the token response, with all OAuth specific parameters being removed
- Parameters:
consumer
- theOAuthConsumer
that should be used to sign the requestendpointUrl
- the URL at which the service provider serves the OAuth token that is to be fetchedcustomOAuthParams
- you can pass custom OAuth parameters here (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.- Throws:
OAuthMessageSignerException
- if signing the token request failsOAuthCommunicationException
- if a network communication error occursOAuthNotAuthorizedException
- if the server replies 401 - UnauthorizedOAuthExpectationFailedException
- if an expectation has failed, e.g. because the server didn't reply in the expected format
- the
-
handleUnexpectedResponse
protected void handleUnexpectedResponse(int statusCode, HttpResponse response) throws Exception
- Throws:
Exception
-
createRequest
protected abstract HttpRequest createRequest(String endpointUrl) throws Exception
Overrride this method if you want to customize the logic for building a request object for the given endpoint URL.- Parameters:
endpointUrl
- the URL to which the request will go- Returns:
- the request object
- Throws:
Exception
- if something breaks
-
sendRequest
protected abstract HttpResponse sendRequest(HttpRequest request) throws Exception
Override this method if you want to customize the logic for how the given request is sent to the server.- Parameters:
request
- the request to send- Returns:
- the response to the request
- Throws:
Exception
- if something breaks
-
closeConnection
protected void closeConnection(HttpRequest request, HttpResponse response) throws Exception
Called when the connection is being finalized after receiving the response. Use this to do any cleanup / resource freeing.- Parameters:
request
- the request that has been sentresponse
- the response that has been received- Throws:
Exception
- if something breaks
-
getResponseParameters
public HttpParameters getResponseParameters()
Description copied from interface:OAuthProvider
Any additional non-OAuth parameters returned in the response body of a token request can be obtained through this method. These parameters will be preserved until the next token request is issued. The return value is never null.- Specified by:
getResponseParameters
in interfaceOAuthProvider
-
getResponseParameter
protected String getResponseParameter(String key)
Returns a single query parameter as served by the service provider in a token reply. You must callsetResponseParameters(oauth.signpost.http.HttpParameters)
with the set of parameters before using this method.- Parameters:
key
- the parameter name- Returns:
- the parameter value
-
setResponseParameters
public void setResponseParameters(HttpParameters parameters)
Description copied from interface:OAuthProvider
Subclasses must use this setter to preserve any non-OAuth query parameters contained in the server response. It's the caller's responsibility that any OAuth parameters be removed beforehand.- Specified by:
setResponseParameters
in interfaceOAuthProvider
- Parameters:
parameters
- the map of query parameters served by the service provider in the token response
-
setOAuth10a
public void setOAuth10a(boolean isOAuth10aProvider)
- Specified by:
setOAuth10a
in interfaceOAuthProvider
- Parameters:
isOAuth10aProvider
- set to true if the service provider supports OAuth 1.0a. Note that you need only call this method if you reconstruct a provider object in between calls to retrieveRequestToken() and retrieveAccessToken() (i.e. if the object state isn't preserved). If instead those two methods are called on the same provider instance, this flag will be deducted automatically based on the server response during retrieveRequestToken(), so you can simply ignore this method.
-
isOAuth10a
public boolean isOAuth10a()
- Specified by:
isOAuth10a
in interfaceOAuthProvider
- Returns:
- true if the service provider supports OAuth 1.0a. Note that the value returned here is only meaningful after you have already performed the token handshake, otherwise there is no way to determine what version of the OAuth protocol the service provider implements.
-
getRequestTokenEndpointUrl
public String getRequestTokenEndpointUrl()
- Specified by:
getRequestTokenEndpointUrl
in interfaceOAuthProvider
-
getAccessTokenEndpointUrl
public String getAccessTokenEndpointUrl()
- Specified by:
getAccessTokenEndpointUrl
in interfaceOAuthProvider
-
getAuthorizationWebsiteUrl
public String getAuthorizationWebsiteUrl()
- Specified by:
getAuthorizationWebsiteUrl
in interfaceOAuthProvider
-
setRequestHeader
public void setRequestHeader(String header, String value)
Description copied from interface:OAuthProvider
Use this method to set custom HTTP headers to be used for the requests which are sent to retrieve tokens. @deprecated THIS METHOD HAS BEEN DEPRECATED. UseOAuthProviderListener
to customize requests.- Specified by:
setRequestHeader
in interfaceOAuthProvider
- Parameters:
header
- The header name (e.g. 'WWW-Authenticate')value
- The header value (e.g. 'realm=www.example.com')
-
getRequestHeaders
public Map<String,String> getRequestHeaders()
- Specified by:
getRequestHeaders
in interfaceOAuthProvider
- Returns:
- all request headers set via
OAuthProvider.setRequestHeader(java.lang.String, java.lang.String)
-
setListener
public void setListener(OAuthProviderListener listener)
- Specified by:
setListener
in interfaceOAuthProvider
-
removeListener
public void removeListener(OAuthProviderListener listener)
- Specified by:
removeListener
in interfaceOAuthProvider
-
-