|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface OAuthProvider
Supplies an interface that can be used to retrieve request and access tokens
from an OAuth 1.0(a) service provider. A provider object requires an
OAuthConsumer
to sign the token request message; after a token has
been retrieved, the consumer is automatically updated with the token and the
corresponding secret.
To initiate the token exchange, create a new provider instance and configure it with the URLs the service provider exposes for requesting tokens and resource authorization, e.g.:
OAuthProvider provider = new DefaultOAuthProvider("http://twitter.com/oauth/request_token", "http://twitter.com/oauth/access_token", "http://twitter.com/oauth/authorize");
Depending on the HTTP library you use, you may need a different provider type, refer to the website documentation for how to do that.
To receive a request token which the user must authorize, you invoke it using a consumer instance and a callback URL:
String url = provider.retrieveRequestToken(consumer, "http://www.example.com/callback");
That url must be opened in a Web browser, where the user can grant access to the resources in question. If that succeeds, the service provider will redirect to the callback URL and append the blessed request token.
That token must now be exchanged for an access token, as such:
provider.retrieveAccessToken(consumer, nullOrVerifierCode);
where nullOrVerifierCode is either null if your provided a callback URL in
the previous step, or the pin code issued by the service provider to the user
if the request was out-of-band (cf. OAuth.OUT_OF_BAND
.
The consumer used during token handshakes is now ready for signing.
DefaultOAuthProvider
,
DefaultOAuthConsumer
,
OAuthProviderListener
Method Summary | |
---|---|
String |
getAccessTokenEndpointUrl()
|
String |
getAuthorizationWebsiteUrl()
|
Map<String,String> |
getRequestHeaders()
Deprecated. THIS METHOD HAS BEEN DEPRECATED. Use OAuthProviderListener to customize requests. |
String |
getRequestTokenEndpointUrl()
|
HttpParameters |
getResponseParameters()
Any additional non-OAuth parameters returned in the response body of a token request can be obtained through this method. |
boolean |
isOAuth10a()
|
void |
removeListener(OAuthProviderListener listener)
|
void |
retrieveAccessToken(OAuthConsumer consumer,
String oauthVerifier)
Queries the service provider for an access token. |
String |
retrieveRequestToken(OAuthConsumer consumer,
String callbackUrl)
Queries the service provider for a request token. |
void |
setListener(OAuthProviderListener listener)
|
void |
setOAuth10a(boolean isOAuth10aProvider)
|
void |
setRequestHeader(String header,
String value)
Deprecated. |
void |
setResponseParameters(HttpParameters parameters)
Subclasses must use this setter to preserve any non-OAuth query parameters contained in the server response. |
Method Detail |
---|
String retrieveRequestToken(OAuthConsumer consumer, String callbackUrl) throws OAuthMessageSignerException, OAuthNotAuthorizedException, OAuthExpectationFailedException, OAuthCommunicationException
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.
consumer
- the OAuthConsumer
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.
Pass OAuth.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).
OAuthMessageSignerException
- if signing the request failed
OAuthNotAuthorizedException
- if the service provider rejected the consumer
OAuthExpectationFailedException
- if required parameters were not correctly set by the consumer or
service provider
OAuthCommunicationException
- if server communication failedvoid retrieveAccessToken(OAuthConsumer consumer, String oauthVerifier) throws OAuthMessageSignerException, OAuthNotAuthorizedException, OAuthExpectationFailedException, OAuthCommunicationException
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.
consumer
- the OAuthConsumer
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 was
OAuth.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.
OAuthMessageSignerException
- if signing the request failed
OAuthNotAuthorizedException
- if the service provider rejected the consumer
OAuthExpectationFailedException
- if required parameters were not correctly set by the consumer or
service provider
OAuthCommunicationException
- if server communication failedHttpParameters getResponseParameters()
void setResponseParameters(HttpParameters parameters)
parameters
- the map of query parameters served by the service provider in the
token response@Deprecated void setRequestHeader(String header, String value)
OAuthProviderListener
to customize requests.
header
- The header name (e.g. 'WWW-Authenticate')value
- The header value (e.g. 'realm=www.example.com')@Deprecated Map<String,String> getRequestHeaders()
OAuthProviderListener
to customize requests.
setRequestHeader(java.lang.String, java.lang.String)
void setOAuth10a(boolean isOAuth10aProvider)
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.boolean isOAuth10a()
String getRequestTokenEndpointUrl()
String getAccessTokenEndpointUrl()
String getAuthorizationWebsiteUrl()
void setListener(OAuthProviderListener listener)
void removeListener(OAuthProviderListener listener)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |