winterwell.jtwitter
Class AStream

java.lang.Object
  winterwell.jtwitter.AStream

All Implemented Interfaces:

java.io.Closeable

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

static interface	AStream.IListen Use these for push-notification of incoming tweets and stream activity.
static class	AStream.Outage

Field Summary

static int

MAX_BUFFER Start dropping messages after this.

Constructor Summary

AStream(Twitter jtwit)

Method Summary

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

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 void fillInOutages()
                         throws java.lang.UnsupportedOperationException

Use the REST API to fill in outages when possible. Filled-in outages will be removed from the list.

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.

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

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

popSystemEvents

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

Returns:

the recent system events, such as "delete this status". Calling this will clear the list of system events.

This also lists reconnect events, with the number of seconds taken to reconnect.

popTweets

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

Returns:

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

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.