Twitter

Overview

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

All Implemented Interfaces:: java.io.Serializable

public class Twitter
extends java.lang.Object
implements java.io.Serializable
extends java.lang.Object
implements java.io.Serializable

Java wrapper for the Twitter API version "2.4"

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 jby 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 http://dev.twitter.com/doc 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 available via this class (Twitter), except for list support (in TwitterList - though getLists() is here) and some profile/account settings (in Twitter_Account).
This class is NOT thread safe. If you're using multiple threads, it is best to create separate Twitter objects (which is fine).

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

See Also:: Serialized Form

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 `Message`s and `Status`es.
`static class`	`Twitter.KEntityType`
`static class`	`Twitter.KRequestType` The different types of API request.
`static class`	`Twitter.TweetEntity` A special slice of text within a tweet.

Field Summary
`static boolean`	`CASE_SENSITIVE_SCREENNAMES` This rather dangerous global toggle switches off lower-casing on Twitter screen-names.
`static int`	`LINK_LENGTH` The length of a url after t.co shortening.
`static long`	`PHOTO_SIZE_LIMIT`
`static java.lang.String`	`SEARCH_MIXED`
`static java.lang.String`	`SEARCH_POPULAR`
`static java.lang.String`	`SEARCH_RECENT`
`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.
`Twitter(Twitter jtwit)` Copy constructor.

Method Summary
`Twitter_Account`	`account()` API methods relating to your account.
`User`	`befriend(java.lang.String username)` Deprecated. Use `follow(String)` instead, which is equivalent.
`User`	`breakFriendship(java.lang.String username)` Deprecated. Please use `stopFollowing(String)` instead.
`java.util.List<User>`	`bulkShow(java.util.List<java.lang.String> screenNames)` Deprecated. Use `Twitter_Users.show(List)` instead
`java.util.List<User>`	`bulkShowById(java.util.List<? extends java.lang.Number> userIds)` Deprecated. Use `#showById(List)` instead
`void`	`destroy(Twitter.ITweet tweet)` Deletes the given Status or Message.
`void`	`destroyMessage(java.lang.Number id)` Deletes the direct message specified by the ID.
`void`	`destroyStatus(java.lang.Number id)` Deletes the status specified by the required ID parameter.
`void`	`destroyStatus(Status status)` Deprecated. in favour of `destroy(ITweet)`. This method will be removed by the end of 2010.
`User`	`follow(java.lang.String username)` Deprecated.
`User`	`follow(User user)` Deprecated.
`Twitter_Geo`	`geo()` Geo-location API methods.
`static java.util.Map<java.lang.String,java.lang.Double>`	`getAPIStatus()` How is the Twitter API today? See `https://dev.twitter.com/status` for more information.
`java.util.List<Message>`	`getDirectMessages()` Returns a list of the direct messages sent to the authenticating user.
`java.util.List<Message>`	`getDirectMessagesSent()` Returns a list of the direct messages sent by the authenticating user.
`java.util.List<Status>`	`getFavorites()` The most recent 20 favourite tweets.
`java.util.List<Status>`	`getFavorites(java.lang.String screenName)` The most recent 20 favourite tweets for the given user.
`java.util.List<java.lang.Number>`	`getFollowerIDs()` Deprecated.
`java.util.List<java.lang.Number>`	`getFollowerIDs(java.lang.String screenName)` Deprecated.
`java.util.List<User>`	`getFollowers()` Deprecated.
`java.util.List<User>`	`getFollowers(java.lang.String username)` Deprecated.
`java.util.List<java.lang.Number>`	`getFriendIDs()` Deprecated.
`java.util.List<java.lang.Number>`	`getFriendIDs(java.lang.String screenName)` Deprecated.
`java.util.List<User>`	`getFriends()` Deprecated.
`java.util.List<User>`	`getFriends(java.lang.String username)` Deprecated.
`java.util.List<Status>`	`getFriendsTimeline()` Deprecated. Replaced by `getHomeTimeline()`
`java.util.List<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.util.List<TwitterList>`	`getListsAll(User user)` Returns all lists the authenticating or specified user subscribes to, including their own.
`java.util.List<TwitterList>`	`getListsContaining(java.lang.String screenName, boolean filterToOwned)`
`java.util.List<TwitterList>`	`getListsContainingMe()` Convenience for `getListsContaining(String, boolean)`.
`java.lang.String`	`getLongStatus(Status truncatedStatus)`
`int`	`getMaxResults()` Provides support for fetching many pages.
`java.util.List<Status>`	`getMentions()` Returns the 20 most recent replies/mentions (status updates with
`java.util.List<Status>`	`getPublicTimeline()` Returns the 20 most recent statuses from non-protected users who have set a custom user icon.
`RateLimit`	`getRateLimit(Twitter.KRequestType reqType)` What is the current rate limit status? Do we need to throttle back our usage? This is the cached info from the last call of that type.
`int`	`getRateLimitStatus()` How many normal rate limit calls do you have left? This calls Twitter, which makes it slower than `getRateLimit(KRequestType)` but it's up-to-date and safe against threads and other-programs using the same allowance.
`java.util.List<Twitter.ITweet>`	`getRelated(Twitter.ITweet tweet)` Deprecated.
`java.util.List<Status>`	`getReplies()` Deprecated. Use #getMentions() for preference
`java.util.List<User>`	`getRetweeters(Status tweet)` Show users who (new-style) retweeted the given tweet.
`java.util.List<Status>`	`getRetweets(Status tweet)`
`java.util.List<Status>`	`getRetweetsByMe()`
`java.util.List<Status>`	`getRetweetsOfMe()`
`java.lang.String`	`getScreenName()`
`User`	`getSelf()`
`Status`	`getStatus()`
`Status`	`getStatus(java.lang.Number id)` Returns a single status, specified by the id parameter below.
`Status`	`getStatus(java.lang.String username)`
`java.util.List<java.lang.String>`	`getTrends()`
`java.util.List<java.lang.String>`	`getTrends(java.lang.Number woeid)`
`java.util.Date`	`getUntilDate()`
`User`	`getUser(long userId)` Deprecated.
`User`	`getUser(java.lang.String screenName)` Deprecated.
`static User`	`getUser(java.lang.String screenName, java.util.List<User> users)` Convenience method: Finds a user with the given screen-name from the list.
`java.util.List<Status>`	`getUserTimeline()` Returns the most recent statuses from the authenticating user.
`java.util.List<Status>`	`getUserTimeline(java.lang.Long userId)` Equivalent to `getUserTimeline(String)`, but takes a numeric user-id instead of a screen-name.
`java.util.List<Status>`	`getUserTimeline(java.lang.String screenName)` Returns the most recent statuses from the given user.
`java.util.List<Status>`	`getUserTimelineWithRetweets(java.lang.String screenName)` Deprecated. Use `setIncludeRTs(boolean)` instead to control retweet behaviour. Returns the most recent statuses posted by the given user. Unlike `getUserTimeline(String)`, this includes new-style retweets. This will return 20 by default, though `setMaxResults(int)` can be used to fetch multiple pages. There is a cap of 3200 tweets - this is the farthest back you can go down a user timeline! 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.
`boolean`	`isFollower(java.lang.String userB)` Deprecated.
`boolean`	`isFollower(java.lang.String followerScreenName, java.lang.String followedScreenName)` Deprecated.
`boolean`	`isFollowing(java.lang.String userB)` Deprecated.
`boolean`	`isFollowing(User user)` Deprecated.
`boolean`	`isRateLimited(Twitter.KRequestType reqType, int minCalls)`
`boolean`	`isTwitlongerSetup()`
`boolean`	`isValidLogin()` Are the login details used for authentication valid?
`static void`	`main(java.lang.String[] args)`
`void`	`reportSpam(java.lang.String screenName)` Report a user for being a spammer.
`Status`	`retweet(Status tweet)` Retweet (new-style) a tweet without any edits.
`java.util.List<Status>`	`search(java.lang.String searchTerm)` Perform a search of Twitter.
`java.util.List<Status>`	`search(java.lang.String searchTerm, Twitter.ICallback callback, int rpp)` Perform a search of Twitter.
`java.util.List<User>`	`searchUsers(java.lang.String searchTerm)` Deprecated.
`Message`	`sendMessage(java.lang.String recipient, java.lang.String text)` Sends a new direct message (DM) 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(Status status, boolean isFavorite)`
`void`	`setIncludeRTs(boolean includeRTs)` true by default.
`void`	`setIncludeTweetEntities(boolean tweetEntities)` Note: does NOT work for search() methods (not supported by Twitter).
`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`	`setSearchResultType(java.lang.String resultType)` Optional.
`void`	`setSinceDate(java.util.Date sinceDate)` Deprecated.
`void`	`setSinceId(java.lang.Number 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.
`Status`	`setStatus(java.lang.String statusText)` Sets the authenticating user's status.
`void`	`setUntilDate(java.util.Date untilDate)` Deprecated.
`void`	`setUntilId(java.lang.Number untilId)` If set, return results older than this.
`void`	`setupTwitlonger(java.lang.String twitlongerAppName, java.lang.String twitlongerApiKey)` Set this to allow the use of twitlonger via `#updateLongStatus(String, long)`.
`User`	`show(java.lang.Number userId)` Deprecated.
`User`	`show(java.lang.String screenName)` Deprecated.
`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)`.
`User`	`stopFollowing(java.lang.String username)` Deprecated.
`User`	`stopFollowing(User user)` Deprecated.
`java.lang.String`	`toString()`
`void`	`updateConfiguration()` Update info on Twitter's configuration -- such as shortened url lengths.
`Status`	`updateLongStatus(java.lang.String message, java.lang.Number inReplyToStatusId)` Use twitlonger.com to post a lengthy tweet.
`Status`	`updateStatus(java.lang.String statusText)` Updates the authenticating user's status.
`Status`	`updateStatus(java.lang.String statusText, java.lang.Number inReplyToStatusId)` Updates the authenticating user's status and marks it as a reply to the tweet with the given ID.
`Twitter_Users`	`users()` User and social-network related API methods.

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

Field Detail

CASE_SENSITIVE_SCREENNAMES

public static boolean CASE_SENSITIVE_SCREENNAMES

This rather dangerous global toggle switches off lower-casing on Twitter screen-names.

Screen-names are case insensitive as far as Twitter is concerned. However you might want to preserve the case people use for display purposes.

false by default.

LINK_LENGTH

public static int LINK_LENGTH

The length of a url after t.co shortening. Currently 20 characters.

Use updateConfiguration() if you want to get the latest settings from Twitter.

PHOTO_SIZE_LIMIT

public static long PHOTO_SIZE_LIMIT

SEARCH_MIXED

public static final java.lang.String SEARCH_MIXED

See Also:: Constant Field Values

SEARCH_POPULAR

public static final java.lang.String SEARCH_POPULAR

See Also:: Constant Field Values

SEARCH_RECENT

public static final java.lang.String SEARCH_RECENT

See Also:: Constant Field Values

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 -
See Also:: OAuthSignpostClient

Twitter

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

Deprecated.

WARNING: Twitter no longer supports name/password basic authentication. This constructor is only for non-Twitter sites, such as identi.ca.

Parameters:: screenName - The name of the user. Only used by some methods.; password - The password of the user.

Twitter

public Twitter(Twitter jtwit)

Copy constructor. Use this to pass cloned Twitter objects for multi-threaded work.

Parameters:: jtwit -

Method Detail

getRelated

@Deprecated
public java.util.List<Twitter.ITweet> getRelated(Twitter.ITweet tweet)

Deprecated.

TODO

getAPIStatus

public static java.util.Map<java.lang.String,java.lang.Double> getAPIStatus()
                                                                     throws java.lang.Exception

How is the Twitter API today? See https://dev.twitter.com/status for more information.

Returns:: map of {method: %uptime in the last 24 hours}. An empty map indicates this method itself failed!
Throws:: java.lang.Exception - This method is not officially supported! As such, it could break at some future point.

getUser

public static User getUser(java.lang.String screenName,
                           java.util.List<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.

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.

account

public Twitter_Account account()

API methods relating to your account.

befriend

@Deprecated
public 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 User breakFriendship(java.lang.String username)

Deprecated. Please use stopFollowing(String) instead.

Equivalent to stopFollowing(String).

bulkShow

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

Deprecated. Use Twitter_Users.show(List) instead

bulkShowById

public java.util.List<User> bulkShowById(java.util.List<? extends java.lang.Number> userIds)

Deprecated. Use #showById(List) instead

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

destroyMessage

public void destroyMessage(java.lang.Number id)

Deletes the direct message specified by the ID. The authenticating user must be the author of the specified status.

See Also:: destroy(ITweet)

destroyStatus

public void destroyStatus(java.lang.Number 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(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)

follow

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

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.follow(String)

toString

public java.lang.String toString()

Overrides:: toString in class java.lang.Object

follow

@Deprecated
public User follow(User user)

Deprecated.

See Also:: Twitter_Users.follow(User)

geo

public Twitter_Geo geo()

Geo-location API methods.

getDirectMessages

public java.util.List<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<Message> getDirectMessagesSent()

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

getFavorites

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

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

getFavorites

public java.util.List<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.

getFollowerIDs

@Deprecated
public java.util.List<java.lang.Number> getFollowerIDs()
                                                throws TwitterException

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFollowerIDs()

getFollowerIDs

@Deprecated
public java.util.List<java.lang.Number> getFollowerIDs(java.lang.String screenName)
                                                throws TwitterException

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFollowerIDs(String)

getFollowers

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

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFollowers()

getFollowers

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

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFollowers(String)

getFriendIDs

@Deprecated
public java.util.List<java.lang.Number> getFriendIDs()
                                              throws TwitterException

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFriendIDs()

getFriendIDs

@Deprecated
public java.util.List<java.lang.Number> getFriendIDs(java.lang.String screenName)
                                              throws TwitterException

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFriendIDs(String)

getFriends

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

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users.getFriends()

getFriends

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

Deprecated.

Throws:: TwitterException
See Also:: Twitter_Users#getFriendss(String)

getFriendsTimeline

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

Deprecated. Replaced by getHomeTimeline()

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

getHttpClient

public Twitter.IHttpClient getHttpClient()

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

getLists

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

Returns:: your lists, ie. the one's you made.

getListsAll

public java.util.List<TwitterList> getListsAll(User user)

Returns all lists the authenticating or specified user subscribes to, including their own.

Parameters:: user - can be null for the authenticating user.
See Also:: getLists(String)

getLists

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

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

getListsContaining

public java.util.List<TwitterList> getListsContaining(java.lang.String screenName,
                                                      boolean filterToOwned)

Parameters:: screenName -; filterToOwned - If true, only return lists which the user owns.
Returns:: lists of which screenName is a member. NOTE: currently limited to a maximum of 20 lists!

getListsContainingMe

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

Convenience for getListsContaining(String, boolean).

Returns:: lists that you are a member of. Warning: currently limited to a maximum of 20 results.

getLongStatus

public java.lang.String getLongStatus(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)

getMaxResults

public int getMaxResults()

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

getMentions

public java.util.List<Status> getMentions()

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

getPublicTimeline

public java.util.List<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

getRateLimit

public RateLimit getRateLimit(Twitter.KRequestType reqType)

What is the current rate limit status? Do we need to throttle back our usage? This is the cached info from the last call of that type.

Note: The RateLimit object is created using cached info from a previous Twitter call. So this method is quick (it doesn't require a fresh call to Twitter), but the RateLimit object isn't available until after you make a call of the right type to Twitter.

Status: Headin towards stable, but still a bit experimental.

Parameters:: reqType - Different methods have separate rate limits.
Returns:: the last rate limit advice received, or null if unknown.
See Also:: getRateLimitStatus()

getRateLimitStatus

public int getRateLimitStatus()

How many normal rate limit calls do you have left? This calls Twitter, which makes it slower than getRateLimit(KRequestType) but it's up-to-date and safe against threads and other-programs using the same allowance.

This may update getRateLimit(KRequestType) for NORMAL requests, but sadly it doesn't fetch rate-limit info on other request types.

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 zero or 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.
See Also:: getRateLimit(KRequestType)

getReplies

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

Deprecated. Use #getMentions() for preference

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

Throws:: TwitterException

getRetweeters

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

Show users who (new-style) retweeted the given tweet. Can use count (up to 100) and page. This does not include old-style retweeters!

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

getRetweets

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

Returns:: Retweets of this tweet. This attempts to cover new-style and old-style "manual" retweets. It does so by making retweet call and a search call. It will miss edited retweets though.

getRetweetsByMe

public java.util.List<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 Status.getOriginal()

getRetweetsOfMe

public java.util.List<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.

getScreenName

public java.lang.String getScreenName()

Returns:: Login name of the authenticating user, or null if not set.
Will call Twitter to find out if null but oauth is set.
See Also:: getSelf()

getSelf

public User getSelf()

Returns:: you, or null if this is an anonymous Twitter object.
This will cache the result if it makes an API call.

getStatus

public 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 Status getStatus(java.lang.Number 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 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

getTrends

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

Returns:: the latest global trending topics on Twitter

getTrends

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

Parameters:: a - Yahoo Where-on-Earth ID. c.f. http://developer.yahoo.com/geo/geoplanet/
Returns:: the latest regional trending topics on Twitter
See Also:: Twitter_Geo.getTrendRegions()

getUntilDate

public java.util.Date getUntilDate()

Returns:: the untilDate

getUser

@Deprecated
public User getUser(long userId)

Deprecated.

See Also:: Twitter_Users.getUser(long)

getUser

@Deprecated
public User getUser(java.lang.String screenName)

Deprecated.

See Also:: Twitter_Users.getUser(String)

getUserTimeline

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

Returns the most recent statuses from the authenticating user. 20 by default.

Throws:: TwitterException

getUserTimeline

public java.util.List<Status> getUserTimeline(java.lang.Long userId)
                                       throws TwitterException

Equivalent to getUserTimeline(String), but takes a numeric user-id instead of a screen-name.

Parameters:: userId -
Returns:: tweets by userId
Throws:: TwitterException

getUserTimeline

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

Returns the most recent statuses from the given user.

This will return 20 results by default, though setMaxResults(int) can be used to fetch multiple pages. Note that if you exclude new-style retweets (via setIncludeRTs(boolean)) then this can return less than 20 results -- it can even return none if the latest 20 are all retweets.

There is a cap of 3200 tweets - this is the farthest back you can go down a user timeline!

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.E401 - if the user has protected their tweets, and you do not have access.; TwitterException.SuspendedUser - if the user has been suspended; TwitterException

getUserTimelineWithRetweets

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

Deprecated. Use setIncludeRTs(boolean) instead to control retweet behaviour. Returns the most recent statuses posted by the given user. Unlike getUserTimeline(String), this includes new-style retweets.
This will return 20 by default, though setMaxResults(int) can be used to fetch multiple pages. There is a cap of 3200 tweets - this is the farthest back you can go down a user timeline!

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

isFollower

@Deprecated
public boolean isFollower(java.lang.String userB)

Deprecated.

See Also:: Twitter_Users.isFollower(String)

isFollower

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

Deprecated.

See Also:: Twitter_Users.isFollower(String, String)

isFollowing

@Deprecated
public boolean isFollowing(java.lang.String userB)

Deprecated.

See Also:: Twitter_Users.isFollowing(String)

isFollowing

@Deprecated
public boolean isFollowing(User user)

Deprecated.

See Also:: Twitter_Users.isFollowing(User)

isRateLimited

public boolean isRateLimited(Twitter.KRequestType reqType,
                             int minCalls)

Parameters:: type -; minCalls - Standard value = 1. The minimum number of calls which should be available.
Returns:: true if this is currently rate-limited, & should not be used for a while. false = OK
See Also:: for more info, for guaranteed up-to-date info

isTwitlongerSetup

public boolean isTwitlongerSetup()

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

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

reportSpam

public void reportSpam(java.lang.String screenName)

Report a user for being a spammer.

Parameters:: screenName -

retweet

public Status retweet(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<Status> search(java.lang.String searchTerm)

Perform a search of Twitter. Convenience wrapper for search(String, ICallback, int) with no callback and fetching one pages worth of results.

search

public java.util.List<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.; rpp - results per page. 100 is the default
Returns:: search results - up to maxResults if maxResults is positive, or rpp if maxResults is negative/zero. See setMaxResults(int) to use > 100.

searchUsers

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

Deprecated.

See Also:: Twitter_Users.searchUsers(String)

sendMessage

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

Sends a new direct message (DM) to the specified user from the authenticating user. This is a private message!

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

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.

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.

setFavorite

public void setFavorite(Status status,
                        boolean isFavorite)

setIncludeRTs

public void setIncludeRTs(boolean includeRTs)

true by default. If true, lists of tweets will include new-style retweets. If false, they won't (execpt for the retweet-specific calls).

Parameters:: includeRTs -

setIncludeTweetEntities

public void setIncludeTweetEntities(boolean tweetEntities)

Note: does NOT work for search() methods (not supported by Twitter).

Parameters:: tweetEntities - Set to true to enable Status#getTweetEntities(KEntityType), false if you don't care. Default is true.

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

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.

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.

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

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 preferably taken 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

setSearchResultType

public void setSearchResultType(java.lang.String resultType)

Optional. Specifies what type of search results you would prefer to receive. The current default is "mixed." Valid values:
SEARCH_MIXED: Include both popular and real time results in the response.
SEARCH_RECENT: return only the most recent results in the response
SEARCH_POPULAR: return only the most popular results in the response.

Parameters:: resultType -

setSinceDate

@Deprecated
public void setSinceDate(java.util.Date sinceDate)

Deprecated.

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. Use setSinceId(Number) for preference.

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 -
See Also:: setSinceId(Number)

setSinceId

public void setSinceId(java.lang.Number 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 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

setUntilDate

@Deprecated
public void setUntilDate(java.util.Date untilDate)

Deprecated.

Parameters:: untilDate - the untilDate to set. This is NOT properly supported. It operates by post filtering results client-side.
See Also:: which is better

setUntilId

public void setUntilId(java.lang.Number untilId)

If set, return results older than this.

Parameters:: untilId - aka max_id

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 -

show

@Deprecated
public User show(java.lang.Number userId)

Deprecated.

See Also:: Twitter_Users.show(Number)

show

@Deprecated
public User show(java.lang.String screenName)
          throws TwitterException,
                 TwitterException.SuspendedUser

Deprecated.

Throws:: TwitterException; TwitterException.SuspendedUser
See Also:: Twitter_Users.show(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

@Deprecated
public User stopFollowing(java.lang.String username)

Deprecated.

See Also:: Twitter_Users.stopFollowing(String)

stopFollowing

@Deprecated
public User stopFollowing(User user)

Deprecated.

See Also:: Twitter_Users.stopFollowing(User)

updateConfiguration

public void updateConfiguration()

Update info on Twitter's configuration -- such as shortened url lengths.

updateLongStatus

public Status updateLongStatus(java.lang.String message,
                               java.lang.Number 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 - Can be null if this isn't a reply
Returns:: A Twitter status using a truncated message with a link to twitlonger.com
See Also:: setupTwitlonger(String, String)

updateStatus

public 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 Status updateStatus(java.lang.String statusText,
                           java.lang.Number 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. null 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.

users

public Twitter_Users users()

User and social-network related API methods.

Overview

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

CASE_SENSITIVE_SCREENNAMES

LINK_LENGTH

PHOTO_SIZE_LIMIT

SEARCH_MIXED

SEARCH_POPULAR

SEARCH_RECENT

version

Twitter

Twitter

Twitter

Twitter

getRelated

getAPIStatus

getUser

main

account

befriend

breakFriendship

bulkShow

bulkShowById

destroy

destroyMessage

destroyStatus

destroyStatus

follow

toString

follow

geo

getDirectMessages

getDirectMessagesSent

getFavorites

getFavorites

getFollowerIDs

getFollowerIDs

getFollowers

getFollowers

getFriendIDs

getFriendIDs

getFriends

getFriends

getFriendsTimeline

getHomeTimeline

getHttpClient

getLists

getListsAll

getLists

getListsContaining

getListsContainingMe

getLongStatus

getMaxResults

getMentions

getPublicTimeline

getRateLimit

getRateLimitStatus

getReplies

getRetweeters

getRetweets

getRetweetsByMe

getRetweetsOfMe

getScreenName

getSelf

getStatus

getStatus

getStatus

getTrends

getTrends

getUntilDate

getUser

getUser

getUserTimeline

getUserTimeline

getUserTimeline

getUserTimelineWithRetweets

isFollower

isFollower

isFollowing

isFollowing

winterwell.jtwitter
Class Twitter