Javadocs for #9274

6 files changed, 239 insertions, 7 deletions

diff --git a/server/src/com/vaadin/Application.java b/server/src/com/vaadin/Application.java
index c7f3462b05..05951ce88f 100644
--- a/server/src/com/vaadin/Application.java
+++ b/server/src/com/vaadin/Application.java
@@ -2406,6 +2406,18 @@ public class Application implements Terminal.ErrorListener, Serializable {
         return roots.get(rootId);
     }
 
+    /**
+     * Adds a listener that will be invoked when the bootstrap HTML is about to
+     * be generated. This can be used to modify the contents of the HTML that
+     * loads the Vaadin application in the browser and the HTTP headers that are
+     * included in the response serving the HTML.
+     * 
+     * @see BootstrapListener#modifyBootstrapFragment(BootstrapFragmentResponse)
+     * @see BootstrapListener#modifyBootstrapPage(BootstrapPageResponse)
+     * 
+     * @param listener
+     *            the bootstrap listener to add
+     */
     public void addBootstrapListener(BootstrapListener listener) {
         eventRouter.addListener(BootstrapFragmentResponse.class, listener,
                 BOOTSTRAP_FRAGMENT_METHOD);
@@ -2413,6 +2425,14 @@ public class Application implements Terminal.ErrorListener, Serializable {
                 BOOTSTRAP_PAGE_METHOD);
     }
 
+    /**
+     * Remove a bootstrap listener that was previously added.
+     * 
+     * @see #addBootstrapListener(BootstrapListener)
+     * 
+     * @param listener
+     *            the bootstrap listener to remove
+     */
     public void removeBootstrapListener(BootstrapListener listener) {
         eventRouter.removeListener(BootstrapFragmentResponse.class, listener,
                 BOOTSTRAP_FRAGMENT_METHOD);
@@ -2420,6 +2440,15 @@ public class Application implements Terminal.ErrorListener, Serializable {
                 BOOTSTRAP_PAGE_METHOD);
     }
 
+    /**
+     * Fires a bootstrap event to all registered listeners. There are currently
+     * two supported events, both inheriting from {@link BootstrapResponse}:
+     * {@link BootstrapFragmentResponse} and {@link BootstrapPageResponse}.
+     * 
+     * @param response
+     *            the bootstrap response event for which listeners should be
+     *            fired
+     */
     public void modifyBootstrapResponse(BootstrapResponse response) {
         eventRouter.fireEvent(response);
     }
diff --git a/server/src/com/vaadin/terminal/gwt/server/BootstrapFragmentResponse.java b/server/src/com/vaadin/terminal/gwt/server/BootstrapFragmentResponse.java
index bcf098b5aa..8d3812abcb 100644
--- a/server/src/com/vaadin/terminal/gwt/server/BootstrapFragmentResponse.java
+++ b/server/src/com/vaadin/terminal/gwt/server/BootstrapFragmentResponse.java
@@ -11,16 +11,54 @@ import org.jsoup.nodes.Node;
 import com.vaadin.Application;
 import com.vaadin.terminal.WrappedRequest;
 
+/**
+ * A representation of a bootstrap fragment being generated. The bootstrap
+ * fragment is the HTML code that will make up the actual application. This also
+ * includes the JavaScript that initializes the application.
+ * 
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
 public class BootstrapFragmentResponse extends BootstrapResponse {
     private final List<Node> fragmentNodes;
 
+    /**
+     * Crate a new bootstrap fragment response.
+     * 
+     * @see BootstrapResponse#BootstrapResponse(BootstrapHandler,
+     *      WrappedRequest, Application, Integer)
+     * 
+     * @param handler
+     *            the bootstrap handler that is firing the event
+     * @param request
+     *            the wrapped request for which the bootstrap page should be
+     *            generated
+     * @param application
+     *            the application for which the bootstrap page should be
+     *            generated
+     * @param rootId
+     *            the generated id of the Root that will be displayed on the
+     *            page
+     * @param fragmentNodes
+     *            a mutable list containing the DOM nodes that will make up the
+     *            application HTML
+     */
     public BootstrapFragmentResponse(BootstrapHandler handler,
-            WrappedRequest request, List<Node> fragmentNodes,
-            Application application, Integer rootId) {
+            WrappedRequest request, Application application, Integer rootId,
+            List<Node> fragmentNodes) {
         super(handler, request, application, rootId);
         this.fragmentNodes = fragmentNodes;
     }
 
+    /**
+     * Gets the list of DOM nodes that will be used to generate the fragment
+     * HTML. Changes to the returned list will be reflected in the generated
+     * HTML.
+     * 
+     * @return the current list of DOM nodes that makes up the application
+     *         fragment
+     */
     public List<Node> getFragmentNodes() {
         return fragmentNodes;
     }
diff --git a/server/src/com/vaadin/terminal/gwt/server/BootstrapHandler.java b/server/src/com/vaadin/terminal/gwt/server/BootstrapHandler.java
index 4d278a55a1..b308d628ce 100644
--- a/server/src/com/vaadin/terminal/gwt/server/BootstrapHandler.java
+++ b/server/src/com/vaadin/terminal/gwt/server/BootstrapHandler.java
@@ -158,8 +158,8 @@ public abstract class BootstrapHandler implements RequestHandler {
             Map<String, Object> headers = new LinkedHashMap<String, Object>();
             Document document = Document.createShell("");
             BootstrapPageResponse pageResponse = new BootstrapPageResponse(
-                    this, request, document, headers, context.getApplication(),
-                    context.getRootId());
+                    this, request, context.getApplication(), context.getRootId(), document,
+                    headers);
             List<Node> fragmentNodes = fragmentResponse.getFragmentNodes();
             Element body = document.body();
             for (Node node : fragmentNodes) {
@@ -263,7 +263,7 @@ public abstract class BootstrapHandler implements RequestHandler {
             WrappedResponse response, Application application, Integer rootId) {
         BootstrapContext context = new BootstrapContext(response,
                 new BootstrapFragmentResponse(this, request,
-                        new ArrayList<Node>(), application, rootId));
+                        application, rootId, new ArrayList<Node>()));
         return context;
     }
 
diff --git a/server/src/com/vaadin/terminal/gwt/server/BootstrapListener.java b/server/src/com/vaadin/terminal/gwt/server/BootstrapListener.java
index d80e626cc1..662e0573e2 100644
--- a/server/src/com/vaadin/terminal/gwt/server/BootstrapListener.java
+++ b/server/src/com/vaadin/terminal/gwt/server/BootstrapListener.java
@@ -6,8 +6,44 @@ package com.vaadin.terminal.gwt.server;
 
 import java.util.EventListener;
 
+import javax.portlet.RenderResponse;
+
+/**
+ * Event listener notified when the bootstrap HTML is about to be generated and
+ * send to the client. The bootstrap HTML is first constructed as an in-memory
+ * DOM representation which registered listeners can modify before the final
+ * HTML is generated.
+ * 
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
 public interface BootstrapListener extends EventListener {
+    /**
+     * Lets this listener make changes to the fragment that makes up the actual
+     * Vaadin application. In a typical Servlet deployment, this is the contents
+     * of the HTML body tag. In a typical Portlet deployment, this is the HTML
+     * that will be returned in a {@link RenderResponse}.
+     * 
+     * @param response
+     *            the bootstrap response that can modified to cause changes in
+     *            the generated HTML.
+     */
     public void modifyBootstrapFragment(BootstrapFragmentResponse response);
 
+    /**
+     * Lets this listener make changes to the overall HTML document that will be
+     * used as the initial HTML page in a typical Servlet deployment as well as
+     * the HTTP headers in the response serving the initial HTML. In cases where
+     * a full HTML document is not generated, this method will not be invoked.
+     * <p>
+     * If a full page is being generated, this method is invoked after
+     * {@link #modifyBootstrapFragment(BootstrapFragmentResponse)} has been
+     * invoked for all registered listeners.
+     * 
+     * @param response
+     *            the bootstrap response that can be modified to cause change in
+     *            the generate HTML and in the HTTP headers of the response.
+     */
     public void modifyBootstrapPage(BootstrapPageResponse response);
 }
diff --git a/server/src/com/vaadin/terminal/gwt/server/BootstrapPageResponse.java b/server/src/com/vaadin/terminal/gwt/server/BootstrapPageResponse.java
index 802238ac62..f72522a801 100644
--- a/server/src/com/vaadin/terminal/gwt/server/BootstrapPageResponse.java
+++ b/server/src/com/vaadin/terminal/gwt/server/BootstrapPageResponse.java
@@ -10,28 +10,91 @@ import org.jsoup.nodes.Document;
 
 import com.vaadin.Application;
 import com.vaadin.terminal.WrappedRequest;
+import com.vaadin.terminal.WrappedResponse;
 
+/**
+ * A representation of a bootstrap page being generated. The bootstrap page
+ * contains of the full DOM of the HTML document as well as the HTTP headers
+ * that will be included in the corresponding HTTP response.
+ * 
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
 public class BootstrapPageResponse extends BootstrapResponse {
 
     private final Map<String, Object> headers;
     private final Document document;
 
+    /**
+     * Crate a new bootstrap page response.
+     * 
+     * @see BootstrapResponse#BootstrapResponse(BootstrapHandler,
+     *      WrappedRequest, Application, Integer)
+     * 
+     * @param handler
+     *            the bootstrap handler that is firing the event
+     * @param request
+     *            the wrapped request for which the bootstrap page should be
+     *            generated
+     * @param application
+     *            the application for which the bootstrap page should be
+     *            generated
+     * @param rootId
+     *            the generated id of the Root that will be displayed on the
+     *            page
+     * @param document
+     *            the DOM document making up the HTML page
+     * @param headers
+     *            a map into which header data can be added
+     */
     public BootstrapPageResponse(BootstrapHandler handler,
-            WrappedRequest request, Document document,
-            Map<String, Object> headers, Application application, Integer rootId) {
+            WrappedRequest request, Application application, Integer rootId,
+            Document document, Map<String, Object> headers) {
         super(handler, request, application, rootId);
         this.headers = headers;
         this.document = document;
     }
 
+    /**
+     * Sets a header value that will be added to the HTTP response. If the
+     * header had already been set, the new value overwrites the previous one.
+     * 
+     * @see WrappedResponse#setHeader(String, String)
+     * 
+     * @param name
+     *            the name of the header
+     * @param value
+     *            the header value
+     */
     public void setHeader(String name, String value) {
         headers.put(name, value);
     }
 
+    /**
+     * Properly formats a timestamp as a date in a header that will be included
+     * in the HTTP response. If the header had already been set, the new value
+     * overwrites the previous one.
+     * 
+     * @see #setHeader(String, String)
+     * @see WrappedResponse#setDateHeader(String, long)
+     * 
+     * @param name
+     *            the name of the header
+     * @param timestamp
+     *            the number of milliseconds since epoch
+     */
     public void setDateHeader(String name, long timestamp) {
         headers.put(name, Long.valueOf(timestamp));
     }
 
+    /**
+     * Gets the document node representing the root of the DOM hierarchy that
+     * will be used to generate the HTML page. Changes to the document will be
+     * reflected in the HTML.
+     * 
+     * @return the document node
+     */
     public Document getDocument() {
         return document;
     }
diff --git a/server/src/com/vaadin/terminal/gwt/server/BootstrapResponse.java b/server/src/com/vaadin/terminal/gwt/server/BootstrapResponse.java
index 88bd58593d..ea8d825e96 100644
--- a/server/src/com/vaadin/terminal/gwt/server/BootstrapResponse.java
+++ b/server/src/com/vaadin/terminal/gwt/server/BootstrapResponse.java
@@ -7,14 +7,38 @@ package com.vaadin.terminal.gwt.server;
 import java.util.EventObject;
 
 import com.vaadin.Application;
+import com.vaadin.RootRequiresMoreInformationException;
 import com.vaadin.terminal.WrappedRequest;
 import com.vaadin.ui.Root;
 
+/**
+ * Base class providing common functionality used in different bootstrap
+ * modification events.
+ * 
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
 public abstract class BootstrapResponse extends EventObject {
     private final WrappedRequest request;
     private final Application application;
     private final Integer rootId;
 
+    /**
+     * Creates a new bootstrap event.
+     * 
+     * @param handler
+     *            the bootstrap handler that is firing the event
+     * @param request
+     *            the wrapped request for which the bootstrap page should be
+     *            generated
+     * @param application
+     *            the application for which the bootstrap page should be
+     *            generated
+     * @param rootId
+     *            the generated id of the Root that will be displayed on the
+     *            page
+     */
     public BootstrapResponse(BootstrapHandler handler, WrappedRequest request,
             Application application, Integer rootId) {
         super(handler);
@@ -23,22 +47,64 @@ public abstract class BootstrapResponse extends EventObject {
         this.rootId = rootId;
     }
 
+    /**
+     * Gets the bootstrap handler that fired this event
+     * 
+     * @return the bootstrap handler that fired this event
+     */
     public BootstrapHandler getBootstrapHandler() {
         return (BootstrapHandler) getSource();
     }
 
+    /**
+     * Gets the request for which the generated bootstrap HTML will be the
+     * response. This can be used to read request headers and other additional
+     * information. Please note that {@link WrappedRequest#getBrowserDetails()}
+     * will not be available because the bootstrap page is generated before the
+     * bootstrap javascript has had a chance to send any information back to the
+     * server.
+     * 
+     * @return the wrapped request that is being handled
+     */
     public WrappedRequest getRequest() {
         return request;
     }
 
+    /**
+     * Gets the application to which the rendered view belongs.
+     * 
+     * @return the application
+     */
     public Application getApplication() {
         return application;
     }
 
+    /**
+     * Gets the root id that has been generated for this response. Please note
+     * that if {@link Application#isRootPreserved()} is enabled, a previously
+     * created Root with a different id might eventually end up being used.
+     * 
+     * @return the root id
+     */
     public Integer getRootId() {
         return rootId;
     }
 
+    /**
+     * Gets the Root for which this page is being rendered, if available. Some
+     * features of the framework will postpone the Root selection until after
+     * the bootstrap page has been rendered and required information from the
+     * browser has been sent back. This method will return <code>null</code> if
+     * no Root instance is yet available.
+     * 
+     * @see Application#isRootPreserved()
+     * @see Application#getRoot(WrappedRequest)
+     * @see RootRequiresMoreInformationException
+     * 
+     * @return The Root that will be displayed in the page being generated, or
+     *         <code>null</code> if all required information is not yet
+     *         available.
+     */
     public Root getRoot() {
         return Root.getCurrent();
     }