TimelineStreamListener.java

package edu.umd.rhsmith.diads.tools.twitter;

import twitter4j.RateLimitStatus;
import twitter4j.Status;
import twitter4j.TwitterException;

/**
 * <p>
 * The interface defining the operations necessary for an object to listen for
 * events generated by a {@link TimelineStream} instance.
 * </p>
 * <p>
 * This interface provides the means of retrieving statuses via a
 * {@code TimelineStream}; resulting status objects are passed to the
 * {@link #onStatus(Status)} method.
 * </p>
 * <p>
 * Listeners register with {@code TimelineStream} instances via the
 * {@link TimelineStream#addListener(TimelineStreamListener)} method; they may
 * unregister via {@link TimelineStream#removeListener(TimelineStreamListener)}.
 * </p>
 * 
 * @see TimelineStream
 * 
 * @author rmachedo
 * 
 */
public interface TimelineStreamListener {
	/**
	 * <p>
	 * Method invoked by {@link TimelineStream} instances on registered
	 * listeners when they begin collection of a new user's timeline. Provides
	 * the Twitter ID of the to-be-collected user.
	 * </p>
	 * 
	 * @param userId
	 *            the Twitter ID of the
	 *            to-be-collected user
	 */
	public void onUserStarted(long userId);

	/**
	 * <p>
	 * Method invoked by {@link TimelineStream} instances on registered
	 * listeners when they begin collection of a new page of a user's timeline.
	 * Provides the Twitter ID of the user being collected and the timeline page
	 * number that is about to be retrieved.
	 * </p>
	 * 
	 * @param userId
	 *            the Twitter ID of the
	 *            to-be-collected user
	 * @param page
	 *            the timeline page number that is about to be
	 *            retrieved.
	 */
	public void onUserPageStarted(long userId, int page);

	/**
	 * <p>
	 * Method invoked by {@link TimelineStream} instances on registered
	 * listeners when they encounter a rate-limit restriction while collecting a
	 * user's timeline. Provides the Twitter ID of the user being collected, the
	 * timeline page number that is being retrieved, and the
	 * {@link RateLimitStatus} corresponding to the rate-limit.
	 * </p>
	 * <p>
	 * {@code TimelineStream} instances will pause collection until the rate
	 * limit given by this event expires.
	 * </p>
	 * 
	 * @param userId
	 *            the Twitter ID of the
	 *            user being collected
	 * @param page
	 *            the page index that is about to be
	 *            retrieved.
	 * @param rateLimitStatus
	 *            the {@link RateLimitStatus} corresponding to the
	 *            rate-limit.
	 * @see RateLimitStatus
	 */
	public void onRateLimit(long userId, int page,
			RateLimitStatus rateLimitStatus);

	/**
	 * <p>
	 * Method invoked by {@link TimelineStream} instances on registered
	 * listeners when they encounter an unhandled Twitter exception while
	 * collecting a user's timeline. Provides the Twitter ID of the user being
	 * collected, the timeline page number that was being retrieved, and the
	 * {@link TwitterException} that was thrown.
	 * </p>
	 * <p>
	 * {@code TimelineStream} instances will abort collection of a user's
	 * timeline upon encountering an unhandled exception.
	 * </p>
	 * 
	 * @param userId
	 *            the Twitter ID of the
	 *            user being collected
	 * @param page
	 *            the page index that is about to be
	 *            retrieved.
	 * @param rateLimitStatus
	 *            the {@link RateLimitStatus} corresponding to the
	 *            rate-limit.
	 * @see TwitterException
	 */
	public void onException(long userId, int page, TwitterException ex);

	/**
	 * <p>
	 * Method invoked by {@link TimelineStream} instances for each status that
	 * is retrieved from a user's timeline. Provides a pointer to the collected
	 * {@link Status} object.
	 * </p>
	 * 
	 * @param userId
	 *            the collected {@link Status} object
	 */
	public void onStatus(Status status);

	/**
	 * <p>
	 * Method invoked by {@link TimelineStream} instances when they shut down,
	 * ceasing collection of user timelines. No new events will be produced
	 * after this method is invoked.
	 * </p>
	 */
	public void onShutdown();
}