winterwell.jtwitter
Class Twitter

java.lang.Object
  winterwell.jtwitter.Twitter

public class Twitter
extends java.lang.Object

Java wrapper for the Twitter API version 1.4.3

Example usage:

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

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. I would like to improve error-handling, and welcome suggestions on cases where more informative exceptions would be helpful.

Copyright and License

This code is copyright (c) Winterwell Associates 2008/2009 and (c) ThinkTank 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: http://www.winterwell.com/software/changelist.txt

Author:

Daniel Winterstein

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. allows for OAuth to be used instead.
static interface	Twitter.ITweet This gives common access to features that are common to both Twitter.Messages and Twitter.Statuses.
static class	Twitter.Message A Twitter direct message.
static class	Twitter.Status A Twitter status post. .toString() returns the status text.
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)
Java wrapper for the Twitter API.

Twitter(java.lang.String name, Twitter.IHttpClient client)
Java wrapper for the Twitter API.

Method Summary

java.util.List<Twitter.User>	bulkShow(java.util.List<java.lang.String> screenNames) Lookup user info.
void	destroyStatus(long id) Destroys the status specified by the required ID parameter.
void	destroyStatus(Twitter.Status status) Destroys the given status.
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.
int	getMaxResults() Provides support for fetching many pages. -1 indicates "give me as much as Twitter will let me have."
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.Status>	getRetweets(Twitter.Status tweet)
java.util.List<Twitter.Status>	getRetweetsOfMe() TODO
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). show is the Twitter API name, getUser feels more Java-like.
Twitter.User	getUser(java.lang.String screenName) Synonym for show(String). show is the Twitter API name, getUser feels more Java-like.
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.
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	isValidLogin() Are the login details used for authentication valid?
protected static java.lang.String	jsonGet(java.lang.String key, 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 a tweet without any edits.
java.util.List<Twitter.Status>	search(java.lang.String searchTerm) Wrapper for search(String, ICallback, int) with no callback and fetching 100 results.
java.util.List<Twitter.Status>	search(java.lang.String searchTerm, Twitter.ICallback callback, int rpp) Perform a search of Twitter.
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	setLanguage(java.lang.String language) Set a language filter for search results.
void	setMaxResults(int maxResults)
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)
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	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.

Twitter

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

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.

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 -

Method Detail

bulkShow

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

Lookup user info. This is done in batches of 20. 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

destroyStatus

public void destroyStatus(long id)
                   throws TwitterException

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

Throws:

TwitterException

destroyStatus

public void destroyStatus(Twitter.Status status)
                   throws TwitterException

Destroys the given status. Equivalent to #destroyStatus(int). 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 -

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

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

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

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

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

getRetweets

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

Returns:

retweets of this tweet, based on a word search

getRetweetsOfMe

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

TODO

Returns:

retweets of your tweets

getScreenName

public java.lang.String getScreenName()

Returns:

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

getStatus

public Twitter.Status getStatus()
                         throws TwitterException

Returns:

The current status of the user. null if unset (ie if they have never tweeted)

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, as a normal String.

Throws:

TwitterException

getTrends

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

Returns:

the latest trending topics on Twitter

getUntilDate

public java.util.Date getUntilDate()

TODO document this please - DBW

Returns:

the untilDate

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)

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

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.

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.

since - Can be null. Narrows the returned results to just those statuses created after the specified date.

Throws:

TwitterException

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!

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:

jsonGet

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

Helper method to deal with JSON-in-Java weirdness

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

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.

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

retweet

public Twitter.Status retweet(Twitter.Status tweet)

Retweet a tweet without any edits. You can also retweet by starting a status using the RT

Parameters:

tweet - This must not be one of your own or Twitter will ignore it.

Returns:

your retweet

search

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

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

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) TODO parameters: geocode: Optional. Returns tweets by users located within a given radius of the given latitude/longitude, where the user's location is taken from their Twitter profile. The parameter value is specified by "latitude,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.

Parameters:

searchTerm -

Returns:

search results - up to maxResults + rpp if maxResults is positive, or rpp if maxResults is negative.

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) TODO parameters: geocode: Optional. Returns tweets by users located within a given radius of the given latitude/longitude, where the user's location is taken from their Twitter profile. The parameter value is specified by "latitude,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.

Parameters:

searchTerm -

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.

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

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!

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(Twitter.Status status,
                        boolean isFavorite)

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.

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.

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

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

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 -

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

setUntilDate

public void setUntilDate(java.util.Date untilDate)

Parameters:

untilDate - the untilDate to set

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

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)

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.

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.