diff --git a/smack-core/src/main/java/org/jivesoftware/smack/PacketCollector.java b/smack-core/src/main/java/org/jivesoftware/smack/PacketCollector.java index 00d7d904e..cc8548bcb 100644 --- a/smack-core/src/main/java/org/jivesoftware/smack/PacketCollector.java +++ b/smack-core/src/main/java/org/jivesoftware/smack/PacketCollector.java @@ -192,15 +192,16 @@ public class PacketCollector { } /** - * 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 stanza. The method in equivalent to + * {@link #nextResultOrThrow(long)} where the timeout argument is the default reply timeout of + * the connection associated with this collector. * - * @return the next available packet. - * @throws XMPPErrorException in case an error response. + * @return the next available stanza. + * @throws XMPPErrorException in case an error response was received. * @throws NoResponseException if there was no response from the server. - * @throws InterruptedException - * @throws NotConnectedException + * @throws InterruptedException + * @throws NotConnectedException + * @see #nextResultOrThrow(long) */ public

P nextResultOrThrow() throws NoResponseException, XMPPErrorException, 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 - * the timeout has elapsed. This method does also cancel the PacketCollector. - * - * @param timeout the amount of time to wait for the next stanza(/packet) (in milleseconds). - * @return the next available packet. + * 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. + *
  3. An error response arrives.
  4. + *
  5. An timeout occurs.
  6. + *
  7. The thread is interrupted
  8. + *
+ *

+ * in which this method will + *

+ *
    + *
  1. return with the result.
  2. + *
  3. throw an {@link XMPPErrorException}.
  4. + *
  5. throw an {@link NoResponseException}.
  6. + *
  7. throw an {@link InterruptedException}.
  8. + *
+ *

+ * Additionally the method will throw a {@link NotConnectedException} if no response was + * received and the connection got disconnected. + *

+ * + * @param timeout the amount of time to wait for the next stanza in milliseconds. + * @return the next available stanza. * @throws NoResponseException if there was no response from the server. - * @throws XMPPErrorException in case an error response. - * @throws InterruptedException - * @throws NotConnectedException + * @throws XMPPErrorException in case an error response was received. + * @throws InterruptedException if the calling thread was interrupted. + * @throws NotConnectedException if there was no response and the connection got disconnected. */ public

P nextResultOrThrow(long timeout) throws NoResponseException, XMPPErrorException, InterruptedException, NotConnectedException {