winterwell.jtwitter

Class OAuthSignpostClient

java.lang.Object

winterwell.jtwitter.URLConnectionHttpClient

winterwell.jtwitter.OAuthSignpostClient

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Twitter.IHttpClient

public class OAuthSignpostClient
extends URLConnectionHttpClient
implements Twitter.IHttpClient, java.io.Serializable

OAuth based login using Signpost (http://code.google.com/p/oauth-signpost/). This is the "official" JTwitter OAuth support.

The Signpost jar is included in the JTwitter download.

Example Usage #1 (out-of-bounds, desktop based -- _not_ for Android):

 
        OAuthSignpostClient client = new OAuthSignpostClient(JTWITTER_OAUTH_KEY, JTWITTER_OAUTH_SECRET, "oob");
        Twitter jtwit = new Twitter("yourtwittername", client);
        // open the authorisation page in the user's browser
        // This is a convenience method for directing the user to client.authorizeUrl()
        client.authorizeDesktop();
        // get the pin
        String v = client.askUser("Please enter the verification PIN from Twitter");
        client.setAuthorizationCode(v);
        // Optional: store the authorisation token details
        String[] accessToken = client.getAccessToken();
        // use the API!
        jtwit.setStatus("Messing about in Java");
        
 

Example Usage #2 (using callbacks, works on Android):
If you can handle callbacks, then this can be streamlined. On Android, you can use Intents to launch a web page, & to catch the resulting callback. On a desktop, you need a webserver and a servlet (eg. use Jetty or Tomcat) to handle callbacks.

Replace "oob" with your callback url. Direct the user to client.authorizeUrl(). Twitter will then call your callback with the request token and verifier (authorisation code).

 
        OAuthSignpostClient client = new OAuthSignpostClient(JTWITTER_OAUTH_KEY, JTWITTER_OAUTH_SECRET, myCallbackUrl);
        Twitter jtwit = new Twitter("yourtwittername", client);
        URI url = client.authorizeUrl();
        // Direct the user to this url!
        
 

Now we wait for the callback...

 
        HttpServletRequest request = from your servlet; 
        // get the pin
        String verifier = request.getParameter("oauth_verifier");
        client.setAuthorizationCode(verifier);
 
        // The client is now good for use. But wait: if you get an access token
        // and secret, you can store them for next time:
        String[] accessTokenAndSecret = client.getAccessToken();
        // Then you can in future use
        // OAuthSignpostClient client = new OAuthSignpostClient(APP_KEY, APP_SECRET, ACCESS_TOKEN, ACCESS_TOKEN_SECRET);
 
        // use the API!
        jtwit.setStatus("Messing about in Java");
        
 

There are alternative OAuth libraries you can use:

See Also:

OAuthHttpClient, OAuthScribeClient, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	JTWITTER_OAUTH_KEY Deprecated. Please register an app with Twitter and use your own key! This consumer key (and secret) allows you to get up and running fast. However you are strongly advised to register your own app at http://dev.twitter.com Then use your own key and secret. This will be less confusing for users, and it protects you incase the JTwitter key gets changed.
static java.lang.String	JTWITTER_OAUTH_SECRET For use with JTWITTER_OAUTH_KEY

Fields inherited from class winterwell.jtwitter.URLConnectionHttpClient

name, timeout

Constructor Summary

Constructors

Constructor and Description
OAuthSignpostClient(java.lang.String consumerKey, java.lang.String consumerSecret, java.lang.String callbackUrl) This is for doing the initial authorisation.
OAuthSignpostClient(java.lang.String consumerKey, java.lang.String consumerSecret, java.lang.String accessToken, java.lang.String accessTokenSecret) Use this if you already have an accessToken for the user.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	askUser(java.lang.String question) Convenience method for desktop apps only - does not work in Android
void	authorizeDesktop() Deprecated.
java.net.URI	authorizeUrl() Call Twitter to start the authorisation flow.
boolean	canAuthenticate() Whether this client is setup to do authentication when contacting the Twitter server.
URLConnectionHttpClient	clone() Identical to URLConnectionHttpClient.copy()
Twitter.IHttpClient	copy()
java.lang.String[]	getAccessToken()
OAuthConsumer	getConsumer()
AbstractOAuthProvider	getProvider()
HttpParameters	getProviderResponseParams() Provide low level access to the provider -- e.g.
java.net.HttpURLConnection	post2_connect(java.lang.String uri, com.winterwell.json.JSONObject body) Lower-level POST method - stringifies JSON body instead of encoding vars
java.net.HttpURLConnection	post2_connect(java.lang.String uri, java.util.Map<java.lang.String,java.lang.String> vars) Lower-level POST method.
java.lang.String	postMultipartForm(java.lang.String url, java.util.Map<java.lang.String,?> vars)
protected void	setAuthentication(java.net.URLConnection connection) Set a header for basic authentication login.
void	setAuthorizationCode(java.lang.String verifier) Set the authorisation code (aka the verifier).
void	setAuthorizationCode(java.lang.String verifier, java.lang.String oauth_token, java.lang.String oauth_token_secret) Set the authorisation code (aka the verifier).
void	setFlickrProvider()
void	setFoursquareProvider()
void	setLinkedInProvider() Replace the default Twitter urls with the LinkedIn urls.
void	setName(java.lang.String name) Unlike the base class URLConnectionHttpClient, this does not set name by default.
void	setProvider(AbstractOAuthProvider provider) Set to Twitter settings by default.
java.lang.String	signInUrl()

Methods inherited from class winterwell.jtwitter.URLConnectionHttpClient

checkRateLimit, connect, delete, disconnect, getHeader, getPage, getRateLimit, getRateLimits, isRetryOnError, post, post2_connect, post2_getPayload, postJSON, processHeaders, setGzip, setHtmlImpliesError, setMinRateLimit, setRetryOnError, setTimeout, toString, updateRateLimits

Methods inherited from class java.lang.Object

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

Methods inherited from interface winterwell.jtwitter.Twitter.IHttpClient

connect, delete, getHeader, getPage, getRateLimit, getRateLimits, isRetryOnError, post, post2_connect, postJSON, setRetryOnError, setTimeout

Field Detail

JTWITTER_OAUTH_KEY

public static final java.lang.String JTWITTER_OAUTH_KEY

Deprecated. Please register an app with Twitter and use your own key!

This consumer key (and secret) allows you to get up and running fast. However you are strongly advised to register your own app at http://dev.twitter.com Then use your own key and secret. This will be less confusing for users, and it protects you incase the JTwitter key gets changed.

See Also:

Constant Field Values

JTWITTER_OAUTH_SECRET

public static final java.lang.String JTWITTER_OAUTH_SECRET

For use with JTWITTER_OAUTH_KEY

See Also:

Constant Field Values

Constructor Detail

OAuthSignpostClient

public OAuthSignpostClient(java.lang.String consumerKey,
                           java.lang.String consumerSecret,
                           java.lang.String callbackUrl)

This is for doing the initial authorisation.

Parameters:

consumerKey -

consumerSecret -

callbackUrl - Servlet that will get the verifier sent to it, or "oob" for out-of-band (user copies and pastes the pin to you)

OAuthSignpostClient

public OAuthSignpostClient(java.lang.String consumerKey,
                           java.lang.String consumerSecret,
                           java.lang.String accessToken,
                           java.lang.String accessTokenSecret)

Use this if you already have an accessToken for the user. You can then go straight to using the API without having to authorise again.

Parameters:

consumerKey -

consumerSecret -

accessToken -

accessTokenSecret -

Method Detail

getConsumer

public OAuthConsumer getConsumer()

Returns:

the consumer, which

postMultipartForm

public final java.lang.String postMultipartForm(java.lang.String url,
                                                java.util.Map<java.lang.String,?> vars)
                                         throws TwitterException

Parameters:

uri -

vars - Can include File values

Returns:

Throws:

TwitterException

askUser

public static java.lang.String askUser(java.lang.String question)

Convenience method for desktop apps only - does not work in Android

Opens a popup dialog asking the user to enter the verification code. (you would then call setAuthorizationCode(String)). This is only relevant when using out-of-band instead of a callback-url. This is a convenience method -- you will probably want to build your own UI around this.

This method requires Swing. It will not work on Android devices!

Parameters:

question - e.g. "Please enter the authorisation code from Twitter"

Returns:

getProvider

public AbstractOAuthProvider getProvider()

authorizeDesktop

@Deprecated
public void authorizeDesktop()

Deprecated.

Redirect the user's browser to Twitter's authorise page. You will need to collect the verifier pin - either from the callback servlet, or from the user (out-of-band).

This method requires Swing. It will not work on Android!

See Also:

authorizeUrl()

authorizeUrl

public java.net.URI authorizeUrl()

Call Twitter to start the authorisation flow. This will lead to (a) this object storing a token secret (needed later for verification) and (b) a url to redirect the user to.

Returns:

url to direct the user to for authorisation. Send the user to this url. They click "OK", then get redirected to your callback url.

See Also:

signInUrl();

signInUrl

public java.lang.String signInUrl()

Returns:

url to direct the user to for sign-in with Twitter. Send the user to this url. If they've already authorised, then they get an instant redirect.

See Also:

signInUrl();

canAuthenticate

public boolean canAuthenticate()

Description copied from interface: Twitter.IHttpClient

Whether this client is setup to do authentication when contacting the Twitter server. Note: This is a fast method that does not call the server, so it does not check whether the access token or password is valid. See {Twitter#isValidLogin()} or Twitter_Account.verifyCredentials() if you need to check a login.

Specified by:

canAuthenticate in interface Twitter.IHttpClient

Overrides:

canAuthenticate in class URLConnectionHttpClient

copy

public Twitter.IHttpClient copy()

Specified by:

copy in interface Twitter.IHttpClient

Overrides:

copy in class URLConnectionHttpClient

Returns:

a copy of this client. The copy can share structure, but it MUST be safe for passing to a new thread to be used in parallel with the original.

clone

public URLConnectionHttpClient clone()

Description copied from class: URLConnectionHttpClient

Identical to URLConnectionHttpClient.copy()

Overrides:

clone in class URLConnectionHttpClient

getAccessToken

public java.lang.String[] getAccessToken()

Returns:

the access token and access token secret - if this client was constructed with an access token, or has successfully authenticated and got one. null otherwise. Also returns the expiry time, if we've got one (null if not). See setExpiryKey for how to locate these.

post2_connect

public java.net.HttpURLConnection post2_connect(java.lang.String uri,
                                                java.util.Map<java.lang.String,java.lang.String> vars)
                                         throws java.io.IOException,
                                                OAuthException

Description copied from interface: Twitter.IHttpClient

Lower-level POST method.

Specified by:

post2_connect in interface Twitter.IHttpClient

Overrides:

post2_connect in class URLConnectionHttpClient

Returns:

a freshly opened authorised connection

Throws:

java.io.IOException

OAuthException

post2_connect

public java.net.HttpURLConnection post2_connect(java.lang.String uri,
                                                com.winterwell.json.JSONObject body)
                                         throws java.io.IOException,
                                                OAuthException

Description copied from interface: Twitter.IHttpClient

Lower-level POST method - stringifies JSON body instead of encoding vars

Specified by:

post2_connect in interface Twitter.IHttpClient

Overrides:

post2_connect in class URLConnectionHttpClient

Returns:

a freshly opened authorised connection

Throws:

java.io.IOException

OAuthException

setAuthentication

protected void setAuthentication(java.net.URLConnection connection)

Description copied from class: URLConnectionHttpClient

Set a header for basic authentication login.

Overrides:

setAuthentication in class URLConnectionHttpClient

setAuthorizationCode

public void setAuthorizationCode(java.lang.String verifier)
                          throws TwitterException

Set the authorisation code (aka the verifier). This must be the same object as you used to create the authorisation redirect! Otherwise the temporary token/secret will not be set, and you'll get an error.

Parameters:

verifier - a pin code which Twitter gives the user (with the oob method), or which you get from the callback response as the parameter "oauth_verifier".

Throws:

java.lang.RuntimeException - throws an exception if the verifier is invalid

TwitterException

setAuthorizationCode

public void setAuthorizationCode(java.lang.String verifier,
                                 java.lang.String oauth_token,
                                 java.lang.String oauth_token_secret)
                          throws TwitterException

Set the authorisation code (aka the verifier). And get an accessToken + secret

Parameters:

verifier - a pin code which Twitter gives the user (with the oob method), or which you get from the callback response as the parameter "oauth_verifier".

Throws:

java.lang.RuntimeException - throws an exception if the verifier is invalid

TwitterException

setFoursquareProvider

public void setFoursquareProvider()

setLinkedInProvider

public void setLinkedInProvider()

Replace the default Twitter urls with the LinkedIn urls.

setFlickrProvider

public void setFlickrProvider()

setName

public void setName(java.lang.String name)

Unlike the base class URLConnectionHttpClient, this does not set name by default. But you can set it for nicer error messages.

Parameters:

name -

setProvider

public void setProvider(AbstractOAuthProvider provider)

Set to Twitter settings by default. This method lets you override that.

Parameters:

provider - Note: These objects are NOT thread safe.

See Also:

setLinkedInProvider(), setFoursquareProvider()

getProviderResponseParams

public HttpParameters getProviderResponseParams()

Provide low level access to the provider -- e.g. allows for getting the expiry details from LinkedIn.