org.jivesoftware.smack

Class PacketCollector

java.lang.Object

org.jivesoftware.smack.PacketCollector

public class PacketCollector
extends java.lang.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 PacketListener when you need to wait for a specific result.

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

See Also:

XMPPConnection.createPacketCollector(PacketFilter)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PacketCollector(XMPPConnection connection, PacketFilter packetFilter) Creates a new packet collector.
protected	PacketCollector(XMPPConnection connection, PacketFilter packetFilter, int maxSize) Creates a new packet collector.

Method Summary

Methods

Modifier and Type	Method and Description
void	cancel() Explicitly cancels the packet collector so that no more results are queued up.
PacketFilter	getPacketFilter() Returns the packet filter associated with this packet collector.
<P extends Packet> P	nextResult() Returns the next available packet.
<P extends Packet> P	nextResult(long timeout) Returns the next available packet.
<P extends Packet> P	nextResultBlockForever() Returns the next available packet.
<P extends Packet> P	nextResultOrThrow() Returns the next available packet.
<P extends Packet> P	nextResultOrThrow(long timeout) Returns the next available packet.
<P extends Packet> P	pollResult() Polls to see if a packet is currently available and returns it, or immediately returns null if no packets are currently in the result queue.
protected void	processPacket(Packet packet) Processes a packet to see if it meets the criteria for this 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,
               PacketFilter packetFilter)

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

Parameters:

connection - the connection the collector is tied to.

packetFilter - determines which packets will be returned by this collector.

PacketCollector

protected PacketCollector(XMPPConnection connection,
               PacketFilter packetFilter,
               int maxSize)

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

Parameters:

connection - the connection the collector is tied to.

packetFilter - determines which packets will be returned by this collector.

maxSize - the maximum number of packets that will be stored in the collector.

Method Detail

cancel

public void cancel()

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

getPacketFilter

public PacketFilter getPacketFilter()

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

Returns:

the packet filter.

pollResult

public <P extends Packet> P pollResult()

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

Returns:

the next packet result, or null if there are no more results.

nextResultBlockForever

public <P extends Packet> P nextResultBlockForever()

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

Returns:

the next available packet.

nextResult

public <P extends Packet> P nextResult()

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

Returns:

the next availabe packet.

nextResult

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

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

Returns:

the next available packet.

nextResultOrThrow

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

Returns the next available packet. The method call will block until a 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 Packet> P nextResultOrThrow(long timeout)
                                   throws SmackException.NoResponseException,
                                          XMPPException.XMPPErrorException

Returns the next available packet. The method call will block until a 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 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.

processPacket

protected void processPacket(Packet packet)

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

Parameters:

packet - the packet to process.