winterwell.jtwitter

Class AStream

java.lang.Object

winterwell.jtwitter.AStream

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

TwitterStream, UserStream

public abstract class AStream
extends java.lang.Object
implements java.io.Closeable

Internal base class for UserStream and TwitterStream.

Warning from Twitter: Consuming applications must tolerate duplicate statuses, out-of-order statuses (upto 3 seconds of scrambling) and non-status messages.

Threading

Streams create a gobbler thread which consumes the output from Twitter. They are then accessed on a polling basis from a second thread. You can also register a listener for push notifications in the gobbler thread. They are thread-safe for this usage -- but not thread-safe for multi-threaded polling (which would be confusing anyway, cos polling typically consumes data).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AStream.IListen Use these for push-notification of incoming tweets and stream activity.
static class	AStream.Outage What, Twitter had an outage? Here are the details.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_BUFFER Start dropping messages after this.

Constructor Summary

Constructors

Constructor and Description
AStream(Twitter jtwit)

Method Summary

Modifier and Type	Method and Description
void	addListener(AStream.IListen listener) Add a listener to the front of the queue.
void	addOutage(AStream.Outage outage) The stream will track outages during use (provided setAutoReconnect(boolean) is true).
void	clear() Forget the past.
void	close() A closed stream can be restarted.
void	connect() Connect to Twitter.
java.lang.Exception	fillInOutages() Use the REST API to fill in outages when possible.
protected void	finalize()
java.util.List<TwitterEvent>	getEvents()
int	getForgotten()
java.util.List<AStream.Outage>	getOutages()
java.util.List<java.lang.Object[]>	getSystemEvents()
java.util.List<Twitter.ITweet>	getTweets()
boolean	isAlive()
boolean	isConnected() Many users will want to use isAlive() instead, which takes into account auto-reconnect behaviour.
java.util.List<TwitterEvent>	popEvents()
java.util.List<java.lang.Object[]>	popSystemEvents() System Events
java.util.List<Twitter.ITweet>	popTweets()
boolean	removeListener(AStream.IListen listener)
void	setAutoReconnect(boolean yes)
void	setPreviousCount(int previousCount) Deprecated. Twitter need to fix this :(

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_BUFFER

public static int MAX_BUFFER

Start dropping messages after this.

Constructor Detail

AStream

public AStream(Twitter jtwit)

Method Detail

addListener

public void addListener(AStream.IListen listener)

Add a listener to the front of the queue. WARNING: listeners need to be fast (see javadoc notes on AStream.IListen)

Parameters:

listener -

addOutage

public void addOutage(AStream.Outage outage)

The stream will track outages during use (provided setAutoReconnect(boolean) is true). This method allows you to manually add outages (which can then be filled in using fillInOutages()) -- e.g. to cover restarting Java.

Parameters:

outage -

clear

public void clear()

Forget the past. Clears all current queues of tweets, etc.

close

public void close()

A closed stream can be restarted.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

connect

public void connect()
             throws TwitterException

Connect to Twitter.

Do nothing if we already have a good connection. Bad or partly formed connections will be closed.

Auto-reconnect is ignored here: if there's an exception it will be thrown and a reconnect will not be attempted. This gives a fast-return.

Throws:

TwitterException

See Also:

reconnect()

fillInOutages

public final java.lang.Exception fillInOutages()
                                        throws java.lang.UnsupportedOperationException

Use the REST API to fill in outages when possible. There is a list of outages -- filled-in outages will be removed from the list, failed ones will be left on. WARNING: This swallows exceptions! (but check the return value).

In accordance with best-practice, this method will skip over very recent outages (which will be picked up by subsequent calls to fillInOutages()).

From dev.twitter.com:
Do not resume REST API polling immediately after a stream failure. Wait at least a minute or two after the initial failure before you begin REST API polling. This delay is crucial to prevent dog-piling the REST API in the event of a minor hiccup on the streaming API.

Returns:

null if all OK, the Exception raised otherwise.

Throws:

java.lang.UnsupportedOperationException

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getEvents

public final java.util.List<TwitterEvent> getEvents()

Returns:

never null

getForgotten

public final int getForgotten()

Returns:

the number of messages (which could be tweets, events, or system events) which the stream has dropped to stay within it's (very generous) bounds.

Best practice is to NOT rely on this for memory management. You should call popEvents(), popSystemEvents() and popTweets() regularly to clear the buffers.

getOutages

public final java.util.List<AStream.Outage> getOutages()

Returns:

the list outages so far. Hopefully empty, never null.

This is the actual list used. You can remove items from this list to quietly forget about them. Use addOutage(Outage) to add items in the correct order. The list size is capped to avoid memory leakage.

getSystemEvents

public final java.util.List<java.lang.Object[]> getSystemEvents()

Returns:

the recent system events, such as "delete this status".

See Also:

popSystemEvents()

getTweets

public final java.util.List<Twitter.ITweet> getTweets()

isAlive

public final boolean isAlive()

Returns:

true if connected, or if trying to reconnect. Note: false for streams which have not yet been connected!

isConnected

public final boolean isConnected()

Many users will want to use isAlive() instead, which takes into account auto-reconnect behaviour.

Returns:

true if connected to Twitter without error (and not in the middle of a stop-sequence).

See Also:

isAlive()

popEvents

public final java.util.List<TwitterEvent> popEvents()

Returns:

the recent events. Calling this will clear the list of events. never null

Thread safety: If two threads both call popEvents / getEvents, then there is a race condition, and the caller should synchronize appropriately.

popSystemEvents

public final java.util.List<java.lang.Object[]> popSystemEvents()

System Events

["delete", Status] This tweet has been deleted from Twitter
["limit", int skipped_tweets] See https://dev.twitter.com/discussions/2655
["exception", Exception]
["reconnect", milliseconds_offline]
["disconnect", JSONObject e.g. {"reason":"admin logout","stream_name":"mystream","code":7}]

Returns:

the recent system events. Calling this will clear the list of system events.

Thread safety: If two threads both call popSystemEvents / getSystemEvents, then there is a race condition, and the caller should synchronize appropriately.

popTweets

public final java.util.List<Twitter.ITweet> popTweets()

Returns:

the recent events. Calling this will clear the list of tweets.

Thread safety: If two threads both call popTweets / getTweets, then there is a race condition, and the caller should synchronize appropriately.

removeListener

public boolean removeListener(AStream.IListen listener)

setAutoReconnect

public void setAutoReconnect(boolean yes)

Parameters:

yes - If true, attempt to connect if disconnected. true by default.

setPreviousCount

@Deprecated
public void setPreviousCount(int previousCount)

Deprecated. Twitter need to fix this :(

How many messages prior-to-connecting to retrieve. Twitter bug: Currently this does not work!

Parameters:

previousCount - Up to 150,000 but subject to change. Negative values are allowed -- they mean the stream will terminate when it reaches the end of the historical messages.