From 6be93f4a4e4b4c983ff93fbd6f37a6b5de669c85 Mon Sep 17 00:00:00 2001
From: Matt Tucker <matt@jivesoftware.com>
Date: Fri, 15 Sep 2006 21:51:08 +0000
Subject: [PATCH] Code cleanup and refactoring.

git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@5383 b35dd754-fafc-0310-a699-88a17e54d16e
---
 .../org/jivesoftware/smack/PrivacyList.java   |   2 +-
 .../smack/PrivacyListManager.java             |   2 +-
 .../smack/ReconnectionManager.java            |  31 +++--
 .../jivesoftware/smack/XMPPConnection.java    | 114 +++++++++---------
 .../smackx/LastActivityManager.java           |   2 +-
 .../smackx/ServiceDiscoveryManager.java       |   2 +-
 .../smackx/muc/MultiUserChat.java             |   2 +-
 7 files changed, 78 insertions(+), 77 deletions(-)

diff --git a/source/org/jivesoftware/smack/PrivacyList.java b/source/org/jivesoftware/smack/PrivacyList.java
index 44f4737ff..aec66364c 100644
--- a/source/org/jivesoftware/smack/PrivacyList.java
+++ b/source/org/jivesoftware/smack/PrivacyList.java
@@ -5,7 +5,7 @@ import org.jivesoftware.smack.packet.PrivacyItem;
 import java.util.List;
 
 /**
- * A Privacy List is a read only class used to represent a set of allowed or blocked communications. 
+ * A privacy list represents a list of contacts that is a read only class used to represent a set of allowed or blocked communications. 
  * Basically it can:<ul>
  *
  *      <li>Handle many {@link org.jivesoftware.smack.packet.PrivacyItem}.</li>
diff --git a/source/org/jivesoftware/smack/PrivacyListManager.java b/source/org/jivesoftware/smack/PrivacyListManager.java
index 93febcbd5..129918bd6 100644
--- a/source/org/jivesoftware/smack/PrivacyListManager.java
+++ b/source/org/jivesoftware/smack/PrivacyListManager.java
@@ -35,7 +35,7 @@ public class PrivacyListManager {
         // Create a new PrivacyListManager on every established connection. In the init()
         // method of PrivacyListManager, we'll add a listener that will delete the
         // instance when the connection is closed.
-        XMPPConnection.addConnectionListener(new ConnectionEstablishedListener() {
+        XMPPConnection.addConnectionEstablishedListener(new ConnectionEstablishedListener() {
             public void connectionEstablished(XMPPConnection connection) {
                 new PrivacyListManager(connection);
             }
diff --git a/source/org/jivesoftware/smack/ReconnectionManager.java b/source/org/jivesoftware/smack/ReconnectionManager.java
index 258989113..a36e771bd 100644
--- a/source/org/jivesoftware/smack/ReconnectionManager.java
+++ b/source/org/jivesoftware/smack/ReconnectionManager.java
@@ -4,15 +4,15 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Handles the reconnection process. Every time a connection is broken, it automatically
- * tries to reconnect it. The reconnection is been executed when the first connection
- * error is detected.<p>
+ * Handles the automatic reconnection process. Every time a connection is dropped without
+ * the application explicitly closing it, the manager automatically tries to reconnect to
+ * the server.<p>
  *
- * The reconnection mechanism will try to reconnect periodically in this way:
+ * The reconnection mechanism will try to reconnect periodically:
  * <ol>
- * <li>First it will try 6 times every 10 seconds.
- * <li>Then it will try 10 times every 1 minute.
- * <li>Finally it will try indefinitely every 5 minutes.
+ *      <li>First it will try 6 times every 10 seconds.
+ *      <li>Then it will try 10 times every 1 minute.
+ *      <li>Finally it will try indefinitely every 5 minutes.
  * </ol>
  *
  * @author Francisco Vives
@@ -35,7 +35,7 @@ public class ReconnectionManager implements ConnectionListener {
         // Create a new PrivacyListManager on every established connection. In the init()
         // method of PrivacyListManager, we'll add a listener that will delete the
         // instance when the connection is closed.
-        XMPPConnection.addConnectionListener(new ConnectionEstablishedListener() {
+        XMPPConnection.addConnectionEstablishedListener(new ConnectionEstablishedListener() {
             public void connectionEstablished(XMPPConnection connection) {
                 connection.addConnectionListener(new ReconnectionManager(connection));
             }
@@ -48,7 +48,9 @@ public class ReconnectionManager implements ConnectionListener {
 
 
     /**
-     * Returns if the reconnection mechanism is allowed to use.
+     * Returns true if the reconnection mechanism is enabled.
+     *
+     * @return true if automatic reconnections are allowed.
      */
     private boolean isReconnectionAllowed() {
         return !done && !connection.isConnected()
@@ -103,15 +105,16 @@ public class ReconnectionManager implements ConnectionListener {
                 private int firstReconnectionPeriod = 7; // 6 attempts
                 private int secondReconnectionPeriod = 10 + firstReconnectionPeriod; // 16 attempts
                 private int firstReconnectionTime = 10; // 10 seconds
-                private int secondReconnectionTime = 1 * 60; // 1 minute
+                private int secondReconnectionTime = 60; // 1 minute
                 private int lastReconnectionTime =
                         getSecondBetweenReconnection(); // user defined in seconds
                 private int remainingSeconds = 0; // The seconds remaining to a reconnection
                 private int notificationPeriod = 1000; // 1 second
 
                 /**
-                 * Answer the time it should wait until the next reconnection
-                 * attempt
+                 * Returns the amount of time until the next reconnection attempt.
+                 *
+                 * @return the amount of time until the next reconnection attempt.
                  */
                 private int timeDelay() {
                     if (attempts > secondReconnectionPeriod) {
@@ -173,6 +176,8 @@ public class ReconnectionManager implements ConnectionListener {
 
     /**
      * Fires listeners when a reconnection attempt has failed.
+     *
+     * @param exception the exception that occured.
      */
     protected void notifyReconnectionFailed(Exception exception) {
         List<ConnectionListener> listenersCopy;
@@ -190,6 +195,8 @@ public class ReconnectionManager implements ConnectionListener {
 
     /**
      * Fires listeners when The XMPPConnection will retry a reconnection. Expressed in seconds.
+     *
+     * @param seconds the number of seconds that a reconnection will be attempted in.
      */
     protected void notifyAttemptToReconnectIn(int seconds) {
         List<ConnectionListener> listenersCopy;
diff --git a/source/org/jivesoftware/smack/XMPPConnection.java b/source/org/jivesoftware/smack/XMPPConnection.java
index f5dbfe2fc..08aa082c1 100644
--- a/source/org/jivesoftware/smack/XMPPConnection.java
+++ b/source/org/jivesoftware/smack/XMPPConnection.java
@@ -39,11 +39,11 @@ import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
 import java.net.Socket;
 import java.net.UnknownHostException;
-import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
 
 /**
  * Creates a connection to a XMPP server. A simple use of this API might
@@ -64,10 +64,10 @@ import java.util.concurrent.ConcurrentHashMap;
  *
  * XMPPConnections can be reused between connections. This means that an XMPPConnection
  * may be connected, disconnected and then connected again. Listeners of the XMPPConnection
- * will remain accross connections.<p>
+ * will be retained accross connections.<p>
  *
  * If a connected XMPPConnection gets disconnected abruptly then it will try to reconnect
- * again. To stop the reconnection process just use {@link #disconnect()}. Once stopped
+ * again. To stop the reconnection process, use {@link #disconnect()}. Once stopped
  * you can use {@link #connect()} to manually connect to the server.
  *
  * @author Matt Tucker
@@ -90,7 +90,7 @@ public class XMPPConnection {
     public static boolean DEBUG_ENABLED = false;
 
     private final static List<ConnectionEstablishedListener> connectionEstablishedListeners =
-            new ArrayList<ConnectionEstablishedListener>();
+            new CopyOnWriteArrayList<ConnectionEstablishedListener>();
 
     static {
         // Use try block since we may not have permission to get a system
@@ -267,33 +267,6 @@ public class XMPPConnection {
         init(config, socketFactory);
     }
 
-    private void connectUsingConfiguration(ConnectionConfiguration config) throws XMPPException {
-        this.host = config.getHost();
-        this.port = config.getPort();
-        try {
-            if (config.getSocketFactory() == null) {
-                this.socket = new Socket(host, port);
-            }
-            else {
-                this.socket = config.getSocketFactory().createSocket(host, port);
-            }
-        }
-        catch (UnknownHostException uhe) {
-            String errorMessage = "Could not connect to " + host + ":" + port + ".";
-            throw new XMPPException(errorMessage, new XMPPError(
-                    XMPPError.Condition.remote_server_timeout, errorMessage),
-                    uhe);
-        }
-        catch (IOException ioe) {
-            String errorMessage = "XMPPError connecting to " + host + ":"
-                    + port + ".";
-            throw new XMPPException(errorMessage, new XMPPError(
-                    XMPPError.Condition.remote_server_error, errorMessage), ioe);
-        }
-        this.serviceName = config.getServiceName();
-        initConnection();
-    }
-
     /**
      * Package-private default constructor. This constructor is only intended
      * for unit testing. Normal classes extending XMPPConnection should override
@@ -845,11 +818,9 @@ public class XMPPConnection {
      *
      * @param connectionEstablishedListener a listener interested on connection established events.
      */
-    public static void addConnectionListener(ConnectionEstablishedListener connectionEstablishedListener) {
-        synchronized (connectionEstablishedListeners) {
-            if (!connectionEstablishedListeners.contains(connectionEstablishedListener)) {
-                connectionEstablishedListeners.add(connectionEstablishedListener);
-            }
+    public static void addConnectionEstablishedListener(ConnectionEstablishedListener connectionEstablishedListener) {
+        if (!connectionEstablishedListeners.contains(connectionEstablishedListener)) {
+            connectionEstablishedListeners.add(connectionEstablishedListener);
         }
     }
 
@@ -858,15 +829,43 @@ public class XMPPConnection {
      *
      * @param connectionEstablishedListener a listener interested on connection established events.
      */
-    public static void removeConnectionListener(ConnectionEstablishedListener connectionEstablishedListener) {
-        synchronized (connectionEstablishedListeners) {
-            connectionEstablishedListeners.remove(connectionEstablishedListener);
-        }
+    public static void removeConnectionEstablishedListener(ConnectionEstablishedListener connectionEstablishedListener) {
+        connectionEstablishedListeners.remove(connectionEstablishedListener);
     }
 
-    /** 
+    private void connectUsingConfiguration(ConnectionConfiguration config) throws XMPPException {
+        this.host = config.getHost();
+        this.port = config.getPort();
+        try {
+            if (config.getSocketFactory() == null) {
+                this.socket = new Socket(host, port);
+            }
+            else {
+                this.socket = config.getSocketFactory().createSocket(host, port);
+            }
+        }
+        catch (UnknownHostException uhe) {
+            String errorMessage = "Could not connect to " + host + ":" + port + ".";
+            throw new XMPPException(errorMessage, new XMPPError(
+                    XMPPError.Condition.remote_server_timeout, errorMessage),
+                    uhe);
+        }
+        catch (IOException ioe) {
+            String errorMessage = "XMPPError connecting to " + host + ":"
+                    + port + ".";
+            throw new XMPPException(errorMessage, new XMPPError(
+                    XMPPError.Condition.remote_server_error, errorMessage), ioe);
+        }
+        this.serviceName = config.getServiceName();
+        initConnection();
+    }
+
+    /**
      * Initializes the connection configuration. This method is only executed
      * when the XMPPConnection is created.
+     *
+     * @param config the connection configuration options.
+     * @param socketFactory a factory used for creating sockets to the XMPP server.
      */
     private void init(ConnectionConfiguration config, SocketFactory socketFactory) {
         try {
@@ -925,8 +924,10 @@ public class XMPPConnection {
 
 
             if (isFirstInitialization) {
-                // Notify that a new connection has been established
-                connectionEstablished(this);
+                // Notify listeners that a new connection has been established
+                for (ConnectionEstablishedListener listener : connectionEstablishedListeners) {
+                    listener.connectionEstablished(this);
+                }
 
                 // Add a listener for all message packets so that we can deliver errant
                 // messages to the best Chat instance available.
@@ -1110,20 +1111,6 @@ public class XMPPConnection {
         }
     }
 
-    /**
-     * Fires listeners on connection established events.
-     */
-    private static void connectionEstablished(XMPPConnection connection) {
-        ConnectionEstablishedListener[] listeners;
-        synchronized (connectionEstablishedListeners) {
-            listeners = new ConnectionEstablishedListener[connectionEstablishedListeners.size()];
-            connectionEstablishedListeners.toArray(listeners);
-        }
-        for (ConnectionEstablishedListener listener : listeners) {
-            listener.connectionEstablished(connection);
-        }
-    }
-
     /***********************************************
      * TLS code below
      **********************************************/
@@ -1180,6 +1167,8 @@ public class XMPPConnection {
      * The server has indicated that TLS negotiation can start. We now need to secure the
      * existing plain connection and perform a handshake. This method won't return until the
      * connection has finished the handshake or an error occured while securing the connection.
+     *
+     * @throws Exception if an exception occurs.
      */
     void proceedTLSReceived() throws Exception {
         SSLContext context = SSLContext.getInstance("TLS");
@@ -1300,6 +1289,8 @@ public class XMPPConnection {
 
     /**
      * Start using stream compression since the server has acknowledged stream compression.
+     *
+     * @throws Exception if there is an exception starting stream compression.
      */
     void startStreamCompression() throws Exception {
         // Secure the plain connection
@@ -1317,8 +1308,11 @@ public class XMPPConnection {
         }
     }
 
+    /**
+     * Notifies the XMPP connection that stream compression was denied so that
+     * the connection process can proceed.
+     */
     void streamCompressionDenied() {
-        // Notify that compression has been denied
         synchronized (this) {
             this.notify();
         }
@@ -1358,9 +1352,9 @@ public class XMPPConnection {
     }
     
     /** 
-     * Sets if the connection has already logged in the server.
+     * Sets whether the connection has already logged in the server.
      * 
-     * @param wasAuthenticated
+     * @param wasAuthenticated true if the connection has already been authenticated.
      */
     private void setWasAuthenticated(boolean wasAuthenticated) {
         if (!this.wasAuthenticated) {
diff --git a/source/org/jivesoftware/smackx/LastActivityManager.java b/source/org/jivesoftware/smackx/LastActivityManager.java
index da9393012..023368cc2 100644
--- a/source/org/jivesoftware/smackx/LastActivityManager.java
+++ b/source/org/jivesoftware/smackx/LastActivityManager.java
@@ -75,7 +75,7 @@ public class LastActivityManager {
 
     // Enable the LastActivity support on every established connection
     static {
-        XMPPConnection.addConnectionListener(new ConnectionEstablishedListener() {
+        XMPPConnection.addConnectionEstablishedListener(new ConnectionEstablishedListener() {
             public void connectionEstablished(XMPPConnection connection) {
                 new LastActivityManager(connection);
             }
diff --git a/source/org/jivesoftware/smackx/ServiceDiscoveryManager.java b/source/org/jivesoftware/smackx/ServiceDiscoveryManager.java
index 5c1fefe22..9e6bbdcdc 100644
--- a/source/org/jivesoftware/smackx/ServiceDiscoveryManager.java
+++ b/source/org/jivesoftware/smackx/ServiceDiscoveryManager.java
@@ -59,7 +59,7 @@ public class ServiceDiscoveryManager {
 
     // Create a new ServiceDiscoveryManager on every established connection
     static {
-        XMPPConnection.addConnectionListener(new ConnectionEstablishedListener() {
+        XMPPConnection.addConnectionEstablishedListener(new ConnectionEstablishedListener() {
             public void connectionEstablished(XMPPConnection connection) {
                 new ServiceDiscoveryManager(connection);
             }
diff --git a/source/org/jivesoftware/smackx/muc/MultiUserChat.java b/source/org/jivesoftware/smackx/muc/MultiUserChat.java
index 36cb781e8..b582592b1 100644
--- a/source/org/jivesoftware/smackx/muc/MultiUserChat.java
+++ b/source/org/jivesoftware/smackx/muc/MultiUserChat.java
@@ -76,7 +76,7 @@ public class MultiUserChat {
     private List<PacketListener> connectionListeners = new ArrayList<PacketListener>();
 
     static {
-        XMPPConnection.addConnectionListener(new ConnectionEstablishedListener() {
+        XMPPConnection.addConnectionEstablishedListener(new ConnectionEstablishedListener() {
             public void connectionEstablished(final XMPPConnection connection) {
                 // Set on every established connection that this client supports the Multi-User
                 // Chat protocol. This information will be used when another client tries to