winterwell.jtwitter
Class OAuthSignpostClient

java.lang.Object
  winterwell.jtwitter.URLConnectionHttpClient
      winterwell.jtwitter.OAuthSignpostClient

All Implemented Interfaces:

java.io.Serializable, 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.

First download the Signpost jar and add it to your classpath, as it isn't included in the JTwitter download.

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

 
        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
        Object accessToken = client.getAccessToken();
        // use the API!
        jtwit.setStatus("Messing about in Java");
        
 

Example Usage #2 (using callbacks):
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

static java.lang.String	JTWITTER_OAUTH_KEY This consumer key (and secret) allows you to get up and running fast.
static java.lang.String	JTWITTER_OAUTH_SECRET For use with JTWITTER_OAUTH_KEY

Fields inherited from class winterwell.jtwitter.URLConnectionHttpClient

name, timeout

Constructor Summary

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

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

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()
boolean	canAuthenticate() Whether this client is setup to do authentication when contacting the Twitter server.
Twitter.IHttpClient	copy()
java.lang.String[]	getAccessToken()
java.net.HttpURLConnection	post2_connect(java.lang.String uri, java.util.Map<java.lang.String,java.lang.String> vars) Lower-level POST method.
protected void	setAuthentication(java.net.URLConnection connection, java.lang.String name, java.lang.String password) Set a header for basic authentication login.
void	setAuthorizationCode(java.lang.String verifier) Set the authorisation code (aka the verifier).
void	setFoursquareProvider()
void	setName(java.lang.String name) Unlike the base class URLConnectionHttpClient, this does not set name by default.
void	setProvider(DefaultOAuthProvider provider) Set to Twitter settings by default.

Methods inherited from class winterwell.jtwitter.URLConnectionHttpClient

close, connect, disconnect, getHeader, getPage, getRateLimit, post, post2_getPayload, processHeaders, setMinRateLimit, setRetryOnError, setTimeout, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface winterwell.jtwitter.Twitter.IHttpClient

connect, getHeader, getPage, getRateLimit, post, setTimeout

Field Detail

JTWITTER_OAUTH_KEY

public static final java.lang.String JTWITTER_OAUTH_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)

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 -

Method Detail

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:

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()

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.

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.

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.

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

setAuthentication

protected void setAuthentication(java.net.URLConnection connection,
                                 java.lang.String name,
                                 java.lang.String password)

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).

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()

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(DefaultOAuthProvider provider)

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

Parameters:

provider -