Merge branch '4.4'

smack-core/src/main/java/org/jivesoftware/smack/XMPPConnection.java

@@ -91,23 +91,24 @@
  * <h2>Incoming Stanza Listeners</h2>
  * Most callbacks (listeners, handlers, …) than you can add to a connection come in three different variants:
  * <ul>
- * <li>standard</li>
- * <li>async (asynchronous)</li>
- * <li>sync (synchronous)</li>
+ * <li>asynchronous - e.g., {@link #addAsyncStanzaListener(StanzaListener, StanzaFilter)}</li>
+ * <li>synchronous  - e.g., {@link #addSyncStanzaListener(StanzaListener, StanzaFilter)}</li>
+ * <li>other        - e.g., {@link #addStanzaListener(StanzaListener, StanzaFilter)}</li>
  * </ul>
  * <p>
- * Standard callbacks are invoked concurrently, but it is ensured that the same callback is never run concurrently.
- * The callback's identity is used as key for that. The events delivered to the callback preserve the order of the
- * causing events of the connection.
- * </p>
- * <p>
  * Asynchronous callbacks are run decoupled from the connections main event loop. Hence a callback triggered by
  * stanza B may (appear to) invoked before a callback triggered by stanza A, even though stanza A arrived before B.
  * </p>
  * <p>
- * Synchronous callbacks are run synchronous to the main event loop of a connection. Hence they are invoked in the
- * exact order of how events happen there, most importantly the arrival order of incoming stanzas. You should only
- * use synchronous callbacks in rare situations.
+ * Synchronous callbacks are invoked concurrently, but it is ensured that the same callback is never run concurrently
+ * and that they are executed in order. That is, if both stanza A and B trigger the same callback, and A arrives before
+ * B, then the callback will be invoked with A first, and then B. Furthermore, those callbacks are not executed within
+ * the main loop. However it is still advisable that those callbacks do not block or only block briefly.
+ * </p>
+ * <p>
+ * Other callbacks are run synchronous to the main event loop of a connection and are executed within the main loop.
+ * <b>This means that if such a callback blocks, the main event loop also blocks, which can easily cause deadlocks.
+ * Therefore, you should avoid using those callbacks unless you know what you are doing.</b>
  * </p>
  * <h2>Stanza Filters</h2>
  * Stanza filters allow you to define the predicates for which listeners or collectors should be invoked. For more
@@ -409,7 +410,7 @@ StanzaCollector createStanzaCollectorAndSend(StanzaFilter stanzaFilter, Stanza s
     boolean removeStanzaListener(StanzaListener stanzaListener);
 
     /**
-     *  Registers a <b>synchronous</b> stanza listener with this connection. A stanza listener will be invoked only when
+     * Registers a <b>synchronous</b> stanza listener with this connection. A stanza listener will be invoked only when
      * an incoming stanza is received. A stanza filter determines which stanzas will be delivered to the listener. If
      * the same stanza listener is added again with a different filter, only the new filter will be used.
      * <p>

smack-experimental/src/main/java/org/jivesoftware/smackx/chat_markers/ChatMarkersManager.java

@@ -174,7 +174,10 @@ else if (ChatMarkersElements.AcknowledgedExtension.from(message) != null) {
      * @throws XMPPErrorException in case an error response was received.
      * @throws NoResponseException if no response was received.
      * @throws InterruptedException if the connection is interrupted.
+     * @deprecated This method serves no purpose, as servers do not announce this feature.
      */
+    // TODO: Remove in Smack 4.6.
+    @Deprecated
     public boolean isSupportedByServer()
             throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException {
         return ServiceDiscoveryManager.getInstanceFor(connection())

smack-extensions/src/main/java/org/jivesoftware/smackx/caps/EntityCapsManager.java

@@ -388,7 +388,10 @@ private void processCapsStreamFeatureIfAvailable(XMPPConnection connection) {
         if (autoEnableEntityCaps)
             enableEntityCaps();
 
-        connection.addAsyncStanzaListener(new StanzaListener() {
+        // Note that this is a *synchronous* stanza listener to avoid unnecessary feature lookups. If this were to be an
+        // asynchronous listener, then it would be possible that the entity caps information was not processed when the
+        // features of entity are looked up. See SMACK-937.
+        connection.addStanzaListener(new StanzaListener() {
             // Listen for remote presence stanzas with the caps extension
             // If we receive such a stanza, record the JID and nodeVer
             @Override