winterwell.jtwitter
Class Twitter_Users

java.lang.Object
  winterwell.jtwitter.Twitter_Users

public class Twitter_Users
extends java.lang.Object

API calls relating to users and relationships (the social network). Use Twitter.users() to get one of these objects.

Conceptually, this is an extension of Twitter. The methods are here because Twitter was getting crowded.

Method Summary

User	block(java.lang.String screenName) blocks/create: Blocks screenName from following the authenticating user.
User	follow(java.lang.String username) Start following a user.
User	follow(User user) Convenience for follow(String)
java.util.List<java.lang.Number>	getBlockedIds()
java.util.List<User>	getFeatured() Returns a list of the users currently featured on the site with their current statuses inline.
java.util.List<java.lang.Number>	getFollowerIDs() Returns the IDs of the authenticating user's followers.
java.util.List<java.lang.Number>	getFollowerIDs(java.lang.String screenName) Returns the IDs of the specified user's followers.
java.util.List<User>	getFollowers() Deprecated. Twitter advise using getFollowerIDs() and show(Number)
java.util.List<User>	getFollowers(java.lang.String username) Returns the (latest 100) given user's followers, each with current status inline.
java.util.List<java.lang.Number>	getFriendIDs() Returns the IDs of the authenticating user's friends.
java.util.List<java.lang.Number>	getFriendIDs(java.lang.String screenName) Returns the IDs of the specified user's friends.
java.util.List<User>	getFriends() Deprecated. Twitter advise you to use getFriendIDs() with Twitter_Users#showById(List) instead.
java.util.List<User>	getFriends(java.lang.String username) Returns the (latest 100) given user's friends, each with current status inline.
java.util.List<User>	getRelationshipInfo(java.util.List<java.lang.String> screenNames) Bulk-fetch relationship info by screen-name.
java.util.List<User>	getRelationshipInfoById(java.util.List<? extends java.lang.Number> userIDs) Bulk-fetch relationship info by user-id.
User	getUser(long userId) Synonym for #show(long).
User	getUser(java.lang.String screenName) Synonym for show(String).
boolean	isBlocked(java.lang.Long userId)
boolean	isBlocked(java.lang.String screenName)
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(User user) Convenience for isFollowing(String)
User	leaveNotifications(java.lang.String screenName) Switches off notifications for updates from the specified user who must already be a friend.
User	notify(java.lang.String username) Enables notifications for updates from the specified user who must already be a friend.
User	reportSpammer(java.lang.String screenName)
java.util.List<User>	searchUsers(java.lang.String searchTerm) Warning: there is a bug within twitter.com which means that location-based searches are treated as OR.
java.util.List<User>	show(java.util.List<java.lang.String> screenNames) Lookup user info.
User	show(java.lang.Number userId) Returns information of a given user, specified by user-id.
User	show(java.lang.String screenName) Returns information of a given user, specified by screen name.
java.util.List<User>	showById(java.util.Collection<? extends java.lang.Number> userIds) Lookup user info.
User	stopFollowing(java.lang.String username) Destroy: Discontinues friendship with the user specified in the ID parameter as the authenticating user.
User	stopFollowing(User user) Convenience for stopFollowing(String)
User	unblock(java.lang.String screenName) blocks/destroy: Un-blocks screenName for the authenticating user.
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

Method Detail

block

public User block(java.lang.String screenName)

blocks/create: Blocks screenName from following the authenticating user. In addition the blocked user will not show in the authenticating users mentions or timeline (unless retweeted by another user). If a follow or friend relationship exists it is destroyed.

Parameters:

screenName -

Returns:

info on the (now blocked) user

See Also:

unblock(String)

follow

public 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 (a) they were already being followed, or (b) they protect their tweets & you already requested to follow them.

Throws:

TwitterException - if the user does not exist or has been suspended.

See Also:

stopFollowing(String)

follow

public User follow(User user)

Convenience for follow(String)

Parameters:

user -

Returns:

fresh user object, or null if (a) they were already being followed, or (b) they protect their tweets & you already requested to follow them.

getBlockedIds

public java.util.List<java.lang.Number> getBlockedIds()

Returns:

an array of numeric user ids the authenticating user is blocking. Use showById(Collection) if you want to convert thse into User objects.

getFeatured

public java.util.List<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.Number> getFollowerIDs()
                                                throws TwitterException

Returns the IDs of the authenticating user's followers.

Throws:

TwitterException

getFollowerIDs

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

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

Deprecated. Twitter advise using getFollowerIDs() and show(Number)

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

Throws:

TwitterException

getFollowers

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

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

Deprecated. Twitter advise you to use getFriendIDs() with Twitter_Users#showById(List) instead.

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

getRelationshipInfo

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

Bulk-fetch relationship info by screen-name.

Parameters:

screenNames - Can be empty

Returns:

User objects which are mostly blank, but do have User.isFollowingYou() and User.isFollowedByYou() set (plus name, screenname and id).

See Also:

getRelationshipInfoById(List)

getRelationshipInfoById

public java.util.List<User> getRelationshipInfoById(java.util.List<? extends java.lang.Number> userIDs)

Bulk-fetch relationship info by user-id.

Parameters:

userIDs - Can be empty

Returns:

User objects which are mostly blank, but which have User.isFollowingYou() and User.isFollowedByYou() set (plus name, screenname and id).

See Also:

getRelationshipInfo(List)

getUser

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

isBlocked

public boolean isBlocked(java.lang.Long userId)

isBlocked

public boolean isBlocked(java.lang.String screenName)

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 TwitterException.SuspendedUser exception sub-class for this).

TwitterException.E404 - if one of the users does not exist

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

Convenience for isFollowing(String)

Parameters:

user -

leaveNotifications

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

reportSpammer

public User reportSpammer(java.lang.String screenName)

searchUsers

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

Unlike tweet search, this method does not support any operators. Only the first 1000 matches are available.

Does not do paging-to-max-results. But does support using #setPageNumber(Integer), and #setMaxResults(int) for less than the standard 20.

Parameters:

searchTerm -

Returns:

show

public java.util.List<User> show(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 - Can be empty (in which case we avoid wasting an API call)

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:

#showById(List)

show

public User show(java.lang.Number 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 User show(java.lang.String screenName)
          throws TwitterException,
                 TwitterException.SuspendedUser

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

TwitterException.SuspendedUser - if the user has been terminated (as happens to spam bots).

TwitterException

See Also:

#show(long)

showById

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

Lookup user info. Same as show(List), but works with Twitter user-ID numbers. Done in batches of 100, limited to 1000 an hour.

Parameters:

userIds - . Can be empty (in which case we avoid making a wasted API call).

stopFollowing

public 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 User stopFollowing(User user)

Convenience for stopFollowing(String)

Parameters:

user -

Returns:

unblock

public User unblock(java.lang.String screenName)

blocks/destroy: Un-blocks screenName for the authenticating user. Returns the un-blocked user when successful. If relationships existed before the block was instated, they will not be restored.

Parameters:

screenName -

Returns:

the now un-blocked User

See Also:

block(String)

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.