Package org.jivesoftware.smack

Class 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)

    • 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 - if the calling thread was interrupted.

      • 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 - if the calling thread was interrupted.

      • 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 - if the calling thread was interrupted.

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

      • close

        public void close()
        Specified by:
        close in interface java.lang.AutoCloseable