org.jivesoftware.smack

Class PacketCollector

java.lang.Object

org.jivesoftware.smack.PacketCollector

public class PacketCollector
extends Object

Provides a mechanism to collect packets into a result queue that pass a specified filter. The collector lets you perform blocking and polling operations on the result queue. So, a PacketCollector is more suitable to use than a StanzaListener when you need to wait for a specific result.

Each stanza(/packet) collector will queue up a configured number of packets for processing before older packets are automatically dropped. The default number is retrieved by SmackConfiguration.getPacketCollectorSize().

Author:

Matt Tucker

See Also:

XMPPConnection.createPacketCollector(StanzaFilter)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PacketCollector.Configuration

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PacketCollector(XMPPConnection connection, PacketCollector.Configuration configuration) Creates a new stanza(/packet) collector.

Method Summary

Modifier and Type	Method and Description
void	cancel() Explicitly cancels the stanza(/packet) collector so that no more results are queued up.
int	getCollectedCount() Get the number of collected stanzas this stanza(/packet) collector has collected so far.
StanzaFilter	getPacketFilter() Deprecated. use getStanzaFilter() instead.
StanzaFilter	getStanzaFilter() Returns the stanza filter associated with this stanza collector.
static PacketCollector.Configuration	newConfiguration() Get a new stanza(/packet) collector configuration instance.
<P extends Stanza> P	nextResult() Returns the next available packet.
<P extends Stanza> P	nextResult(long timeout) Returns the next available packet.
<P extends Stanza> P	nextResultBlockForever() Returns the next available packet.
<P extends Stanza> P	nextResultOrThrow() Returns the next available packet.
<P extends Stanza> P	nextResultOrThrow(long timeout) Returns the next available packet.
<P extends Stanza> P	pollResult() Polls to see if a stanza(/packet) is currently available and returns it, or immediately returns null if no packets are currently in the result queue.
<P extends Stanza> P	pollResultOrThrow() Polls to see if a stanza(/packet) is currently available and returns it, or immediately returns null if no packets are currently in the result queue.
protected void	processPacket(Stanza packet) Processes a stanza(/packet) to see if it meets the criteria for this stanza(/packet) collector.

Methods inherited from class java.lang.Object

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

Constructor Detail

PacketCollector

protected PacketCollector(XMPPConnection connection,
                          PacketCollector.Configuration configuration)

Creates a new stanza(/packet) collector. If the stanza(/packet) filter is null, then all packets will match this collector.

Parameters:

connection - the connection the collector is tied to.

configuration - the configuration used to construct this collector

Method Detail

cancel

public void cancel()

Explicitly cancels the stanza(/packet) collector so that no more results are queued up. Once a stanza(/packet) collector has been cancelled, it cannot be re-enabled. Instead, a new stanza(/packet) collector must be created.

getPacketFilter

@Deprecated
public StanzaFilter getPacketFilter()

Deprecated. use getStanzaFilter() instead.

Returns the stanza(/packet) filter associated with this stanza(/packet) collector. The packet filter is used to determine what packets are queued as results.

Returns:

the stanza(/packet) filter.

getStanzaFilter

public StanzaFilter getStanzaFilter()

Returns the stanza filter associated with this stanza collector. The stanza filter is used to determine what stanzas are queued as results.

Returns:

the stanza filter.

pollResult

public <P extends Stanza> P pollResult()

Polls to see if a stanza(/packet) is currently available and returns it, or immediately returns null if no packets are currently in the result queue.

Returns:

the next stanza(/packet) result, or null if there are no more results.

pollResultOrThrow

public <P extends Stanza> P pollResultOrThrow()
                                       throws XMPPException.XMPPErrorException

Polls to see if a stanza(/packet) is currently available and returns it, or immediately returns null if no packets are currently in the result queue.

Throws an XMPPErrorException in case the polled stanzas did contain an XMPPError.

Returns:

the next available packet.

Throws:

XMPPException.XMPPErrorException - in case an error response.

nextResultBlockForever

public <P extends Stanza> P nextResultBlockForever()

Returns the next available packet. The method call will block (not return) until a stanza(/packet) is available.

Returns:

the next available packet.

nextResult

public <P extends Stanza> P nextResult()

Returns the next available packet. The method call will block until the connection's default timeout has elapsed.

Returns:

the next available packet.

nextResult

public <P extends Stanza> P nextResult(long timeout)

Returns the next available packet. The method call will block (not return) until a stanza(/packet) is available or the timeout has elapsed. If the timeout elapses without a result, null will be returned.

Parameters:

timeout - the timeout in milliseconds.

Returns:

the next available packet.

nextResultOrThrow

public <P extends Stanza> P nextResultOrThrow()
                                       throws SmackException.NoResponseException,
                                              XMPPException.XMPPErrorException

Returns the next available packet. The method call will block until a stanza(/packet) is available or the connections reply timeout has elapsed. If the timeout elapses without a result, null will be returned. This method does also cancel the PacketCollector.

Returns:

the next available packet.

Throws:

XMPPException.XMPPErrorException - in case an error response.

SmackException.NoResponseException - if there was no response from the server.

nextResultOrThrow

public <P extends Stanza> P nextResultOrThrow(long timeout)
                                       throws SmackException.NoResponseException,
                                              XMPPException.XMPPErrorException

Returns the next available packet. The method call will block until a stanza(/packet) is available or the timeout has elapsed. This method does also cancel the PacketCollector.

Parameters:

timeout - the amount of time to wait for the next stanza(/packet) (in milleseconds).

Returns:

the next available packet.

Throws:

SmackException.NoResponseException - if there was no response from the server.

XMPPException.XMPPErrorException - in case an error response.

getCollectedCount

public int getCollectedCount()

Get the number of collected stanzas this stanza(/packet) collector has collected so far.

Returns:

the count of collected stanzas.

Since:

4.1

processPacket

protected void processPacket(Stanza packet)

Processes a stanza(/packet) to see if it meets the criteria for this stanza(/packet) collector. If so, the stanza(/packet) is added to the result queue.

Parameters:

packet - the stanza(/packet) to process.

newConfiguration

public static PacketCollector.Configuration newConfiguration()

Get a new stanza(/packet) collector configuration instance.

Returns:

a new stanza(/packet) collector configuration.