Make non public API private again and update javadoc (#11733)

Change-Id: Ie7a28488e4642a294f0341f00fc98b2ef38922b6

10 files changed, 93 insertions, 72 deletions

diff --git a/client/src/com/vaadin/client/ApplicationConnection.java b/client/src/com/vaadin/client/ApplicationConnection.java
index 568c728671..c7d470accc 100644
--- a/client/src/com/vaadin/client/ApplicationConnection.java
+++ b/client/src/com/vaadin/client/ApplicationConnection.java
@@ -42,7 +42,6 @@ import com.google.gwt.user.client.Timer;
 import com.google.gwt.user.client.ui.HasWidgets;
 import com.google.gwt.user.client.ui.Widget;
 import com.vaadin.client.ApplicationConfiguration.ErrorMessage;
-import com.vaadin.client.ApplicationConnection.ApplicationStoppedEvent;
 import com.vaadin.client.ResourceLoader.ResourceLoadEvent;
 import com.vaadin.client.ResourceLoader.ResourceLoadListener;
 import com.vaadin.client.communication.CommunicationProblemHandler;
@@ -572,45 +571,6 @@ public class ApplicationConnection implements HasHandlers {
     }-*/;
 
     /**
-     * Runs possibly registered client side post request hooks. This is expected
-     * to be run after each uidl request made by Vaadin application.
-     * 
-     * @param appId
-     */
-    public static native void runPostRequestHooks(String appId)
-    /*-{
-    	if ($wnd.vaadin.postRequestHooks) {
-    		for ( var hook in $wnd.vaadin.postRequestHooks) {
-    			if (typeof ($wnd.vaadin.postRequestHooks[hook]) == "function") {
-    				try {
-    					$wnd.vaadin.postRequestHooks[hook](appId);
-    				} catch (e) {
-    				}
-    			}
-    		}
-    	}
-    }-*/;
-
-    /**
-     * If on Liferay and logged in, ask the client side session management
-     * JavaScript to extend the session duration.
-     * 
-     * Otherwise, Liferay client side JavaScript will explicitly expire the
-     * session even though the server side considers the session to be active.
-     * See ticket #8305 for more information.
-     */
-    public static native void extendLiferaySession()
-    /*-{
-    if ($wnd.Liferay && $wnd.Liferay.Session) {
-        $wnd.Liferay.Session.extend();
-        // if the extend banner is visible, hide it
-        if ($wnd.Liferay.Session.banner) {
-            $wnd.Liferay.Session.banner.remove();
-        }
-    }
-    }-*/;
-
-    /**
      * Requests an analyze of layouts, to find inconsistencies. Exclusively used
      * for debugging during development.
      * 
diff --git a/client/src/com/vaadin/client/communication/CommunicationProblemEvent.java b/client/src/com/vaadin/client/communication/CommunicationProblemEvent.java
index b9e373ecea..0e1019ec97 100644
--- a/client/src/com/vaadin/client/communication/CommunicationProblemEvent.java
+++ b/client/src/com/vaadin/client/communication/CommunicationProblemEvent.java
@@ -21,8 +21,10 @@ import com.google.gwt.http.client.Response;
 import elemental.json.JsonObject;
 
 /**
+ * Event describing a problem which took place during communication with the
+ * server
  * 
- * @since
+ * @since 7.6
  * @author Vaadin Ltd
  */
 public class CommunicationProblemEvent {
@@ -33,7 +35,14 @@ public class CommunicationProblemEvent {
     private JsonObject payload;
 
     /**
+     * Constructs an event from the given request, payload and exception
+     * 
+     * @param request
+     *            the request which failed
+     * @param payload
+     *            the payload which was going to the server
      * @param exception
+     *            the exception describing the problem
      */
     public CommunicationProblemEvent(Request request, JsonObject payload,
             Throwable exception) {
@@ -43,8 +52,14 @@ public class CommunicationProblemEvent {
     }
 
     /**
+     * Constructs an event from the given request, response and payload
+     * 
      * @param request
-     * @param statusCode
+     *            the request which failed
+     * @param payload
+     *            the payload which was going to the server
+     * @param response
+     *            the response for the request
      */
     public CommunicationProblemEvent(Request request, JsonObject payload,
             Response response) {
@@ -54,28 +69,36 @@ public class CommunicationProblemEvent {
     }
 
     /**
-     * @return the exception
+     * Returns the exception which caused the problem, if available
+     * 
+     * @return the exception which caused the problem, or null if not available
      */
     public Throwable getException() {
         return exception;
     }
 
     /**
-     * @return the request
+     * Returns the request for which the problem occurred
+     * 
+     * @return the request where the problem occurred
      */
     public Request getRequest() {
         return request;
     }
 
     /**
-     * @return the response
+     * Returns the received response, if available
+     * 
+     * @return the received response, or null if not available
      */
     public Response getResponse() {
         return response;
     }
 
     /**
-     * @return the payload
+     * Returns the payload which was sent to the server
+     * 
+     * @return the payload which was sent, never null
      */
     public JsonObject getPayload() {
         return payload;
diff --git a/client/src/com/vaadin/client/communication/CommunicationProblemHandler.java b/client/src/com/vaadin/client/communication/CommunicationProblemHandler.java
index 73c13864da..1451ec3f93 100644
--- a/client/src/com/vaadin/client/communication/CommunicationProblemHandler.java
+++ b/client/src/com/vaadin/client/communication/CommunicationProblemHandler.java
@@ -22,13 +22,12 @@ import com.vaadin.client.ApplicationConnection;
 import elemental.json.JsonObject;
 
 /**
- * Interface for handling problems which occur during communications with the
+ * Interface for handling problems which occur during communication with the
  * server.
  * 
  * The handler is responsible for handling any problem in XHR, heartbeat and
- * push connections in a way it sees fit. The default implementation used is
- * {@link DefaultCommunicationProblemHandler}, which considers all problems
- * terminal
+ * push connections in a way it sees fit. The default implementation is
+ * {@link ReconnectingCommunicationProblemHandler}.
  * 
  * @since 7.6
  * @author Vaadin Ltd
@@ -188,7 +187,6 @@ public interface CommunicationProblemHandler {
     /**
      * Called when some part of the reconnect dialog configuration has been
      * changed.
-     * 
      */
     void configurationUpdated();
 
diff --git a/client/src/com/vaadin/client/communication/PushConnection.java b/client/src/com/vaadin/client/communication/PushConnection.java
index ceee4a36a3..d5affcfa88 100644
--- a/client/src/com/vaadin/client/communication/PushConnection.java
+++ b/client/src/com/vaadin/client/communication/PushConnection.java
@@ -105,11 +105,11 @@ public interface PushConnection {
 
     /**
      * Checks whether this push connection should be used for communication in
-     * both directions or if a normal XHR should be used for client to server
+     * both directions or if an XHR should be used for client to server
      * communication.
      * 
-     * A bidirectional push connection must be able to reliably tell when it is
-     * connected and when it is not.
+     * A bidirectional push connection must be able to reliably inform about its
+     * connection state.
      * 
      * @since 7.6
      * @return true if the push connection should be used for messages in both
diff --git a/client/src/com/vaadin/client/communication/ReconnectDialog.java b/client/src/com/vaadin/client/communication/ReconnectDialog.java
index 5e1fe790f3..fb03439965 100644
--- a/client/src/com/vaadin/client/communication/ReconnectDialog.java
+++ b/client/src/com/vaadin/client/communication/ReconnectDialog.java
@@ -71,7 +71,8 @@ public interface ReconnectDialog {
      * re-established.
      * 
      * @param modal
-     *            true to set the dialog to modal, false otherwise
+     *            true to make the dialog modal, false to allow usage while
+     *            dialog is shown
      */
     void setModal(boolean modal);
 
@@ -79,7 +80,7 @@ public interface ReconnectDialog {
      * Checks the modality of the dialog.
      * 
      * @see #setModal(boolean)
-     * @return
+     * @return true if the dialog is modal, false otherwise
      */
     boolean isModal();
 }
diff --git a/client/src/com/vaadin/client/communication/ServerCommunicationHandler.java b/client/src/com/vaadin/client/communication/ServerCommunicationHandler.java
index 0e96eafd3d..38b3321b27 100644
--- a/client/src/com/vaadin/client/communication/ServerCommunicationHandler.java
+++ b/client/src/com/vaadin/client/communication/ServerCommunicationHandler.java
@@ -35,15 +35,12 @@ import elemental.json.JsonArray;
 import elemental.json.JsonObject;
 
 /**
- * ServerCommunicationHandler is responsible for communicating (sending and
- * receiving messages) with the servlet.
+ * ServerCommunicationHandler is responsible for sending messages to the server.
  * 
- * It will internally use either XHR or websockets for communicating, depending
- * on how the application is configured.
+ * Internally either XHR or push is used for communicating, depending on the
+ * application configuration.
  * 
- * Uses {@link ServerMessageHandler} for processing received messages
- * 
- * @since
+ * @since 7.6
  * @author Vaadin Ltd
  */
 public class ServerCommunicationHandler {
@@ -73,7 +70,7 @@ public class ServerCommunicationHandler {
         xhrConnection.setConnection(connection);
     }
 
-    public static Logger getLogger() {
+    private static Logger getLogger() {
         return Logger.getLogger(ServerCommunicationHandler.class.getName());
     }
 
@@ -250,8 +247,7 @@ public class ServerCommunicationHandler {
             if (getServerRpcQueue().isFlushPending()) {
                 sendInvocationsToServer();
             }
-            ApplicationConnection.runPostRequestHooks(connection
-                    .getConfiguration().getRootPanelId());
+            runPostRequestHooks(connection.getConfiguration().getRootPanelId());
         }
 
         // deferring to avoid flickering
@@ -269,7 +265,7 @@ public class ServerCommunicationHandler {
                     // responsiveness.
                     // Postponed until the end of the next request if other
                     // requests still pending.
-                    ApplicationConnection.extendLiferaySession();
+                    extendLiferaySession();
                 }
             }
         });
@@ -277,6 +273,45 @@ public class ServerCommunicationHandler {
     }
 
     /**
+     * Runs possibly registered client side post request hooks. This is expected
+     * to be run after each uidl request made by Vaadin application.
+     * 
+     * @param appId
+     */
+    public static native void runPostRequestHooks(String appId)
+    /*-{
+        if ($wnd.vaadin.postRequestHooks) {
+                for ( var hook in $wnd.vaadin.postRequestHooks) {
+                        if (typeof ($wnd.vaadin.postRequestHooks[hook]) == "function") {
+                                try {
+                                        $wnd.vaadin.postRequestHooks[hook](appId);
+                                } catch (e) {
+                                }
+                        }
+                }
+        }
+    }-*/;
+
+    /**
+     * If on Liferay and logged in, ask the client side session management
+     * JavaScript to extend the session duration.
+     * 
+     * Otherwise, Liferay client side JavaScript will explicitly expire the
+     * session even though the server side considers the session to be active.
+     * See ticket #8305 for more information.
+     */
+    public static native void extendLiferaySession()
+    /*-{
+    if ($wnd.Liferay && $wnd.Liferay.Session) {
+        $wnd.Liferay.Session.extend();
+        // if the extend banner is visible, hide it
+        if ($wnd.Liferay.Session.banner) {
+            $wnd.Liferay.Session.banner.remove();
+        }
+    }
+    }-*/;
+
+    /**
      * Indicates whether or not there are currently active UIDL requests. Used
      * internally to sequence requests properly, seldom needed in Widgets.
      * 
diff --git a/client/src/com/vaadin/client/communication/ServerMessageHandler.java b/client/src/com/vaadin/client/communication/ServerMessageHandler.java
index 3c986079a1..0daf0c8fcc 100644
--- a/client/src/com/vaadin/client/communication/ServerMessageHandler.java
+++ b/client/src/com/vaadin/client/communication/ServerMessageHandler.java
@@ -80,7 +80,7 @@ import elemental.json.JsonObject;
  * from the server (state changes, RPCs and other updates) and ensuring that the
  * connectors are updated accordingly.
  * 
- * @since
+ * @since 7.6
  * @author Vaadin Ltd
  */
 public class ServerMessageHandler {
@@ -214,7 +214,7 @@ public class ServerMessageHandler {
         this.connection = connection;
     }
 
-    public static Logger getLogger() {
+    private static Logger getLogger() {
         return Logger.getLogger(ServerMessageHandler.class.getName());
     }
 
diff --git a/client/src/com/vaadin/client/communication/ServerRpcQueue.java b/client/src/com/vaadin/client/communication/ServerRpcQueue.java
index 16fe54ec94..94cc167c30 100644
--- a/client/src/com/vaadin/client/communication/ServerRpcQueue.java
+++ b/client/src/com/vaadin/client/communication/ServerRpcQueue.java
@@ -39,7 +39,7 @@ import elemental.json.JsonValue;
  * Manages the queue of server invocations (RPC) which are waiting to be sent to
  * the server.
  * 
- * @since
+ * @since 7.6
  * @author Vaadin Ltd
  */
 public class ServerRpcQueue {
@@ -76,7 +76,7 @@ public class ServerRpcQueue {
         this.connection = connection;
     }
 
-    public static Logger getLogger() {
+    private static Logger getLogger() {
         return Logger.getLogger(ServerRpcQueue.class.getName());
     }
 
@@ -135,6 +135,8 @@ public class ServerRpcQueue {
 
     /**
      * Returns a collection of all queued method invocations
+     * <p>
+     * The returned collection must not be modified in any way
      * 
      * @return a collection of all queued method invocations
      */
diff --git a/client/src/com/vaadin/client/communication/XhrConnection.java b/client/src/com/vaadin/client/communication/XhrConnection.java
index 7930560aae..e830d465fc 100644
--- a/client/src/com/vaadin/client/communication/XhrConnection.java
+++ b/client/src/com/vaadin/client/communication/XhrConnection.java
@@ -99,7 +99,7 @@ public class XhrConnection {
 
     }
 
-    public static Logger getLogger() {
+    private static Logger getLogger() {
         return Logger.getLogger(XhrConnection.class.getName());
     }
 
diff --git a/server/src/com/vaadin/ui/UI.java b/server/src/com/vaadin/ui/UI.java
index 1e27856af3..90ae713746 100644
--- a/server/src/com/vaadin/ui/UI.java
+++ b/server/src/com/vaadin/ui/UI.java
@@ -1717,6 +1717,7 @@ public abstract class UI extends AbstractSingleComponentContainer implements
      * 
      * @return lastProcessedServerMessageId the id of the last processed server
      *         message
+     * @since 7.6
      */
     public int getLastProcessedClientToServerId() {
         return lastProcessedClientToServerId;
@@ -1729,6 +1730,7 @@ public abstract class UI extends AbstractSingleComponentContainer implements
      * 
      * @param lastProcessedServerMessageId
      *            the id of the last processed server message
+     * @since 7.6
      */
     public void setLastProcessedClientToServerId(
             int lastProcessedClientToServerId) {