org.springframework.social.twitter.api

Interface TimelineOperations

public interface TimelineOperations

Interface defining the operations for sending and retrieving tweets.

Author:

Craig Walls

Method Summary

Methods

Modifier and Type	Method and Description
void	addToFavorites(long id) Adds a tweet to the user's collection of favorite tweets.
void	deleteStatus(long tweetId) Removes a status entry.
List<Tweet>	getFavorites() Retrieves the 20 most recent tweets favorited by the authenticated user.
List<Tweet>	getFavorites(int pageSize) Retrieves tweets favorited by the authenticated user.
List<Tweet>	getFavorites(long userId) Retrieves the 20 most recent tweets favorited by the specified user.
List<Tweet>	getFavorites(long userId, int pageSize) Retrieves tweets favorited by the specified user.
List<Tweet>	getFavorites(String screenName) Retrieves the 20 most recent tweets favorited by the specified user.
List<Tweet>	getFavorites(String screenName, int pageSize) Retrieves tweets favorited by the specified user.
List<Tweet>	getHomeTimeline() Retrieves the 20 most recently posted tweets, including retweets, from the authenticating user's home timeline.
List<Tweet>	getHomeTimeline(int pageSize) Retrieves tweets, including retweets, from the authenticating user's home timeline.
List<Tweet>	getHomeTimeline(int pageSize, long sinceId, long maxId) Retrieves tweets, including retweets, from the authenticating user's home timeline.
List<Tweet>	getMentions() Retrieve the 20 most recent tweets that mention the authenticated user.
List<Tweet>	getMentions(int pageSize) Retrieve tweets that mention the authenticated user.
List<Tweet>	getMentions(int pageSize, long sinceId, long maxId) Retrieve tweets that mention the authenticated user.
List<Tweet>	getRetweets(long tweetId) Retrieves up to 100 retweets of a specific tweet.
List<Tweet>	getRetweets(long tweetId, int count) Retrieves retweets of a specific tweet.
List<Tweet>	getRetweetsOfMe() Retrieve the 20 most recent tweets of the authenticated user that have been retweeted by others.
List<Tweet>	getRetweetsOfMe(int page, int pageSize) Retrieve tweets of the authenticated user that have been retweeted by others.
List<Tweet>	getRetweetsOfMe(int page, int pageSize, long sinceId, long maxId) Retrieve tweets of the authenticated user that have been retweeted by others.
Tweet	getStatus(long tweetId) Returns a single tweet.
OEmbedTweet	getStatusOEmbed(String tweetId) Returns a single tweet as an oEmbed representation.
OEmbedTweet	getStatusOEmbed(String tweetId, OEmbedOptions options) Returns a single tweet as an oEmbed representation.
List<Tweet>	getUserTimeline() Retrieves the 20 most recent tweets posted by the authenticating user.
List<Tweet>	getUserTimeline(int pageSize) Retrieves tweets posted by the authenticating user.
List<Tweet>	getUserTimeline(int pageSize, long sinceId, long maxId) Retrieves tweets posted by the authenticating user.
List<Tweet>	getUserTimeline(long userId) Retrieves the 20 most recent tweets posted by the given user.
List<Tweet>	getUserTimeline(long userId, int pageSize) Retrieves tweets posted by the given user.
List<Tweet>	getUserTimeline(long userId, int pageSize, long sinceId, long maxId) Retrieves tweets posted by the given user.
List<Tweet>	getUserTimeline(String screenName) Retrieves the 20 most recent tweets posted by the given user.
List<Tweet>	getUserTimeline(String screenName, int pageSize) Retrieves tweets posted by the given user.
List<Tweet>	getUserTimeline(String screenName, int pageSize, long sinceId, long maxId) Retrieves tweets posted by the given user.
void	removeFromFavorites(long id) Removes a tweet from the user's collection of favorite tweets.
Tweet	retweet(long tweetId) Posts a retweet of an existing tweet.
Tweet	updateStatus(String status) Updates the user's status.
Tweet	updateStatus(String status, Resource photo) Deprecated. Use updateStatus(TweetData) instead.
Tweet	updateStatus(String status, Resource photo, StatusDetails details) Deprecated. Use updateStatus(TweetData) instead.
Tweet	updateStatus(String status, StatusDetails details) Deprecated. Use updateStatus(TweetData) instead.
Tweet	updateStatus(TweetData tweetData) Updates the user's status, including any additional metadata about the status carried in TweetData

Method Detail

getHomeTimeline

List<Tweet> getHomeTimeline()

Retrieves the 20 most recently posted tweets, including retweets, from the authenticating user's home timeline. The home timeline includes tweets from the user's timeline and the timeline of anyone that they follow.

Returns:

a collection of Tweets in the authenticating user's home timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getHomeTimeline

List<Tweet> getHomeTimeline(int pageSize)

Retrieves tweets, including retweets, from the authenticating user's home timeline. The home timeline includes tweets from the user's timeline and the timeline of anyone that they follow.

Parameters:

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

Returns:

a collection of Tweets in the authenticating user's home timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getHomeTimeline

List<Tweet> getHomeTimeline(int pageSize,
                          long sinceId,
                          long maxId)

Retrieves tweets, including retweets, from the authenticating user's home timeline. The home timeline includes tweets from the user's timeline and the timeline of anyone that they follow.

Parameters:

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

sinceId - The minimum Tweet ID to return in the results

maxId - The maximum Tweet ID to return in the results

Returns:

a collection of Tweets in the authenticating user's home timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getUserTimeline

List<Tweet> getUserTimeline()

Retrieves the 20 most recent tweets posted by the authenticating user.

Returns:

a collection of Tweets that have been posted by the authenticating user.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getUserTimeline

List<Tweet> getUserTimeline(int pageSize)

Retrieves tweets posted by the authenticating user. The most recent tweets are listed first.

Parameters:

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

Returns:

a collection of Tweets that have been posted by the authenticating user.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getUserTimeline

List<Tweet> getUserTimeline(int pageSize,
                          long sinceId,
                          long maxId)

Retrieves tweets posted by the authenticating user. The most recent tweets are listed first.

Parameters:

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

sinceId - The minimum Tweet ID to return in the results

maxId - The maximum Tweet ID to return in the results

Returns:

a collection of Tweets that have been posted by the authenticating user.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getUserTimeline

List<Tweet> getUserTimeline(String screenName)

Retrieves the 20 most recent tweets posted by the given user. Supports either user or application authorization.

Parameters:

screenName - The screen name of the user whose timeline is being requested.

Returns:

a collection of Tweets from the specified user's timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getUserTimeline

List<Tweet> getUserTimeline(String screenName,
                          int pageSize)

Retrieves tweets posted by the given user. The most recent tweets are listed first. Supports either user or application authorization.

Parameters:

screenName - The screen name of the user whose timeline is being requested.

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

Returns:

a collection of Tweets from the specified user's timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getUserTimeline

List<Tweet> getUserTimeline(String screenName,
                          int pageSize,
                          long sinceId,
                          long maxId)

Retrieves tweets posted by the given user. The most recent tweets are listed first. Supports either user or application authorization.

Parameters:

screenName - The screen name of the user whose timeline is being requested.

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

sinceId - The minimum Tweet ID to return in the results

maxId - The maximum Tweet ID to return in the results

Returns:

a collection of Tweets from the specified user's timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getUserTimeline

List<Tweet> getUserTimeline(long userId)

Retrieves the 20 most recent tweets posted by the given user. Supports either user or application authorization.

Parameters:

userId - The user ID of the user whose timeline is being requested.

Returns:

a collection of Tweets from the specified user's timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getUserTimeline

List<Tweet> getUserTimeline(long userId,
                          int pageSize)

Retrieves tweets posted by the given user. The most recent tweets are listed first. Supports either user or application authorization.

Parameters:

userId - The user ID of the user whose timeline is being requested.

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

Returns:

a collection of Tweets from the specified user's timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getUserTimeline

List<Tweet> getUserTimeline(long userId,
                          int pageSize,
                          long sinceId,
                          long maxId)

Retrieves tweets posted by the given user. The most recent tweets are listed first. Supports either user or application authorization.

Parameters:

userId - The user ID of the user whose timeline is being requested.

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

sinceId - The minimum Tweet ID to return in the results

maxId - The maximum Tweet ID to return in the results

Returns:

a collection of Tweets from the specified user's timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getRetweetsOfMe

List<Tweet> getRetweetsOfMe()

Retrieve the 20 most recent tweets of the authenticated user that have been retweeted by others.

Returns:

a list of Tweets

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getRetweetsOfMe

List<Tweet> getRetweetsOfMe(int page,
                          int pageSize)

Retrieve tweets of the authenticated user that have been retweeted by others. The most recent tweets are listed first.

Parameters:

page - The page to return

pageSize - The number of Tweets per page. Should be less than or equal to 100. (Will return at most 100 entries, even if pageSize is greater than 100.)

Returns:

a list of Tweets

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getRetweetsOfMe

List<Tweet> getRetweetsOfMe(int page,
                          int pageSize,
                          long sinceId,
                          long maxId)

Retrieve tweets of the authenticated user that have been retweeted by others. The most recent tweets are listed first.

Parameters:

page - The page to return

pageSize - The number of Tweets per page. Should be less than or equal to 100. (Will return at most 100 entries, even if pageSize is greater than 100.)

sinceId - The minimum Tweet ID to return in the results.

maxId - The maximum Tweet ID to return in the results.

Returns:

a list of Tweets

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getMentions

List<Tweet> getMentions()

Retrieve the 20 most recent tweets that mention the authenticated user.

Returns:

a collection of Tweet objects that mention the authenticated user.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getMentions

List<Tweet> getMentions(int pageSize)

Retrieve tweets that mention the authenticated user. The most recent tweets are listed first.

Parameters:

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

Returns:

a collection of Tweet objects that mention the authenticated user.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getMentions

List<Tweet> getMentions(int pageSize,
                      long sinceId,
                      long maxId)

Retrieve tweets that mention the authenticated user. The most recent tweets are listed first.

Parameters:

pageSize - The number of Tweets per page. Should be less than or equal to 200. (Will return at most 200 entries, even if pageSize is greater than 200.)

sinceId - The minimum Tweet ID to return in the results

maxId - The maximum Tweet ID to return in the results

Returns:

a collection of Tweet objects that mention the authenticated user.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getStatus

Tweet getStatus(long tweetId)

Returns a single tweet. Supports either user or application authorization.

Parameters:

tweetId - the tweet's ID

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getStatusOEmbed

OEmbedTweet getStatusOEmbed(String tweetId)

Returns a single tweet as an oEmbed representation. Supports either user or application authorization.

Parameters:

tweetId - the tweet's ID

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getStatusOEmbed

OEmbedTweet getStatusOEmbed(String tweetId,
                          OEmbedOptions options)

Returns a single tweet as an oEmbed representation. Supports either user or application authorization.

Parameters:

tweetId - the tweet's ID

options - options for the embedded tweet

Returns:

an OEmbedTweet representing the tweet in oEmbed form

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

updateStatus

Tweet updateStatus(String status)

Updates the user's status.

Parameters:

status - The status message

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.DuplicateStatusException - if the status message duplicates a previously posted status.

MessageTooLongException - if the length of the status message exceeds Twitter's 140 character limit.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

updateStatus

@Deprecated
Tweet updateStatus(String status,
                            Resource photo)

Deprecated. Use updateStatus(TweetData) instead.

Updates the user's status along with a picture.

Parameters:

status - The status message

photo - A Resource for the photo data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource) and must contain GIF, JPG, or PNG data.

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.DuplicateStatusException - if the status message duplicates a previously posted status.

MessageTooLongException - if the length of the status message exceeds Twitter's 140 character limit.

org.springframework.social.OperationNotPermittedException - if the photo resource isn't a GIF, JPG, or PNG.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

updateStatus

@Deprecated
Tweet updateStatus(String status,
                            StatusDetails details)

Deprecated. Use updateStatus(TweetData) instead.

Updates the user's status, including additional metadata concerning the status.

Parameters:

status - The status message

details - Metadata pertaining to the status

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.DuplicateStatusException - if the status message duplicates a previously posted status.

MessageTooLongException - if the length of the status message exceeds Twitter's 140 character limit.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

updateStatus

@Deprecated
Tweet updateStatus(String status,
                            Resource photo,
                            StatusDetails details)

Deprecated. Use updateStatus(TweetData) instead.

Updates the user's status, including a picture and additional metadata concerning the status.

Parameters:

status - The status message

photo - A Resource for the photo data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource) and must contain GIF, JPG, or PNG data.

details - Metadata pertaining to the status

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.DuplicateStatusException - if the status message duplicates a previously posted status.

MessageTooLongException - if the length of the status message exceeds Twitter's 140 character limit.

org.springframework.social.OperationNotPermittedException - if the photo resource isn't a GIF, JPG, or PNG.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

updateStatus

Tweet updateStatus(TweetData tweetData)

Updates the user's status, including any additional metadata about the status carried in TweetData

Parameters:

tweetData - The data defining the status.

Returns:

the Tweet object

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.DuplicateStatusException - if the status message duplicates a previously posted status.

MessageTooLongException - if the length of the status message exceeds Twitter's 140 character limit.

org.springframework.social.OperationNotPermittedException - if the photo resource isn't a GIF, JPG, or PNG.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

deleteStatus

void deleteStatus(long tweetId)

Removes a status entry.

Parameters:

tweetId - the tweet's ID

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

retweet

Tweet retweet(long tweetId)

Posts a retweet of an existing tweet.

Parameters:

tweetId - The ID of the tweet to be retweeted

Returns:

the Tweet object representing the retweet

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getRetweets

List<Tweet> getRetweets(long tweetId)

Retrieves up to 100 retweets of a specific tweet. Supports either user or application authorization.

Parameters:

tweetId - the tweet's ID

Returns:

A list of Tweet objects representing the retweets

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getRetweets

List<Tweet> getRetweets(long tweetId,
                      int count)

Retrieves retweets of a specific tweet. Supports either user or application authorization.

Parameters:

tweetId - the tweet's ID

count - The maximum number of retweets to return. Should be less than or equal to 100. (Will return at most 100 entries, even if pageSize is greater than 100.)

Returns:

A list of Tweet objects representing the retweets

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getFavorites

List<Tweet> getFavorites()

Retrieves the 20 most recent tweets favorited by the authenticated user.

Returns:

a collection of Tweets from the specified user's favorite timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getFavorites

List<Tweet> getFavorites(int pageSize)

Retrieves tweets favorited by the authenticated user.

Parameters:

pageSize - The number of entries per page.

Returns:

a collection of Tweets from the specified user's favorite timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

getFavorites

List<Tweet> getFavorites(long userId)

Retrieves the 20 most recent tweets favorited by the specified user. Supports either user or application authorization.

Parameters:

userId - The user ID of the user whose favorites are being requested.

Returns:

a collection of Tweets from the specified user's favorite timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getFavorites

List<Tweet> getFavorites(long userId,
                       int pageSize)

Retrieves tweets favorited by the specified user. Supports either user or application authorization.

Parameters:

userId - The user ID of the user whose favorites are being requested.

pageSize - The number of entries per page.

Returns:

a collection of Tweets from the specified user's favorite timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getFavorites

List<Tweet> getFavorites(String screenName)

Retrieves the 20 most recent tweets favorited by the specified user. Supports either user or application authorization.

Parameters:

screenName - The screen name of the user whose favorites are being requested.

Returns:

a collection of Tweets from the specified user's favorite timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

getFavorites

List<Tweet> getFavorites(String screenName,
                       int pageSize)

Retrieves tweets favorited by the specified user. Supports either user or application authorization.

Parameters:

screenName - The screen name of the user whose favorites are being requested.

pageSize - The number of entries per page.

Returns:

a collection of Tweets from the specified user's favorite timeline.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials or an application access token.

addToFavorites

void addToFavorites(long id)

Adds a tweet to the user's collection of favorite tweets.

Parameters:

id - the tweet's ID

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.

removeFromFavorites

void removeFromFavorites(long id)

Removes a tweet from the user's collection of favorite tweets.

Parameters:

id - the tweet's ID

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Twitter.

org.springframework.social.MissingAuthorizationException - if TwitterTemplate was not created with OAuth credentials.