Smack 4.3.0

-----BEGIN PGP SIGNATURE-----
 
 iQGTBAABCgB9FiEEl3UFnzoh3OFr5PuuIjmn6PWFIFIFAltjB1dfFIAAAAAALgAo
 aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDk3
 NzUwNTlGM0EyMURDRTE2QkU0RkJBRTIyMzlBN0U4RjU4NTIwNTIACgkQIjmn6PWF
 IFISagf/bFhu9Getz7tvo3R+Z2brTszQSKVIvXf6DFKXWapUwOLeZp6EQGQXbnym
 UOz1ykMnkCrgKRyNmPFwG2ZBcHWdL0/2nvyfm0e6nhd5gsoTJoqH8gMtVNlIsa47
 lGatkr0JhsyHUREtMbnRmGMEh5M+pMGGWGLqHIFXJIZJ2/IV2cMlBx0jPFpd+Toc
 IKXfe8euZp6Ic8JKk4V7SIcpTJw9zsihsXP3zwwDjn0xft89tI8lpT6MfaWL9q+Z
 bUSEoEv27gJvK1iFbxKR4A1TGnmesl8GMBeWhU2+aF8PardYuc3+0qjD9yah6o6p
 hlg4um1bgWixqRgGWfkcbhDHS1E04A==
 =+uoq
 -----END PGP SIGNATURE-----

Merge tag '4.3.0'

Smack 4.3.0

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

@@ -96,6 +96,38 @@ import org.minidns.dnsname.DnsName;
 import org.xmlpull.v1.XmlPullParser;
 
 
+/**
+ * This abstract class is commonly used as super class for XMPP connection mechanisms like TCP and BOSH. Hence it
+ * provides the methods for connection state management, like {@link #connect()}, {@link #login()} and
+ * {@link #disconnect()} (which are deliberately not provided by the {@link XMPPConnection} interface).
+ * <p>
+ * <b>Note:</b> The default entry point to Smack's documentation is {@link XMPPConnection}. If you are getting started
+ * with Smack, then head over to {@link XMPPConnection} and the come back here.
+ * </p>
+ * <h2>Parsing Exceptions</h2>
+ * <p>
+ * In case a Smack parser (Provider) throws those exceptions are handled over to the {@link ParsingExceptionCallback}. A
+ * common cause for a provider throwing is illegal input, for example a non-numeric String where only Integers are
+ * allowed. Smack's <em>default behavior</em> follows the <b>"fail-hard per default"</b> principle leading to a
+ * termination of the connection on parsing exceptions. This default was chosen to make users eventually aware that they
+ * should configure their own callback and handle those exceptions to prevent the disconnect. Handle a parsing exception
+ * could be as simple as using a non-throwing no-op callback, which would cause the faulty stream element to be taken
+ * out of the stream, i.e., Smack behaves like that element was never received.
+ * </p>
+ * <p>
+ * If the parsing exception is because Smack received illegal input, then please consider informing the authors of the
+ * originating entity about that. If it was thrown because of an bug in a Smack parser, then please consider filling a
+ * bug with Smack.
+ * </p>
+ * <h3>Managing the parsing exception callback</h3>
+ * <p>
+ * The "fail-hard per default" behavior is achieved by using the
+ * {@link org.jivesoftware.smack.parsing.ExceptionThrowingCallbackWithHint} as default parsing exception callback. You
+ * can change the behavior using {@link #setParsingExceptionCallback(ParsingExceptionCallback)} to set a new callback.
+ * Use {@link org.jivesoftware.smack.SmackConfiguration#setDefaultParsingExceptionCallback(ParsingExceptionCallback)} to
+ * set the default callback.
+ * </p>
+ */
 public abstract class AbstractXMPPConnection implements XMPPConnection {
     private static final Logger LOGGER = Logger.getLogger(AbstractXMPPConnection.class.getName());
 

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

@@ -29,7 +29,7 @@ import javax.net.ssl.HostnameVerifier;
 import org.jivesoftware.smack.compression.XMPPInputOutputStream;
 import org.jivesoftware.smack.debugger.ReflectionDebuggerFactory;
 import org.jivesoftware.smack.debugger.SmackDebuggerFactory;
-import org.jivesoftware.smack.parsing.ExceptionThrowingCallback;
+import org.jivesoftware.smack.parsing.ExceptionThrowingCallbackWithHint;
 import org.jivesoftware.smack.parsing.ParsingExceptionCallback;
 import org.jivesoftware.smack.util.Objects;
 
@@ -80,7 +80,7 @@ public final class SmackConfiguration {
      * The default parsing exception callback is {@link ExceptionThrowingCallback} which will
      * throw an exception and therefore disconnect the active connection.
      */
-    private static ParsingExceptionCallback defaultCallback = new ExceptionThrowingCallback();
+    private static ParsingExceptionCallback defaultCallback = new ExceptionThrowingCallbackWithHint();
 
     private static HostnameVerifier defaultHostnameVerififer;
 

smack-core/src/main/java/org/jivesoftware/smack/packet/IQ.java

@@ -137,7 +137,7 @@ public abstract class IQ extends Stanza {
             buf.attribute("type", type.toString());
         }
         buf.rightAngleBracket();
-        buf.append(getChildElementXML());
+        buf.append(getChildElementXML(enclosingNamespace));
         buf.closeElement(IQ_ELEMENT);
         return buf;
     }
@@ -149,10 +149,22 @@ public abstract class IQ extends Stanza {
      * @return the child element section of the IQ XML.
      */
     public final XmlStringBuilder getChildElementXML() {
+        return getChildElementXML(null);
+    }
+
+    /**
+     * Returns the sub-element XML section of the IQ packet, or the empty String if there
+     * isn't one.
+     *
+     * @param enclosingNamespace the enclosing XML namespace.
+     * @return the child element section of the IQ XML.
+     * @since 4.3.0
+     */
+    public final XmlStringBuilder getChildElementXML(String enclosingNamespace) {
         XmlStringBuilder xml = new XmlStringBuilder();
         if (type == Type.error) {
             // Add the error sub-packet, if there is one.
-            appendErrorIfExists(xml);
+            appendErrorIfExists(xml, enclosingNamespace);
         }
         else if (childElementName != null) {
             // Add the query section if there is one.

smack-core/src/main/java/org/jivesoftware/smack/packet/Message.java

@@ -501,7 +501,7 @@ public final class Message extends Stanza implements TypedCloneable<Message> {
         buf.optElement("thread", thread);
         // Append the error subpacket if the message type is an error.
         if (type == Type.error) {
-            appendErrorIfExists(buf);
+            appendErrorIfExists(buf, enclosingNamespace);
         }
 
         // Add extension elements, if any are defined.

smack-core/src/main/java/org/jivesoftware/smack/packet/Presence.java

@@ -292,7 +292,7 @@ public final class Presence extends Stanza implements TypedCloneable<Presence> {
         buf.append(getExtensions(), enclosingNamespace);
 
         // Add the error sub-packet, if there is one.
-        appendErrorIfExists(buf);
+        appendErrorIfExists(buf, enclosingNamespace);
 
         buf.closeElement(ELEMENT);
 

smack-core/src/main/java/org/jivesoftware/smack/packet/Stanza.java

@@ -541,10 +541,10 @@ public abstract class Stanza implements TopLevelStreamElement {
      *
      * @param xml the XmlStringBuilder to append the error to.
      */
-    protected void appendErrorIfExists(XmlStringBuilder xml) {
+    protected void appendErrorIfExists(XmlStringBuilder xml, String enclosingNamespace) {
         StanzaError error = getError();
         if (error != null) {
-            xml.append(error.toXML());
+            xml.append(error.toXML(enclosingNamespace));
         }
     }
 }

smack-core/src/main/java/org/jivesoftware/smack/parsing/ExceptionThrowingCallbackWithHint.java

@@ -0,0 +1,43 @@
+/**
+ *
+ * Copyright 2018 Florian Schmaus.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jivesoftware.smack.parsing;
+
+import java.util.logging.Logger;
+
+import org.jivesoftware.smack.UnparseableStanza;
+
+/**
+ * Like {@link ExceptionThrowingCallback} but additionally logs a warning message.
+ *
+ * @author Florian Schmaus
+ *
+ */
+public class ExceptionThrowingCallbackWithHint extends ExceptionThrowingCallback {
+
+    private static final Logger LOGGER = Logger.getLogger(ExceptionThrowingCallbackWithHint.class.getName());
+
+    @Override
+    public void handleUnparsableStanza(UnparseableStanza packetData) throws Exception {
+        LOGGER.warning("Parsing exception encountered."
+                        + " This exception will be re-thrown, leading to a disconnect."
+                        + " You can change this behavior by setting a different ParsingExceptionCallback using setParsingExceptionCallback()."
+                        + " More information an be found in AbstractXMPPConnection's javadoc.");
+
+        super.handleUnparsableStanza(packetData);
+    }
+}