org.jivesoftware.smack

Class StanzaCollector

java.lang.Object

org.jivesoftware.smack.StanzaCollector

All Implemented Interfaces:

java.lang.AutoCloseable

public final class StanzaCollector
extends java.lang.Object
implements java.lang.AutoCloseable

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

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

See Also:

XMPPConnection.createStanzaCollector(StanzaFilter)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	StanzaCollector.Configuration

Method Summary

Modifier and Type	Method and Description
void	cancel() Explicitly cancels the stanza collector so that no more results are queued up.
void	close()
int	getCollectedCount() Get the number of collected stanzas this stanza collector has collected so far.
java.util.List<Stanza>	getCollectedStanzasAfterCancelled() Return a list of all collected stanzas.
StanzaFilter	getStanzaFilter() Returns the stanza filter associated with this stanza collector.
static StanzaCollector.Configuration	newConfiguration() Get a new stanza collector configuration instance.
<P extends Stanza> P	nextResult() Returns the next available packet.
<P extends Stanza> P	nextResult(long timeout) Returns the next available stanza.
<P extends Stanza> P	nextResultBlockForever() Returns the next available packet.
<P extends Stanza> P	nextResultOrThrow() Returns the next available stanza.
<P extends Stanza> P	nextResultOrThrow(long timeout) Returns the next available stanza.
<P extends Stanza> P	pollResult() Polls to see if a stanza 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 is currently available and returns it, or immediately returns null if no packets are currently in the result queue.
protected void	processStanza(Stanza packet) Processes a stanza to see if it meets the criteria for this stanza collector.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

cancel

public void cancel()

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

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 is currently available and returns it, or immediately returns null if no packets are currently in the result queue.

Type Parameters:

P - type of the result stanza.

Returns:

the next stanza 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 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.

Type Parameters:

P - type of the result stanza.

Returns:

the next available packet.

Throws:

XMPPException.XMPPErrorException - in case an error response.

nextResultBlockForever

public <P extends Stanza> P nextResultBlockForever()
                                            throws java.lang.InterruptedException

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

Type Parameters:

P - type of the result stanza.

Returns:

the next available packet.

Throws:

java.lang.InterruptedException

nextResult

public <P extends Stanza> P nextResult()
                                throws java.lang.InterruptedException

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

Type Parameters:

P - type of the result stanza.

Returns:

the next available packet.

Throws:

java.lang.InterruptedException

nextResult

public <P extends Stanza> P nextResult(long timeout)
                                throws java.lang.InterruptedException

Returns the next available stanza. The method call will block (not return) until a stanza is available or the timeout has elapsed or if the connection was terminated because of an error. If the timeout elapses without a result or if there was an connection error, null will be returned.

Type Parameters:

P - type of the result stanza.

Parameters:

timeout - the timeout in milliseconds.

Returns:

the next available stanza or null on timeout or connection error.

Throws:

java.lang.InterruptedException

nextResultOrThrow

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

Returns the next available stanza. The method in equivalent to nextResultOrThrow(long) where the timeout argument is the default reply timeout of the connection associated with this collector.

Type Parameters:

P - type of the result stanza.

Returns:

the next available stanza.

Throws:

XMPPException.XMPPErrorException - in case an error response was received.

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

java.lang.InterruptedException

SmackException.NotConnectedException

See Also:

nextResultOrThrow(long)

nextResultOrThrow

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

Returns the next available stanza. The method call will block until a stanza is available or the timeout has elapsed. This method does also cancel the collector in every case.

Three things can happen when waiting for an response:

1. A result response arrives.
2. An error response arrives.
3. An timeout occurs.
4. The thread is interrupted

in which this method will

1. return with the result.
2. throw an XMPPException.XMPPErrorException.
3. throw an SmackException.NoResponseException.
4. throw an InterruptedException.

Additionally the method will throw a SmackException.NotConnectedException if no response was received and the connection got disconnected.

Type Parameters:

P - type of the result stanza.

Parameters:

timeout - the amount of time to wait for the next stanza in milliseconds.

Returns:

the next available stanza.

Throws:

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

XMPPException.XMPPErrorException - in case an error response was received.

java.lang.InterruptedException - if the calling thread was interrupted.

SmackException.NotConnectedException - if there was no response and the connection got disconnected.

getCollectedStanzasAfterCancelled

public java.util.List<Stanza> getCollectedStanzasAfterCancelled()

Return a list of all collected stanzas. This method must be invoked after the collector has been cancelled.

Returns:

a list of collected stanzas.

Since:

4.3.0

getCollectedCount

public int getCollectedCount()

Get the number of collected stanzas this stanza collector has collected so far.

Returns:

the count of collected stanzas.

Since:

4.1

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

processStanza

protected void processStanza(Stanza packet)

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

Parameters:

packet - the stanza to process.

newConfiguration

public static StanzaCollector.Configuration newConfiguration()

Get a new stanza collector configuration instance.

Returns:

a new stanza collector configuration.

close

public void close()

Specified by:

close in interface java.lang.AutoCloseable