Make Smack Java8's javac and javadoc ready

.travis.yml

@@ -2,8 +2,14 @@ language: android
 android:
   components:
     - android-8
+jdk:
+  - oraclejdk8
+  - oraclejdk7
+
 install: gradle assemble
 script: gradle check
 
 after_success:
-- gradle jacocoRootReport coveralls
+- JAVAC_VERSION=$((javac -version) 2>&1)
+# Only run jacocoRootReport in the Java7 build
+- if [[ "$JAVAC_VERSION" = javac\ 1.7.* ]]; then gradle jacocoRootReport coveralls; fi

build.gradle

@@ -118,6 +118,14 @@ allprojects {
 		options.encoding = "utf8"
 		options.compilerArgs = [
 			'-Xlint:all',
+			// Set '-options' because a non-java7 javac will emit a
+			// warning if source/traget is set to 1.7 and
+			// bootclasspath is *not* set.
+			// TODO implement a sound heuristic to determine a java7
+			// rt.jar on the build host. And if none is found,
+			// fallback to using a environment variable,
+			// e.g. JAVA7_HOME. See SMACK-651.
+			'-Xlint:-options',
 			'-Werror',
 		]
 	}
@@ -134,6 +142,17 @@ allprojects {
 			xml.enabled true
 		}
 	}
+
+	if (JavaVersion.current().isJava8Compatible()) {
+		tasks.withType(Javadoc) {
+			// The '-quiet' as second argument is actually a hack,
+			// since the one paramater addStringOption doesn't seem to
+			// work, we extra add '-quiet', which is added anyway by
+			// gradle.
+			// TODO enable all doclints, see SMACK-650
+			options.addStringOption('Xdoclint:all,-html,-syntax', '-quiet')
+		}
+	}
 }
 
 gradle.taskGraph.whenReady { taskGraph ->

smack-core/src/main/java/org/jivesoftware/smack/compression/Java7ZlibInputOutputStream.java

@@ -34,12 +34,9 @@ import java.util.zip.InflaterInputStream;
  * <p>
  * See also:
  * <ul>
- * <li><a href=
+ * <li><a href="http://docs.oracle.com/javase/7/docs/api/java/util/zip/Deflater.html#deflate(byte[], int, int, int)">The required deflate() method (Java7)</a>
- * "http://docs.oracle.com/javase/7/docs/api/java/util/zip/Deflater.html#deflate(byte[], int, int, int)"
+ * <li><a href="http://developer.android.com/reference/java/util/zip/Deflater.html#deflate(byte[], int, int, int)">The required deflate() method (Android)</a>
- * >The required deflate() method (Java7)</a>
+ * </ul>
- * <li><a href=
- * "http://developer.android.com/reference/java/util/zip/Deflater.html#deflate(byte[], int, int, int)"
- * >The required deflate() method (Android)</a>
  * 
  * @author Florian Schmaus
  */

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

@@ -42,6 +42,7 @@ import org.jxmpp.jid.Jid;
  * For each message type, different message fields are typically used as follows:
  * <p>
  * <table border="1">
+ * <caption>Message Types</caption>
  * <tr><td>&nbsp;</td><td colspan="5"><b>Message type</b></td></tr>
  * <tr><td><i>Field</i></td><td><b>Normal</b></td><td><b>Chat</b></td><td><b>Group Chat</b></td><td><b>Headline</b></td><td><b>XMPPError</b></td></tr>
  * <tr><td><i>subject</i></td> <td>SHOULD</td><td>SHOULD NOT</td><td>SHOULD NOT</td><td>SHOULD NOT</td><td>SHOULD NOT</td></tr>

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

@@ -285,7 +285,7 @@ public abstract class Stanza implements TopLevelStreamElement {
     }
 
     /**
-     * Return a set of all extensions with the given element name <emph>and</emph> namespace.
+     * Return a set of all extensions with the given element name <em>and</em> namespace.
      * <p>
      * Changes to the returned set will update the stanza(/packet) extensions, if the returned set is not the empty set.
      * </p>

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

@@ -29,6 +29,7 @@ import org.jivesoftware.smack.util.XmlStringBuilder;
  * These is the list of stream errors as defined in the XMPP spec:<p>
  *
  * <table border=1>
+ *      <caption>Stream Errors</caption>
  *      <tr><td><b>Code</b></td><td><b>Description</b></td></tr>
  *      <tr><td> bad-format </td><td> the entity has sent XML that cannot be processed </td></tr>
  *      <tr><td> unsupported-encoding </td><td>  the entity has sent a namespace prefix that is

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

@@ -31,6 +31,7 @@ import org.jivesoftware.smack.util.XmlStringBuilder;
  * error condition as well as as an optional text explanation. Typical errors are:<p>
  *
  * <table border=1>
+ *      <caption>XMPP Errors</caption>
  *      <hr><td><b>XMPP Error Condition</b></td><td><b>Type</b></td><td><b>RFC 6120 Section</b></td></hr>
  *      <tr><td>bad-request</td><td>MODIFY</td><td>8.3.3.1</td></tr>
  *      <tr><td>conflict</td><td>CANCEL</td><td>8.3.3.2</td></tr>

smack-core/src/main/java/org/jivesoftware/smack/util/ArrayBlockingQueueWithShutdown.java

@@ -236,7 +236,6 @@ public class ArrayBlockingQueueWithShutdown<E> extends AbstractQueue<E> implemen
      *  <li>If the thread was was interrupted.</li>
      * </ol>
      * So you have to check which is the case, e.g. by calling {@link #isShutdown()}.
-     * </p>
      *
      * @param e the element to add.
      * @throws InterruptedException if interrupted while waiting or if the queue was shut down.

smack-core/src/main/java/org/jivesoftware/smack/util/XmlStringBuilder.java

@@ -191,7 +191,7 @@ public class XmlStringBuilder implements Appendable, CharSequence {
     }
 
     /**
-     * Add a right angle bracket '>'.
+     * Add a right angle bracket '>'.
      * 
      * @return a reference to this object.
      */
@@ -201,7 +201,7 @@ public class XmlStringBuilder implements Appendable, CharSequence {
     }
 
     /**
-     * Add a right angle bracket '>'.
+     * Add a right angle bracket '>'.
      *
      * @return a reference to this object
      * @deprecated use {@link #rightAngleBracket()} instead
@@ -306,7 +306,7 @@ public class XmlStringBuilder implements Appendable, CharSequence {
     }
 
     /**
-     * Add the given attribute if value not null and value => 0.
+     * Add the given attribute if value not null and {@code value => 0}.
      *
      * @param name
      * @param value

smack-extensions/src/main/java/org/jivesoftware/smackx/bookmarks/BookmarkedConference.java

@@ -110,6 +110,7 @@ public class BookmarkedConference implements SharedBookmark {
         this.password = password;
     }
 
+    @Override
     public boolean equals(Object obj) {
         if(obj == null || !(obj instanceof BookmarkedConference)) {
             return false;
@@ -118,6 +119,11 @@ public class BookmarkedConference implements SharedBookmark {
         return conference.getJid().equalsIgnoreCase(jid);
     }
 
+    @Override
+    public int hashCode() {
+        return getJid().hashCode();
+    }
+
     protected void setShared(boolean isShared) {
         this.isShared = isShared;
     }

smack-extensions/src/main/java/org/jivesoftware/smackx/bookmarks/BookmarkedURL.java

@@ -84,6 +84,7 @@ public class BookmarkedURL implements SharedBookmark {
         return isRss;
     }
 
+    @Override
     public boolean equals(Object obj) {
         if(!(obj instanceof BookmarkedURL)) {
             return false;
@@ -92,6 +93,11 @@ public class BookmarkedURL implements SharedBookmark {
         return url.getURL().equalsIgnoreCase(URL);
     }
 
+    @Override
+    public int hashCode() {
+        return getURL().hashCode();
+    }
+
     protected void setShared(boolean shared) {
         this.isShared = shared;
     }

smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/Form.java

@@ -27,11 +27,11 @@ import org.jivesoftware.smackx.xdata.packet.DataForm;
 /**
  * Represents a Form for gathering data. The form could be of the following types:
  * <ul>
- *  <li>form -> Indicates a form to fill out.</li>
+ *  <li>form &rarr; Indicates a form to fill out.</li>
- *  <li>submit -> The form is filled out, and this is the data that is being returned from 
+ *  <li>submit &rarr; The form is filled out, and this is the data that is being returned from 
  * the form.</li>
- *  <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
+ *  <li>cancel &rarr; The form was cancelled. Tell the asker that piece of information.</li>
- *  <li>result -> Data results being returned from a search, or some other query.</li>
+ *  <li>result &rarr; Data results being returned from a search, or some other query.</li>
  * </ul>
  * 
  * Depending of the form's type different operations are available. For example, it's only possible
@@ -383,7 +383,7 @@ public class Form {
 
     /**
      * Returns the description of the data. It is similar to the title on a web page or an X 
-     * window.  You can put a <title/> on either a form to fill out, or a set of data results.
+     * window.  You can put a title on either a form to fill out, or a set of data results.
      * 
      * @return description of the data.
      */
@@ -423,7 +423,7 @@ public class Form {
 
     /**
      * Sets the description of the data. It is similar to the title on a web page or an X window.
-     * You can put a <title/> on either a form to fill out, or a set of data results.
+     * You can put a title on either a form to fill out, or a set of data results.
      * 
      * @param title description of the data.
      */

smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/FormField.java

@@ -165,9 +165,10 @@ public class FormField implements NamedElement {
     /**
      * Returns a description that provides extra clarification about the question. This information
      * could be presented to the user either in tool-tip, help button, or as a section of text
-     * before the question.<p>
+     * before the question.
-     * <p/>
+     * <p>
      * If the question is of type FIXED then the description should remain empty.
+     * </p>
      *
      * @return description that provides extra clarification about the question.
      */
@@ -255,9 +256,10 @@ public class FormField implements NamedElement {
     /**
      * Sets a description that provides extra clarification about the question. This information
      * could be presented to the user either in tool-tip, help button, or as a section of text
-     * before the question.<p>
+     * before the question.
-     * <p/>
+     * <p>
      * If the question is of type FIXED then the description should remain empty.
+     * </p>
      *
      * @param description provides extra clarification about the question.
      */

smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/XDataManager.java

@@ -51,7 +51,7 @@ public class XDataManager extends Manager {
     /**
      * Get the XDataManager for the given XMPP connection.
      *
-     * @param connection
+     * @param connection the XMPPConnection.
      * @return the XDataManager
      */
     public static synchronized XDataManager getInstanceFor(XMPPConnection connection) {

smack-im/src/main/java/org/jivesoftware/smack/roster/Roster.java

@@ -69,14 +69,15 @@ import org.jxmpp.jid.parts.Resourcepart;
 
 /**
  * Represents a user's roster, which is the collection of users a person receives
- * presence updates for. Roster items are categorized into groups for easier management.<p>
+ * presence updates for. Roster items are categorized into groups for easier management.
- * <p/>
+ * <p>
  * Others users may attempt to subscribe to this user using a subscription request. Three
  * modes are supported for handling these requests: <ul>
  * <li>{@link SubscriptionMode#accept_all accept_all} -- accept all subscription requests.</li>
  * <li>{@link SubscriptionMode#reject_all reject_all} -- reject all subscription requests.</li>
  * <li>{@link SubscriptionMode#manual manual} -- manually process all subscription requests.</li>
  * </ul>
+ * </p>
  *
  * @author Matt Tucker
  * @see #getInstanceFor(XMPPConnection)
@@ -253,11 +254,12 @@ public class Roster extends Manager {
     /**
      * Returns the subscription processing mode, which dictates what action
      * Smack will take when subscription requests from other users are made.
-     * The default subscription mode is {@link SubscriptionMode#accept_all}.<p>
+     * The default subscription mode is {@link SubscriptionMode#accept_all}.
-     * <p/>
+     * <p>
      * If using the manual mode, a PacketListener should be registered that
      * listens for Presence packets that have a type of
      * {@link org.jivesoftware.smack.packet.Presence.Type#subscribe}.
+     * </p>
      *
      * @return the subscription mode.
      */
@@ -268,11 +270,12 @@ public class Roster extends Manager {
     /**
      * Sets the subscription processing mode, which dictates what action
      * Smack will take when subscription requests from other users are made.
-     * The default subscription mode is {@link SubscriptionMode#accept_all}.<p>
+     * The default subscription mode is {@link SubscriptionMode#accept_all}.
-     * <p/>
+     * <p>
      * If using the manual mode, a PacketListener should be registered that
      * listens for Presence packets that have a type of
      * {@link org.jivesoftware.smack.packet.Presence.Type#subscribe}.
+     * </p>
      *
      * @param subscriptionMode the subscription mode.
      */
@@ -427,10 +430,11 @@ public class Roster extends Manager {
     }
 
     /**
-     * Creates a new group.<p>
+     * Creates a new group.
-     * <p/>
+     * <p>
      * Note: you must add at least one entry to the group for the group to be kept
      * after a logout/login. This is due to the way that XMPP stores group information.
+     * </p>
      *
      * @param name the name of the group.
      * @return a new group, or null if the group already exists

smack-java7/src/main/java/org/jivesoftware/smack/util/stringencoder/java7/Base64.java

@@ -20,9 +20,10 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * <p>Encodes and decodes to and from Base64 notation.</p>
+ * Encodes and decodes to and from Base64 notation.
- * This code was obtained from <a href="http://iharder.net/base64">http://iharder.net/base64</a></p>
+ * <p>
- *
+ * This code was obtained from <a href="http://iharder.net/base64">http://iharder.net/base64</a>
+ * </p>
  *
  * @author Robert Harder
  * @author rob@iharder.net

smack-jingle-old/src/main/java/org/jivesoftware/smackx/jingleold/nat/ICECandidate.java

@@ -293,11 +293,7 @@ public class ICECandidate extends TransportCandidate implements Comparable<ICECa
         checkThread.start();
     }
 
-    /*
+    @Override
-    * (non-Javadoc)
-    *
-    * @see java.lang.Object#equals(java.lang.Object)
-    */
     public boolean equals(Object obj) {
         if (this == obj) {
             return true;
@@ -382,6 +378,22 @@ public class ICECandidate extends TransportCandidate implements Comparable<ICECa
         return true;
     }
 
+    @Override
+    public int hashCode() {
+        int res = 37;
+        res = 37 * res + (getChannel() == null ? 0 : getChannel().hashCode());
+        res = 37 * res + (getId() == null ? 0 : getId().hashCode());
+        res = 37 * res + getNetwork();
+        res = 37 * res + (getPassword() == null ? 0 : getPassword().hashCode());
+        res = 37 * res + getPreference();
+        res = 37 * res + (getProto() == null ? 0 : getProto().hashCode());
+        res = 37 * res + (getUsername() == null ? 0 : getUsername().hashCode());
+        res = 37 * res + (getIp() == null ? 0 : getIp().hashCode());
+        res = 37 * res + getPort();
+        res = 37 * res + (getType() == null ? 0 : getType().hashCode());
+        return res;
+    }
+
     public boolean isNull() {
         if (super.isNull()) {
             return true;

smack-jingle-old/src/main/java/org/jivesoftware/smackx/jingleold/nat/TransportCandidate.java

@@ -489,11 +489,7 @@ public abstract class TransportCandidate {
             }
         }
 
-        /*
+        @Override
-           * (non-Javadoc)
-           *
-           * @see java.lang.Object#equals(java.lang.Object)
-           */
         public boolean equals(Object obj) {
             if (this == obj) {
                 return true;
@@ -515,6 +511,14 @@ public abstract class TransportCandidate {
             return true;
         }
 
+        @Override
+        public int hashCode() {
+            if (value == null) {
+                return -1;
+            }
+            return value.hashCode();
+        }
+
         /**
          * Return true if the protocol is not valid.
          *
@@ -567,11 +571,7 @@ public abstract class TransportCandidate {
             }
         }
 
-        /*
+        @Override
-           * (non-Javadoc)
-           *
-           * @see java.lang.Object#equals(java.lang.Object)
-           */
         public boolean equals(Object obj) {
             if (this == obj) {
                 return true;
@@ -593,6 +593,14 @@ public abstract class TransportCandidate {
             return true;
         }
 
+        @Override
+        public int hashCode() {
+            if (value == null) {
+                return -1;
+            }
+            return value.hashCode();
+        }
+
         /**
          * Return true if the channel is not valid.
          *