Twitter

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

winterwell.jtwitter
Class Twitter

java.lang.Object
  winterwell.jtwitter.Twitter

public class Twitter
extends java.lang.Object
extends java.lang.Object

Java wrapper for the Twitter API version "1.7.3"

Example usage:
First, you should get the user to authorise access via OAuth. There are a couple of ways of doing this -- we show one below -- see OAuthSignpostClient for more details.

Note that you don't need to do this for some operations - e.g. you can look up public posts without logging in (use the Twitter() constructor. You can also - for now! - use username and password to login, but Twitter plan to switch this off soon.

        // First, OAuth to login: Make an oauth client
        OAuthSignpostClient oauthClient = new OAuthSignpostClient(JTWITTER_OAUTH_KEY, JTWITTER_OAUTH_SECRET, "oob");
    // open the authorisation page in the user's browser
    oauthClient.authorizeDesktop(); // Note: this only works on desktop PCs
    // or direct the user to the webpage given by oauthClient.authorizeUrl() 
    // get the pin from the user since we're using "oob" instead of a callback servlet
    String v = oauthClient.askUser("Please enter the verification PIN from Twitter");
    oauthClient.setAuthorizationCode(v);
        // You can store the authorisation token details for future use
    Object accessToken = client.getAccessToken();

Now we can access Twitter:

        // Make a Twitter object
        Twitter twitter = new Twitter("my-name", oauthClient); 
        // Print Winterstein's status
        System.out.println(twitter.getStatus("winterstein"));
        // Set my status
        twitter.updateStatus("Messing about in Java");

If you can handle callbacks, then the OAuth login can be streamlined. 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).

See http://www.winterwell.com/software/jtwitter.php for more information about this wrapper. See ://apiwiki.twitter.com/Twitter-API-Documentation for more information about the Twitter API.

Notes:

This wrapper takes care of all url-encoding/decoding.
This wrapper will throw a runtime exception (TwitterException) if a methods fails, e.g. it cannot connect to Twitter.com or you make a bad request.
Note that Twitter treats old-style retweets (those made by sending a normal tweet beginning "RT @whoever") differently from new-style retweets (those made using the retweet API). The differences are documented in various methods.
Most methods are in this class (Twitter), except for list support (in TwitterList - though getLists() is here) and some profile/account settings (in TwitterAccount).

Copyright and License

This code is copyright (c) Winterwell Associates 2008/2009 and (c) winterwell Mathematics Ltd, 2007 except where otherwise stated. It is released as open-source under the LGPL license. See http://www.gnu.org/licenses/lgpl.html for license details. This code comes with no warranty or support.

Change List

The change list is kept online at: ://www.winterwell.com/software/changelist.txt

Nested Class Summary
`static interface`	`Twitter.ICallback` Use to register per-page callbacks for long-running searches.
`static interface`	`Twitter.IHttpClient` Interface for an http client - e.g.
`static interface`	`Twitter.ITweet` This gives common access to features that are common to both `Twitter.Message`s and `Twitter.Status`es.
`static class`	`Twitter.KEntityType`
`static class`	`Twitter.Message` A Twitter direct message.
`static class`	`Twitter.Status` A Twitter status post.
`static class`	`Twitter.TweetEntity` TODO A special slice of text within a tweet.
`static class`	`Twitter.User` A Twitter user.

Field Summary
`static java.lang.String`	`version` JTwitter version

Constructor Summary
`Twitter()` Create a Twitter client without specifying a user.
`Twitter(java.lang.String screenName, java.lang.String password)` Deprecated.
`Twitter(java.lang.String name, Twitter.IHttpClient client)` Java wrapper for the Twitter API.

Method Summary
`Twitter.User`	`befriend(java.lang.String username)` Deprecated. Use `follow(String)` instead, which is equivalent.
`Twitter.User`	`breakFriendship(java.lang.String username)` Deprecated. Please use `stopFollowing(String)` instead.
`java.util.List<Twitter.User>`	`bulkShow(java.util.List<java.lang.String> screenNames)` Lookup user info.
`java.util.List<Twitter.User>`	`bulkShowById(java.util.List<java.lang.Long> userIds)` Lookup user info.
`void`	`destroy(Twitter.ITweet tweet)` Deletes the given Status or Message.
`void`	`destroyStatus(long id)` Deletes the status specified by the required ID parameter.
`void`	`destroyStatus(Twitter.Status status)` Deprecated. in favour of `destroy(ITweet)`. This method will be removed by the end of 2010.
`Twitter.User`	`follow(java.lang.String username)` Start following a user.
`void`	`follow(Twitter.User user)` Convenience for `follow(String)`
`static java.util.Date`	`getDate(int year, java.lang.String month, int day)` Convenience method for making Dates.
`java.util.List<Twitter.Message>`	`getDirectMessages()` Returns a list of the direct messages sent to the authenticating user.
`java.util.List<Twitter.Message>`	`getDirectMessagesSent()` Returns a list of the direct messages sent by the authenticating user.
`java.util.List<Twitter.Status>`	`getFavorites()` The most recent 20 favourite tweets.
`java.util.List<Twitter.Status>`	`getFavorites(java.lang.String screenName)` The most recent 20 favourite tweets for the given user.
`java.util.List<Twitter.User>`	`getFeatured()` Returns a list of the users currently featured on the site with their current statuses inline.
`java.util.List<java.lang.Long>`	`getFollowerIDs()` Returns the IDs of the authenticating user's followers.
`java.util.List<java.lang.Long>`	`getFollowerIDs(java.lang.String screenName)` Returns the IDs of the specified user's followers.
`java.util.List<Twitter.User>`	`getFollowers()` Returns the authenticating user's (latest) followers, each with current status inline.
`java.util.List<Twitter.User>`	`getFollowers(java.lang.String username)` Returns the (latest 100) given user's followers, each with current status inline.
`java.util.List<java.lang.Long>`	`getFriendIDs()` Returns the IDs of the authenticating user's friends.
`java.util.List<java.lang.Long>`	`getFriendIDs(java.lang.String screenName)` Returns the IDs of the specified user's friends.
`java.util.List<Twitter.User>`	`getFriends()` Returns the authenticating user's (latest 100) friends, each with current status inline.
`java.util.List<Twitter.User>`	`getFriends(java.lang.String username)` Returns the (latest 100) given user's friends, each with current status inline.
`java.util.List<Twitter.Status>`	`getFriendsTimeline()` Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends.
`java.util.List<Twitter.Status>`	`getHomeTimeline()` Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends, including retweets.
`Twitter.IHttpClient`	`getHttpClient()` Provides access to the `Twitter.IHttpClient` which manages the low-level authentication, posts and gets.
`java.util.List<TwitterList>`	`getLists()`
`java.util.List<TwitterList>`	`getLists(java.lang.String screenName)`
`java.lang.String`	`getLongStatus(Twitter.Status truncatedStatus)`
`int`	`getMaxResults()` Provides support for fetching many pages.
`java.util.List<Twitter.Status>`	`getPublicTimeline()` Returns the 20 most recent statuses from non-protected users who have set a custom user icon.
`int`	`getRateLimitStatus()`
`java.util.List<Twitter.Status>`	`getReplies()` Returns the 20 most recent replies/mentions (status updates with
`java.util.List<Twitter.User>`	`getRetweeters(Twitter.Status tweet)` Show users who (new-style) retweeted the given tweet.
`java.util.List<Twitter.Status>`	`getRetweets(Twitter.Status tweet)`
`java.util.List<Twitter.Status>`	`getRetweetsByMe()`
`java.util.List<Twitter.Status>`	`getRetweetsOfMe()`
`java.lang.String`	`getScreenName()`
`Twitter.Status`	`getStatus()`
`Twitter.Status`	`getStatus(long id)` Returns a single status, specified by the id parameter below.
`Twitter.Status`	`getStatus(java.lang.String username)`
`java.util.List<java.lang.String>`	`getTrends()`
`java.util.Date`	`getUntilDate()` TODO document this please - DBW
`Twitter.User`	`getUser(long userId)` Synonym for `show(long)`.
`Twitter.User`	`getUser(java.lang.String screenName)` Synonym for `show(String)`.
`static Twitter.User`	`getUser(java.lang.String screenName, java.util.List<Twitter.User> users)` Convenience method: Finds a user with the given screen-name from the list.
`java.util.List<Twitter.Status>`	`getUserTimeline()` Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user.
`java.util.List<Twitter.Status>`	`getUserTimeline(java.lang.String screenName)` Returns the most recent statuses posted in the last 24 hours from the given user.
`java.util.List<Twitter.Status>`	`getUserTimelineWithRetweets(java.lang.String screenName)` Returns the most recent statuses posted in the last 24 hours from the given user.
`boolean`	`isFollower(java.lang.String userB)` Is the authenticating user followed by userB?
`boolean`	`isFollower(java.lang.String followerScreenName, java.lang.String followedScreenName)`
`boolean`	`isFollowing(java.lang.String userB)` Does the authenticating user follow userB?
`boolean`	`isFollowing(Twitter.User user)` Convenience for `isFollowing(String)`
`boolean`	`isTwitlongerSetup()`
`boolean`	`isValidLogin()` Are the login details used for authentication valid?
`protected static java.lang.String`	`jsonGet(java.lang.String key, org.json.JSONObject jsonObj)` Helper method to deal with JSON-in-Java weirdness
`Twitter.User`	`leaveNotifications(java.lang.String screenName)` Switches off notifications for updates from the specified user who must already be a friend.
`static void`	`main(java.lang.String[] args)`
`Twitter.User`	`notify(java.lang.String username)` Enables notifications for updates from the specified user who must already be a friend.
`Twitter.Status`	`retweet(Twitter.Status tweet)` Retweet (new-style) a tweet without any edits.
`java.util.List<Twitter.Status>`	`search(java.lang.String searchTerm)` Perform a search of Twitter.
`java.util.List<Twitter.Status>`	`search(java.lang.String searchTerm, Twitter.ICallback callback, int rpp)` Perform a search of Twitter.
`java.util.List<Twitter.User>`	`searchUsers(java.lang.String searchTerm)` Warning: there is a bug within twitter.com which means that location-based searches are treated as OR.
`Twitter.Message`	`sendMessage(java.lang.String recipient, java.lang.String text)` Sends a new direct message to the specified user from the authenticating user.
`void`	`setAPIRootUrl(java.lang.String url)` Set this to access sites other than Twitter that support the Twitter API.
`void`	`setCount(java.lang.Integer count)` Some methods - the timeline ones for example - allow a count of number-of-tweets to return.
`void`	`setFavorite(Twitter.Status status, boolean isFavorite)`
`void`	`setIncludeTweetEntities(boolean tweetEntities)`
`void`	`setLanguage(java.lang.String language)` Set a language filter for search results.
`void`	`setMaxResults(int maxResults)`
`void`	`setMyLocation(double[] latitudeLongitude)` Set the location for your tweets. Warning: geo-tagging parameters are ignored if geo_enabled for the user is false (this is the default setting for all users unless the user has enabled geolocation in their settings)!
`void`	`setPageNumber(java.lang.Integer pageNumber)`
`void`	`setSearchLocation(double latitude, double longitude, java.lang.String radius)` Restricts `search(String)` to tweets by users located within a given radius of the given latitude/longitude.
`void`	`setSinceDate(java.util.Date sinceDate)` Date based filter on statuses and messages.
`void`	`setSinceId(java.lang.Long statusId)` Narrows the returned results to just those statuses created after the specified status id.
`void`	`setSource(java.lang.String sourceApp)` Set the source application.
`Twitter.Status`	`setStatus(java.lang.String statusText)` Sets the authenticating user's status.
`void`	`setUntilDate(java.util.Date untilDate)`
`void`	`setupTwitlonger(java.lang.String twitlongerAppName, java.lang.String twitlongerApiKey)` Set this to allow the use of twitlonger via `updateLongStatus(String, long)`.
`Twitter.User`	`show(long userId)` Returns information of a given user, specified by user-id.
`Twitter.User`	`show(java.lang.String screenName)` Returns information of a given user, specified by screen name.
`java.util.List<java.lang.String>`	`splitMessage(java.lang.String longStatus)` Split a long message up into shorter chunks suitable for use with `setStatus(String)` or `sendMessage(String, String)`.
`Twitter.User`	`stopFollowing(java.lang.String username)` Destroy: Discontinues friendship with the user specified in the ID parameter as the authenticating user.
`void`	`stopFollowing(Twitter.User user)` Convenience for `stopFollowing(String)`
`Twitter.Status`	`updateLongStatus(java.lang.String message, long inReplyToStatusId)` Use twitlonger.com to post a lengthy tweet.
`Twitter.Status`	`updateStatus(java.lang.String statusText)` Updates the authenticating user's status.
`Twitter.Status`	`updateStatus(java.lang.String statusText, long inReplyToStatusId)` Updates the authenticating user's status and marks it as a reply to the tweet with the given ID.
`boolean`	`userExists(java.lang.String screenName)` Does a user with the specified name or id exist?

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

version

public static final java.lang.String version

JTwitter version

See Also:: Constant Field Values

Constructor Detail

Twitter

public Twitter()

Create a Twitter client without specifying a user. This is an easy way to access public posts. But you can't post of course.

Twitter

public Twitter(java.lang.String name,
               Twitter.IHttpClient client)

Java wrapper for the Twitter API.

Parameters:: name - the authenticating user's name, if known. Can be null.; client -

Twitter

@Deprecated
public Twitter(java.lang.String screenName,
                          java.lang.String password)

Deprecated.

Java wrapper for the Twitter API.

Parameters:: screenName - The name of the Twitter user. Only used by some methods. Can be null if you avoid methods requiring authentication.; password - The password of the Twitter user. Can be null if you avoid methods requiring authentication.

Method Detail

setAPIRootUrl

public void setAPIRootUrl(java.lang.String url)

Set this to access sites other than Twitter that support the Twitter API. E.g. WordPress or Identi.ca. Note that not all methods may work! Also, search uses a separate url and is not affected by this method (it will continue to point to Twitter).

Parameters:: url - Format: "http://domain-name", e.g. "http://twitter.com" by default.

getDate

public static java.util.Date getDate(int year,
                                     java.lang.String month,
                                     int day)

Convenience method for making Dates. Because Date is a tricksy bugger of a class.

Parameters:: year -; month -; day -
Returns:: date object

getUser

public static Twitter.User getUser(java.lang.String screenName,
                                   java.util.List<Twitter.User> users)

Convenience method: Finds a user with the given screen-name from the list.

Parameters:: screenName - aka login name; users -
Returns:: User with the given name, or null.

jsonGet

protected static java.lang.String jsonGet(java.lang.String key,
                                          org.json.JSONObject jsonObj)

Helper method to deal with JSON-in-Java weirdness

Returns:: Can be null

main

public static void main(java.lang.String[] args)

Parameters:: args - Can be used as a command-line tweet tool. To do so, enter 3 arguments: name, password, tweet If empty, prints version info.

setCount

public void setCount(java.lang.Integer count)

*Some* methods - the timeline ones for example - allow a count of number-of-tweets to return.

Parameters:: count - null for default behaviour. 200 is the current maximum. Twitter may reject or ignore high counts.

befriend

@Deprecated
public Twitter.User befriend(java.lang.String username)
                      throws TwitterException

Deprecated. Use follow(String) instead, which is equivalent.

Equivalent to follow(String). C.f. http://apiwiki.twitter.com/Migrating-to-followers-terminology

Parameters:: username - Required. The screen name of the user to befriend.
Returns:: The befriended user.
Throws:: TwitterException

breakFriendship

@Deprecated
public Twitter.User breakFriendship(java.lang.String username)

Deprecated. Please use stopFollowing(String) instead.

Equivalent to stopFollowing(String).

destroyStatus

public void destroyStatus(long id)
                   throws TwitterException

Deletes the status specified by the required ID parameter. The authenticating user must be the author of the specified status.

Throws:: TwitterException
See Also:: destroy(ITweet)

destroyStatus

@Deprecated
public void destroyStatus(Twitter.Status status)
                   throws TwitterException

Deprecated. in favour of destroy(ITweet). This method will be removed by the end of 2010.

Deletes the given status. Equivalent to #destroyStatus(int). The authenticating user must be the author of the status post.

Throws:: TwitterException
See Also:: destroy(ITweet)

destroy

public void destroy(Twitter.ITweet tweet)
             throws TwitterException

Deletes the given Status or Message. The authenticating user must be the author of the status post.

Throws:: TwitterException

follow

public Twitter.User follow(java.lang.String username)
                    throws TwitterException

Start following a user.

Parameters:: username - Required. The ID or screen name of the user to befriend.
Returns:: The befriended user, or null if they were already being followed.
Throws:: TwitterException - if the user does not exist or has been suspended.

follow

public void follow(Twitter.User user)

Convenience for follow(String)

Parameters:: user -

getDirectMessages

public java.util.List<Twitter.Message> getDirectMessages()

Returns a list of the direct messages sent to the authenticating user.

Note: the Twitter API makes this available in rss if that's of interest.

getDirectMessagesSent

public java.util.List<Twitter.Message> getDirectMessagesSent()

Returns a list of the direct messages sent *by* the authenticating user.

getFavorites

public java.util.List<Twitter.Status> getFavorites()

The most recent 20 favourite tweets. (Note: This can use page - and page only - to fetch older favourites).

setFavorite

public void setFavorite(Twitter.Status status,
                        boolean isFavorite)

getFavorites

public java.util.List<Twitter.Status> getFavorites(java.lang.String screenName)

The most recent 20 favourite tweets for the given user. (Note: This can use page - and page only - to fetch older favourites).

Parameters:: screenName - login-name.

getFeatured

public java.util.List<Twitter.User> getFeatured()
                                         throws TwitterException

Returns a list of the users currently featured on the site with their current statuses inline.

Note: This is no longer part of the Twitter API. Support is provided via other methods.

Throws:: TwitterException

getFollowerIDs

public java.util.List<java.lang.Long> getFollowerIDs()
                                              throws TwitterException

Returns the IDs of the authenticating user's followers.

Throws:: TwitterException

getFollowerIDs

public java.util.List<java.lang.Long> getFollowerIDs(java.lang.String screenName)
                                              throws TwitterException

Returns the IDs of the specified user's followers.

Parameters:: The - screen name of the user whose followers are to be fetched.
Throws:: TwitterException

getFollowers

public java.util.List<Twitter.User> getFollowers()
                                          throws TwitterException

Returns the authenticating user's (latest) followers, each with current status inline. Occasionally contains duplicates.

Throws:: TwitterException

getFollowers

public java.util.List<Twitter.User> getFollowers(java.lang.String username)
                                          throws TwitterException

Returns the (latest 100) given user's followers, each with current status inline. Occasionally contains duplicates.

Parameters:: username - The screen name of the user for whom to request a list of friends.
Throws:: TwitterException

getFriendIDs

public java.util.List<java.lang.Long> getFriendIDs()
                                            throws TwitterException

Returns the IDs of the authenticating user's friends. (people who the user follows).

Throws:: TwitterException

getFriendIDs

public java.util.List<java.lang.Long> getFriendIDs(java.lang.String screenName)
                                            throws TwitterException

Returns the IDs of the specified user's friends. Occasionally contains duplicates.

Parameters:: The - screen name of the user whose friends are to be fetched.
Throws:: TwitterException

getFriends

public java.util.List<Twitter.User> getFriends()
                                        throws TwitterException

Returns the authenticating user's (latest 100) friends, each with current status inline. NB - friends are people who *you* follow. Occasionally contains duplicates.

Note that there seems to be a small delay from Twitter in updates to this list.

Throws:: TwitterException
See Also:: getFriendIDs(), isFollowing(String)

getFriends

public java.util.List<Twitter.User> getFriends(java.lang.String username)
                                        throws TwitterException

Returns the (latest 100) given user's friends, each with current status inline. Occasionally contains duplicates.

Parameters:: username - The screen name of the user for whom to request a list of friends.
Throws:: TwitterException

getFriendsTimeline

public java.util.List<Twitter.Status> getFriendsTimeline()
                                                  throws TwitterException

Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends.

Throws:: TwitterException

getHomeTimeline

public java.util.List<Twitter.Status> getHomeTimeline()
                                               throws TwitterException

Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends, including retweets.

Throws:: TwitterException

getScreenName

public java.lang.String getScreenName()

Returns:: Login name of the authenticating user, or null if not set.

getPublicTimeline

public java.util.List<Twitter.Status> getPublicTimeline()
                                                 throws TwitterException

Returns the 20 most recent statuses from non-protected users who have set a custom user icon. Does not require authentication.

Note: Twitter cache-and-refresh this every 60 seconds, so there is little point calling it more frequently than that.

Throws:: TwitterException

getRateLimitStatus

public int getRateLimitStatus()

Returns:: the remaining number of API requests available to the authenticating user before the API limit is reached for the current hour. If this is negative you should stop using Twitter with this login for a bit. Note: Calls to rate_limit_status do not count against the rate limit.

getReplies

public java.util.List<Twitter.Status> getReplies()
                                          throws TwitterException

Returns the 20 most recent replies/mentions (status updates with

Throws:: TwitterException

getRetweetsOfMe

public java.util.List<Twitter.Status> getRetweetsOfMe()

Returns:: those of your tweets that have been retweeted. It's a bit of a strange one this. You can then query who retweeted you.

getLists

public java.util.List<TwitterList> getLists()

getLists

public java.util.List<TwitterList> getLists(java.lang.String screenName)

Parameters:: screenName -
Returns:: the (first 20) lists from the given user

getRetweets

public java.util.List<Twitter.Status> getRetweets(Twitter.Status tweet)

Returns:: *new-style* retweets of this tweet. This does not include old-style "manual" retweets.
Dear developers: we could have it that this method made two calls to Twitter and merged the two lists, thereby getting both types of retweet. There are +s and -s to this, so I'm undecided. -- Daniel

getRetweeters

public java.util.List<Twitter.User> getRetweeters(Twitter.Status tweet)

Show users who (new-style) retweeted the given tweet. Can use count (up to 100) and page.

Parameters:: tweet - You can use a "fake" Status created via Status#Status(User, String, long, Date) if you know the id number.

getStatus

public Twitter.Status getStatus()
                         throws TwitterException

Returns:: The current status of the user. Warning: this is null if (a) unset (ie if this user has never tweeted), or (b) their last six tweets were all new-style retweets!
Throws:: TwitterException

getStatus

public Twitter.Status getStatus(long id)
                         throws TwitterException

Returns a single status, specified by the id parameter below. The status's author will be returned inline.

Parameters:: id - The numerical ID of the status you're trying to retrieve.
Throws:: TwitterException

getStatus

public Twitter.Status getStatus(java.lang.String username)
                         throws TwitterException

Returns:: The current status of the given user.
Warning: this can be null if the user has been doing enough new-style retweets. This is due to flaws in the Twitter API.
Throws:: TwitterException

getUserTimeline

public java.util.List<Twitter.Status> getUserTimeline()
                                               throws TwitterException

Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user.

Throws:: TwitterException

getUserTimeline

public java.util.List<Twitter.Status> getUserTimeline(java.lang.String screenName)
                                               throws TwitterException

Returns the most recent statuses posted in the last 24 hours from the given user. Does not include new-style retweets.

This method will authenticate if it can (i.e. if the Twitter object has a username and password). Authentication is needed to see the posts of a private user.

Parameters:: screenName - Can be null. Specifies the screen name of the user for whom to return the user_timeline.
Throws:: TwitterException
See Also:: getUserTimelineWithRetweets(String)

getUserTimelineWithRetweets

public java.util.List<Twitter.Status> getUserTimelineWithRetweets(java.lang.String screenName)
                                                           throws TwitterException

Returns the most recent statuses posted in the last 24 hours from the given user. Unlike getUserTimeline(String), this includes new-style retweets.

This method will authenticate if it can (i.e. if the Twitter object has a username and password). Authentication is needed to see the posts of a private user.

Parameters:: screenName - Can be null. Specifies the screen name of the user for whom to return the user_timeline.
Throws:: TwitterException

setIncludeTweetEntities

public void setIncludeTweetEntities(boolean tweetEntities)

isFollower

public boolean isFollower(java.lang.String userB)

Is the authenticating user followed by userB?

Parameters:: userB - The screen name of a Twitter user.
Returns:: Whether or not the user is followed by userB.

isFollower

public boolean isFollower(java.lang.String followerScreenName,
                          java.lang.String followedScreenName)

Returns:: true if followerScreenName is following followedScreenName
Throws:: TwitterException.E403 - if one of the users has protected their updates and you don't have access. This can be counter-intuitive (and annoying) at times! Also throws E403 if one of the users has been suspended (we use the SuspendedUser exception sub-class for this).

isFollowing

public boolean isFollowing(java.lang.String userB)

Does the authenticating user follow userB?

Parameters:: userB - The screen name of a Twitter user.
Returns:: Whether or not the user follows userB.

isFollowing

public boolean isFollowing(Twitter.User user)

Convenience for isFollowing(String)

Parameters:: user -

isValidLogin

public boolean isValidLogin()

Are the login details used for authentication valid?

Returns:: true if OK, false if unset or invalid
See Also:: which returns user info

leaveNotifications

public Twitter.User leaveNotifications(java.lang.String screenName)

Switches off notifications for updates from the specified user who must already be a friend.

Parameters:: screenName - Stop getting notifications from this user, who must already be one of your friends.
Returns:: the specified user

notify

public Twitter.User notify(java.lang.String username)

Enables notifications for updates from the specified user who must already be a friend.

Parameters:: username - Get notifications from this user, who must already be one of your friends.
Returns:: the specified user

search

public java.util.List<Twitter.Status> search(java.lang.String searchTerm,
                                             Twitter.ICallback callback,
                                             int rpp)

Perform a search of Twitter.

Warning: the User objects returned by a search (as part of the Status objects) are dummy-users. The only information that is set is the user's screen-name and a profile image url. This reflects the current behaviour of the Twitter API. If you need more info, call show(String) with the screen name.

This supports maxResults and pagination. A language filter can be set via setLanguage(String) Location can be set via setSearchLocation(double, double, String) Other advanced search features can be done via the query string. E.g.
"from:winterstein" - tweets from user winterstein
"to:winterstein" - tweets start with @winterstein
"source:jtwitter" - originating from the application JTwitter - your query must also must contain at least one keyword parameter.
"filter:links" - tweets contain a link
"apples OR pears" - or ("apples pears" would give you apples and pears).

Parameters:: searchTerm - This can include several space-separated keywords, #tags and @username (for mentions), and use quotes for \"exact phrase\" searches.; callback - an object whose process() method will be called on each new page of results.; the - number of results to fetch per page
Returns:: search results - up to maxResults / rpp if maxResults is positive, or rpp if maxResults is negative.

retweet

public Twitter.Status retweet(Twitter.Status tweet)

Retweet (new-style) a tweet without any edits. You can also retweet by starting a status using the RT @username microformat. (this is an old-style retweet).

Parameters:: tweet - Note: you cannot retweet your own tweets.
Returns:: your retweet

search

public java.util.List<Twitter.Status> search(java.lang.String searchTerm)

Perform a search of Twitter. Wrapper for search(String, ICallback, int) with no callback and fetching 100 results.

Parameters:: searchTerm -
Returns:: search results - up to maxResults + rpp if maxResults is positive, or rpp if maxResults is negative.

searchUsers

public java.util.List<Twitter.User> searchUsers(java.lang.String searchTerm)

Warning: there is a bug within twitter.com which means that location-based searches are treated as OR. E.g. "John near:Scotland" will happily return "Andrew from Aberdeen" :(

Parameters:: searchTerm -
Returns:

setupTwitlonger

public void setupTwitlonger(java.lang.String twitlongerAppName,
                            java.lang.String twitlongerApiKey)

Set this to allow the use of twitlonger via updateLongStatus(String, long). To get an api-key for your app, contact twitlonger as described here: http://www.twitlonger.com/api

Parameters:: twitlongerAppName -; twitlongerApiKey -

setSearchLocation

public void setSearchLocation(double latitude,
                              double longitude,
                              java.lang.String radius)

Restricts search(String) to tweets by users located within a given radius of the given latitude/longitude.

The location of a tweet is preferentially taked from the Geotagging API, but will fall back to the Twitter profile.

Parameters:: latitude -; longitude -; radius - E.g. 3.5mi or 2km. Must be <2500km

setMyLocation

public void setMyLocation(double[] latitudeLongitude)

Set the location for your tweets.
Warning: geo-tagging parameters are ignored if geo_enabled for the user is false (this is the default setting for all users unless the user has enabled geolocation in their settings)!

Parameters:: latitudeLongitude - Can be null (which is the default), in which case your tweets will not carry location data.
The valid ranges for latitude is -90.0 to +90.0 (North is positive) inclusive. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive.
See Also:: which is completely separate.

sendMessage

public Twitter.Message sendMessage(java.lang.String recipient,
                                   java.lang.String text)
                            throws TwitterException

Sends a new direct message to the specified user from the authenticating user.

Parameters:: recipient - Required. The screen name of the recipient user.; text - Required. The text of your direct message. Keep it under 140 characters! This should *not* include the "d username" portion
Returns:: the sent message
Throws:: TwitterException.E403 - if the recipient is not following you. (you can \@mention anyone but you can only dm people who follow you).; TwitterException

setMaxResults

public void setMaxResults(int maxResults)

Parameters:: maxResults - if greater than zero, requests will attempt to fetch as many pages as are needed! -1 by default, in which case most methods return the first 20 statuses/messages. Zero is not allowed.
If setting a high figure, you should usually also set a sinceId or sinceDate to limit your Twitter usage. Otherwise you can easily exceed your rate limit.

setPageNumber

public void setPageNumber(java.lang.Integer pageNumber)

Parameters:: pageNumber - null (the default) returns the first page. Pages are indexed from 1. This is used once only! Then it is reset to null

setSinceDate

public void setSinceDate(java.util.Date sinceDate)

Date based filter on statuses and messages. This is done client-side as Twitter have - for their own inscrutable reasons - pulled support for this feature.

If using this, you probably also want to increase setMaxResults(int) - otherwise you get at most 20, and possibly less (since the filtering is done client side).

Parameters:: sinceDate -

setUntilDate

public void setUntilDate(java.util.Date untilDate)

Parameters:: untilDate - the untilDate to set

getUntilDate

public java.util.Date getUntilDate()

TODO document this please - DBW

Returns:: the untilDate

setSinceId

public void setSinceId(java.lang.Long statusId)

Narrows the returned results to just those statuses created after the specified status id. This will be used until it is set to null. Default is null.

If using this, you probably also want to increase setMaxResults(int) (otherwise you just get the most recent 20).

Parameters:: statusId -

setSource

public void setSource(java.lang.String sourceApp)

Set the source application. This will be mentioned on Twitter alongside status updates (with a small label saying source: myapp). In order for this to work, you must first register your app with Twitter and get a source name from them! You must also use OAuth to connect.

Parameters:: sourceApp - jtwitterlib by default. Set to null for no source.

setStatus

public Twitter.Status setStatus(java.lang.String statusText)
                         throws TwitterException

Sets the authenticating user's status.

Identical to updateStatus(String), but with a Java-style name (updateStatus is the Twitter API name for this method).

Parameters:: statusText - The text of your status update. Must not be more than 160 characters and should not be more than 140 characters to ensure optimal display.
Returns:: The posted status when successful.
Throws:: TwitterException

show

public Twitter.User show(java.lang.String screenName)
                  throws TwitterException

Returns information of a given user, specified by screen name.

Parameters:: screenName - The screen name of a user.
Throws:: exception - if the user does not exist - or has been terminated (as happens to spam bots).; TwitterException
See Also:: show(long)

show

public Twitter.User show(long userId)

Returns information of a given user, specified by user-id.

Parameters:: userId - The user-id of a user.
Throws:: exception - if the user does not exist - or has been terminated (as happens to spam bots).

bulkShow

public java.util.List<Twitter.User> bulkShow(java.util.List<java.lang.String> screenNames)

Lookup user info. This is done in batches of 100. Users can look up at most 1000 users in an hour.

Parameters:: screenNames -
Returns:: user objects for screenNames. Warning 1: This may be less than the full set if Twitter returns an error part-way through (e.g. you hit your rate limit). Warning 2: the ordering may be different from the screenNames parameter
See Also:: bulkShowById(List)

bulkShowById

public java.util.List<Twitter.User> bulkShowById(java.util.List<java.lang.Long> userIds)

Lookup user info. Same as bulkShow(List), but works with Twitter user-ID numbers.

Parameters:: userIds -

getUser

public Twitter.User getUser(java.lang.String screenName)

Synonym for show(String). show is the Twitter API name, getUser feels more Java-like.

Parameters:: screenName - The screen name of a user.
Returns:: the user info

getUser

public Twitter.User getUser(long userId)

Synonym for show(long). show is the Twitter API name, getUser feels more Java-like.

Parameters:: userId - The user-id of a user.
Returns:: the user info
See Also:: getUser(String)

splitMessage

public java.util.List<java.lang.String> splitMessage(java.lang.String longStatus)

Split a long message up into shorter chunks suitable for use with setStatus(String) or sendMessage(String, String).

Parameters:: longStatus -
Returns:: longStatus broken into a list of max 140 char strings

stopFollowing

public Twitter.User stopFollowing(java.lang.String username)

Destroy: Discontinues friendship with the user specified in the ID parameter as the authenticating user.

Parameters:: username - The screen name of the user with whom to discontinue friendship.
Returns:: the un-friended user (if they were a friend), or null if the method fails because the specified user was not a friend.

stopFollowing

public void stopFollowing(Twitter.User user)

Convenience for stopFollowing(String)

Parameters:: user -

updateStatus

public Twitter.Status updateStatus(java.lang.String statusText)

Updates the authenticating user's status.

Parameters:: statusText - The text of your status update. Must not be more than 160 characters and should not be more than 140 characters to ensure optimal display.
Returns:: The posted status when successful.

updateStatus

public Twitter.Status updateStatus(java.lang.String statusText,
                                   long inReplyToStatusId)
                            throws TwitterException

Updates the authenticating user's status and marks it as a reply to the tweet with the given ID.

Parameters:: statusText - The text of your status update. Must not be more than 160 characters and should not be more than 140 characters to ensure optimal display.; inReplyToStatusId - The ID of the tweet that this tweet is in response to. The statusText must contain the username (with an "@" prefix) of the owner of the tweet being replied to for for Twitter to agree to mark the tweet as a reply. 0 or less to leave this unset.
Returns:: The posted status when successful.
Warning: the microformat for direct messages is supported. BUT: the return value from this method will be null, and not the direct message. Other microformats (such as follow) may result in an exception being thrown.
Throws:: TwitterException - if something goes wrong. There is a rare (but not rare enough) bug whereby Twitter occasionally returns a success code but the wrong tweet. If this happens, the update may or may not have worked - wait a bit & check.

isTwitlongerSetup

public boolean isTwitlongerSetup()

Returns:: true if setupTwitlonger(String, String) has been used to provide twitlonger.com details.
See Also:: updateLongStatus(String, long)

updateLongStatus

public Twitter.Status updateLongStatus(java.lang.String message,
                                       long inReplyToStatusId)

Use twitlonger.com to post a lengthy tweet. See twitlonger.com for more details on their service.

Note: You need to have called setupTwitlonger(String, String) before calling this.

Parameters:: message -; inReplyToStatusId -
Returns:: A Twitter status using a truncated message with a link to twitlonger.com
See Also:: setupTwitlonger(String, String)

getLongStatus

public java.lang.String getLongStatus(Twitter.Status truncatedStatus)

Parameters:: truncatedStatus - If this is a twitlonger.com truncated status, then call twitlonger to fetch the full text.
Returns:: the full status message. If this is not a twitlonger status, this will just return the status text as-is.
See Also:: updateLongStatus(String, long)

userExists

public boolean userExists(java.lang.String screenName)

Does a user with the specified name or id exist?

Parameters:: screenName - The screen name or user id of the suspected user.
Returns:: False if the user doesn't exist or has been suspended, true otherwise.

setLanguage

public void setLanguage(java.lang.String language)

Set a language filter for search results. Note: This only applies to search results.

Parameters:: language - ISO code for language. Can be null for all languages.
Note: there are multiple different ISO codes! Twitter supports ISO 639-1. http://en.wikipedia.org/wiki/ISO_639-1

getTrends

public java.util.List<java.lang.String> getTrends()

Returns:: the latest trending topics on Twitter

getHttpClient

public Twitter.IHttpClient getHttpClient()

Provides access to the Twitter.IHttpClient which manages the low-level authentication, posts and gets.

getMaxResults

public int getMaxResults()

Provides support for fetching many pages. -1 indicates "give me as much as Twitter will let me have."

getRetweetsByMe

public java.util.List<Twitter.Status> getRetweetsByMe()

Returns:: retweets that you have made using "new-style" retweets rather than the RT microfromat. These are your tweets, i.e. they begin "RT @whoever: ". You can get the original tweet via Twitter.Status.getOriginal()

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

winterwell.jtwitter Class Twitter

Copyright and License

Change List

version

Twitter

Twitter

Twitter

setAPIRootUrl

getDate

getUser

jsonGet

main

setCount

befriend

breakFriendship

destroyStatus

destroyStatus

destroy

follow

follow

getDirectMessages

getDirectMessagesSent

getFavorites

setFavorite

getFavorites

getFeatured

getFollowerIDs

getFollowerIDs

getFollowers

getFollowers

getFriendIDs

getFriendIDs

getFriends

getFriends

getFriendsTimeline

getHomeTimeline

getScreenName

getPublicTimeline

getRateLimitStatus

getReplies

getRetweetsOfMe

getLists

getLists

getRetweets

getRetweeters

getStatus

getStatus

getStatus

getUserTimeline

getUserTimeline

getUserTimelineWithRetweets

setIncludeTweetEntities

isFollower

isFollower

isFollowing

isFollowing

isValidLogin

leaveNotifications

notify

search

retweet

search

searchUsers

setupTwitlonger

setSearchLocation

setMyLocation

sendMessage

setMaxResults

setPageNumber

setSinceDate

setUntilDate

getUntilDate

setSinceId

setSource

setStatus

show

show

bulkShow

bulkShowById

getUser

winterwell.jtwitter
Class Twitter