diff options
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(); } |