Mercury-IM/Smack
Mercury-IM/Smack
1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2024-11-04 15:45:58 +01:00
Code Issues Releases Wiki Activity

Improve Collector javadoc

Browse source
This commit is contained in:
Florian Schmaus 2016-08-01 16:18:01 +02:00
parent f1e24e2273
commit e04697d349
1 changed files with 39 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
smack-core/src/main/java/org/jivesoftware/smack/PacketCollector.java
View file

@ -192,15 +192,16 @@ public class PacketCollector {
} }
/** /**
* Returns the next available packet. The method call will block until a stanza(/packet) is available or * Returns the next available stanza. The method in equivalent to
* the connections reply timeout has elapsed. If the timeout elapses without a result, * {@link #nextResultOrThrow(long)} where the timeout argument is the default reply timeout of
* <tt>null</tt> will be returned. This method does also cancel the PacketCollector. * the connection associated with this collector.
* *
* @return the next available packet. * @return the next available stanza.
* @throws XMPPErrorException in case an error response. * @throws XMPPErrorException in case an error response was received.
* @throws NoResponseException if there was no response from the server. * @throws NoResponseException if there was no response from the server.
* @throws InterruptedException * @throws InterruptedException
* @throws NotConnectedException * @throws NotConnectedException
* @see #nextResultOrThrow(long)
*/ */
public <P extends Stanza> P nextResultOrThrow() throws NoResponseException, XMPPErrorException, public <P extends Stanza> P nextResultOrThrow() throws NoResponseException, XMPPErrorException,
InterruptedException, NotConnectedException { InterruptedException, NotConnectedException {
@ -208,15 +209,38 @@ public class PacketCollector {
} }
/** /**
* Returns the next available packet. The method call will block until a stanza(/packet) is available or * Returns the next available stanza. The method call will block until a stanza is
* the <tt>timeout</tt> has elapsed. This method does also cancel the PacketCollector. * available or the <tt>timeout</tt> has elapsed. This method does also cancel the
* collector in every case.
* <p>
* Three things can happen when waiting for an response:
* </p>
* <ol>
* <li>A result response arrives.</li>
* <li>An error response arrives.</li>
* <li>An timeout occurs.</li>
* <li>The thread is interrupted</li>
* </ol>
* <p>
* in which this method will
* </p>
* <ol>
* <li>return with the result.</li>
* <li>throw an {@link XMPPErrorException}.</li>
* <li>throw an {@link NoResponseException}.</li>
* <li>throw an {@link InterruptedException}.</li>
* </ol>
* <p>
* Additionally the method will throw a {@link NotConnectedException} if no response was
* received and the connection got disconnected.
* </p>
* *
* @param timeout the amount of time to wait for the next stanza(/packet) (in milleseconds). * @param timeout the amount of time to wait for the next stanza in milliseconds.
* @return the next available packet. * @return the next available stanza.
* @throws NoResponseException if there was no response from the server. * @throws NoResponseException if there was no response from the server.
* @throws XMPPErrorException in case an error response. * @throws XMPPErrorException in case an error response was received.
* @throws InterruptedException * @throws InterruptedException if the calling thread was interrupted.
* @throws NotConnectedException * @throws NotConnectedException if there was no response and the connection got disconnected.
*/ */
public <P extends Stanza> P nextResultOrThrow(long timeout) throws NoResponseException, public <P extends Stanza> P nextResultOrThrow(long timeout) throws NoResponseException,
XMPPErrorException, InterruptedException, NotConnectedException { XMPPErrorException, InterruptedException, NotConnectedException {