From: Henri Sara Date: Tue, 24 Nov 2009 07:01:02 +0000 (+0000) Subject: Portlet 2.0 partial review, some javadoc, removed debug printouts and minor refactoring X-Git-Tag: 6.7.0.beta1~2266^2~2 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=f1af8c5dc80eb032a1a58065c3ee860945458ace;p=vaadin-framework.git Portlet 2.0 partial review, some javadoc, removed debug printouts and minor refactoring svn changeset:9965/svn branch:portlet_2.0 --- diff --git a/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java b/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java index 8ea94fcc6b..d461d2c6ca 100755 --- a/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java +++ b/src/com/vaadin/terminal/gwt/client/ApplicationConnection.java @@ -39,9 +39,23 @@ import com.vaadin.terminal.gwt.client.ui.VContextMenu; import com.vaadin.terminal.gwt.client.ui.VNotification; import com.vaadin.terminal.gwt.client.ui.VView; import com.vaadin.terminal.gwt.client.ui.VNotification.HideEvent; +import com.vaadin.terminal.gwt.server.AbstractCommunicationManager; /** - * Entry point classes define onModuleLoad(). + * This is the client side communication "engine", managing client-server + * communication with its server side counterpart + * {@link AbstractCommunicationManager}. + * + * Client-side widgets receive updates from the corresponding server-side + * components as calls to + * {@link Paintable#updateFromUIDL(UIDL, ApplicationConnection)} (not to be + * confused with the server side interface {@link com.vaadin.terminal.Paintable} + * ). Any client-side changes (typically resulting from user actions) are sent + * back to the server as variable changes (see {@link #updateVariable()}). + * + * TODO document better + * + * Entry point classes (widgetsets) define onModuleLoad(). */ public class ApplicationConnection { private static final String MODIFIED_CLASSNAME = "v-modified"; @@ -202,7 +216,7 @@ public class ApplicationConnection { *
  • vaadin.postRequestHooks is a map of functions which gets * called after each XHR made by vaadin application. Note, that it is * attaching js functions responsibility to create the variable like this: - * + * * 
          * if(!vaadin.postRequestHooks) {vaadin.postRequestHooks = new Object();}
      * postRequestHooks.myHook = function(appId) {
@@ -213,7 +227,7 @@ public class ApplicationConnection {
      *
    First parameter passed to these functions is the identifier * of Vaadin application that made the request. * - * + * * TODO make this multi-app aware */ private native void initializeClientHooks() @@ -244,7 +258,7 @@ public class ApplicationConnection { /** * Runs possibly registered client side post request hooks. This is expected * to be run after each uidl request made by Vaadin application. - * + * * @param appId */ private static native void runPostRequestHooks(String appId) @@ -267,7 +281,7 @@ public class ApplicationConnection { /** * Checks if client side is in debug mode. Practically this is invoked by * adding ?debug parameter to URI. - * + * * @return true if client side is currently been debugged */ public native static boolean isDebugMode() @@ -448,7 +462,7 @@ public class ApplicationConnection { /** * Shows the communication error notification. The 'details' only go to the * console for now. - * + * * @param details * Optional details for debugging. */ @@ -530,7 +544,7 @@ public class ApplicationConnection { /** * This method is called after applying uidl change set to application. - * + * * It will clean current and queued variable change sets. And send next * change set if it exists. */ @@ -550,7 +564,7 @@ public class ApplicationConnection { /** * Cleans given queue of variable changes of such changes that came from * components that do not exist anymore. - * + * * @param variableBurst */ private void cleanVariableBurst(ArrayList variableBurst) { @@ -907,7 +921,7 @@ public class ApplicationConnection { /** * Returns Paintable element by its id - * + * * @param id * Paintable ID */ @@ -941,12 +955,12 @@ public class ApplicationConnection { /** * This method sends currently queued variable changes to server. It is * called when immediate variable update must happen. - * + * * To ensure correct order for variable changes (due servers multithreading * or network), we always wait for active request to be handler before * sending a new one. If there is an active request, we will put varible * "burst" to queue that will be purged after current request is handled. - * + * */ @SuppressWarnings("unchecked") public void sendPendingVariableChanges() { @@ -968,11 +982,11 @@ public class ApplicationConnection { /** * Build the variable burst and send it to server. - * + * * When sync is forced, we also force sending of all pending variable-bursts * at the same time. This is ok as we can assume that DOM will never be * updated after this. - * + * * @param pendingVariables * Vector of variable changes to send * @param forceSync @@ -1061,9 +1075,9 @@ public class ApplicationConnection { /** * Update generic component features. - * + * *

    Selecting correct implementation

    - * + * *

    * The implementation of a component depends on many properties, including * styles, component features, etc. Sometimes the user changes those @@ -1071,21 +1085,21 @@ public class ApplicationConnection { * the beginning of your updateFromUIDL -method automatically replaces your * component with more appropriate if the requested implementation changes. *

    - * + * *

    Caption, icon, error messages and description

    - * + * *

    * Component can delegate management of caption, icon, error messages and * description to parent layout. This is optional an should be decided by * component author *

    - * + * *

    Component visibility and disabling

    - * + * * This method will manage component visibility automatically and if * component is an instanceof FocusWidget, also handle component disabling * when needed. - * + * * @param component * Widget to be updated, expected to implement an instance of * Paintable @@ -1094,7 +1108,7 @@ public class ApplicationConnection { * @param manageCaption * True if you want to delegate caption, icon, description and * error message management to parent. - * + * * @return Returns true iff no further painting is needed by caller */ public boolean updateComponent(Widget component, UIDL uidl, @@ -1304,7 +1318,7 @@ public class ApplicationConnection { /** * Traverses recursively child widgets until ContainerResizedListener child * widget is found. They will delegate it further if needed. - * + * * @param container */ private boolean runningLayout = false; @@ -1367,7 +1381,7 @@ public class ApplicationConnection { /** * Converts relative sizes into pixel sizes. - * + * * @param child * @return true if the child has a relative size */ @@ -1514,7 +1528,7 @@ public class ApplicationConnection { /** * Converts relative sizes into pixel sizes. - * + * * @param child * @return true if the child has a relative size */ @@ -1531,12 +1545,12 @@ public class ApplicationConnection { /** * Get either existing or new Paintable for given UIDL. - * + * * If corresponding Paintable has been previously painted, return it. * Otherwise create and register a new Paintable from UIDL. Caller must * update the returned Paintable from UIDL after it has been connected to * parent. - * + * * @param uidl * UIDL to create Paintable from. * @return Either existing or new Paintable corresponding to UIDL. @@ -1556,7 +1570,7 @@ public class ApplicationConnection { /** * Returns a Paintable element by its root element - * + * * @param element * Root element of the paintable */ @@ -1570,7 +1584,7 @@ public class ApplicationConnection { /** * Singleton method to get instance of app's context menu. - * + * * @return VContextMenu object */ public VContextMenu getContextMenu() { @@ -1586,7 +1600,7 @@ public class ApplicationConnection { * Translates custom protocols in UIDL URI's to be recognizable by browser. * All uri's from UIDL should be routed via this method before giving them * to browser due URI's in UIDL may contain custom protocols like theme://. - * + * * @param uidlUri * Vaadin URI from uidl * @return translated URI ready for browser @@ -1614,7 +1628,7 @@ public class ApplicationConnection { /** * Listens for Notification hide event, and redirects. Used for system * messages, such as session expired. - * + * */ private class NotificationRedirect implements VNotification.EventListener { String url; @@ -1634,9 +1648,9 @@ public class ApplicationConnection { /** * Data showed in tooltips are stored centrilized as it may be needed in * varios place: caption, layouts, and in owner components themselves. - * + * * Updating TooltipInfo is done in updateComponent method. - * + * */ public TooltipInfo getTooltipTitleInfo(Paintable titleOwner, Object key) { if (null == titleOwner) { @@ -1656,9 +1670,9 @@ public class ApplicationConnection { * Component may want to delegate Tooltip handling to client. Layouts add * Tooltip (description, errors) to caption, but some components may want * them to appear one other elements too. - * + * * Events wanted by this handler are same as in Tooltip.TOOLTIP_EVENTS - * + * * @param event * @param owner */ @@ -1671,9 +1685,9 @@ public class ApplicationConnection { * Component may want to delegate Tooltip handling to client. Layouts add * Tooltip (description, errors) to caption, but some components may want * them to appear one other elements too. - * + * * Events wanted by this handler are same as in Tooltip.TOOLTIP_EVENTS - * + * * @param event * @param owner * @param key @@ -1687,7 +1701,7 @@ public class ApplicationConnection { /** * Adds PNG-fix conditionally (only for IE6) to the specified IMG -element. - * + * * @param el * the IMG element to fix */ @@ -1737,7 +1751,7 @@ public class ApplicationConnection { * Reset the name of the current browser-window. This should reflect the * window-name used in the server, but might be different from the * window-object target-name on client. - * + * * @param stringAttribute * New name for the window. */ @@ -1767,14 +1781,14 @@ public class ApplicationConnection { *

    * This method can also be used to deregister tooltips by using null as * tooltip - * + * * @param paintable * Paintable "owning" this tooltip * @param key * key assosiated with given tooltip. Can be any object. For * example a related dom element. Same key must be given for * {@link #handleTooltipEvent(Event, Paintable, Object)} method. - * + * * @param tooltip * the TooltipInfo object containing details shown in tooltip, * null if deregistering tooltip diff --git a/src/com/vaadin/terminal/gwt/client/Paintable.java b/src/com/vaadin/terminal/gwt/client/Paintable.java index d4ff755763..54713bd5b7 100644 --- a/src/com/vaadin/terminal/gwt/client/Paintable.java +++ b/src/com/vaadin/terminal/gwt/client/Paintable.java @@ -1,9 +1,17 @@ -/* +/* @ITMillApache2LicenseForJavaFiles@ */ package com.vaadin.terminal.gwt.client; +/** + * An interface used by client-side widgets or paintable parts to receive + * updates from the corresponding server-side components in the form of + * {@link UIDL}. + * + * Updates can be sent back to the server using the + * {@link ApplicationConnection#updateVariable()} methods. + */ public interface Paintable { public void updateFromUIDL(UIDL uidl, ApplicationConnection client); diff --git a/src/com/vaadin/terminal/gwt/server/AbstractCommunicationManager.java b/src/com/vaadin/terminal/gwt/server/AbstractCommunicationManager.java index f66102fc2e..7e9c04bc26 100644 --- a/src/com/vaadin/terminal/gwt/server/AbstractCommunicationManager.java +++ b/src/com/vaadin/terminal/gwt/server/AbstractCommunicationManager.java @@ -1,4 +1,4 @@ -/* +/* @ITMillApache2LicenseForJavaFiles@ */ @@ -29,12 +29,16 @@ import java.util.GregorianCalendar; import java.util.HashMap; import java.util.HashSet; import java.util.Iterator; -import java.util.LinkedList; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Set; +import javax.portlet.PortletRequest; +import javax.portlet.PortletResponse; +import javax.servlet.ServletRequest; +import javax.servlet.ServletResponse; + import com.vaadin.Application; import com.vaadin.Application.SystemMessages; import com.vaadin.external.org.apache.commons.fileupload.FileItemIterator; @@ -42,14 +46,17 @@ import com.vaadin.external.org.apache.commons.fileupload.FileItemStream; import com.vaadin.external.org.apache.commons.fileupload.FileUpload; import com.vaadin.external.org.apache.commons.fileupload.FileUploadException; import com.vaadin.external.org.apache.commons.fileupload.ProgressListener; +import com.vaadin.terminal.ApplicationResource; import com.vaadin.terminal.DownloadStream; import com.vaadin.terminal.PaintException; +import com.vaadin.terminal.PaintTarget; import com.vaadin.terminal.Paintable; import com.vaadin.terminal.URIHandler; import com.vaadin.terminal.UploadStream; import com.vaadin.terminal.VariableOwner; import com.vaadin.terminal.Paintable.RepaintRequestEvent; import com.vaadin.terminal.Terminal.ErrorEvent; +import com.vaadin.terminal.Terminal.ErrorListener; import com.vaadin.terminal.gwt.client.ApplicationConnection; import com.vaadin.terminal.gwt.server.ComponentSizeValidator.InvalidLayout; import com.vaadin.ui.AbstractField; @@ -59,57 +66,164 @@ import com.vaadin.ui.Window; import com.vaadin.ui.Upload.UploadException; /** - * TODO Document me! + * This is a common base class for the server-side implementations of the + * communication system between the client code (compiled with GWT into + * JavaScript) and the server side components. Its client side counterpart is + * {@link ApplicationConnection}. + * + * A server side component sends its state to the client in a paint request (see + * {@link Paintable} and {@link PaintTarget} on the server side). The client + * widget receives these paint requests as calls to + * {@link com.vaadin.terminal.gwt.client.Paintable#updateFromUIDL()}. The client + * component communicates back to the server by sending a list of variable + * changes (see {@link ApplicationConnection#updateVariable()} and + * {@link VariableOwner#changeVariables(Object, Map)}). + * + * TODO Document better! */ @SuppressWarnings("serial") public abstract class AbstractCommunicationManager implements Paintable.RepaintRequestListener, Serializable { /** - * TODO Document me! - * + * Generic interface of a (HTTP or Portlet) request to the application. + * + * This is a wrapper interface that allows + * {@link AbstractCommunicationManager} to use a unified API. + * + * @see javax.servlet.ServletRequest + * @see javax.portlet.PortletRequest + * * @author peholmst */ protected interface Request { + /** + * Gets a {@link Session} wrapper implementation representing the + * session for which this request was sent. + * + * Multiple Vaadin applications can be associated with a single session. + * + * @return Session + */ public Session getSession(); + /** + * Are the applications in this session running in a portlet or directly + * as servlets. + * + * @return true if in a portlet + */ public boolean isRunningInPortlet(); + /** + * Get the named HTTP or portlet request parameter. + * + * @see javax.servlet.ServletRequest#getParameter(String) + * @see javax.portlet.PortletRequest#getParameter(String) + * + * @param name + * @return + */ public String getParameter(String name); + /** + * Returns the length of the request content that can be read from the + * input stream returned by {@link #getInputStream()}. + * + * @return content length in bytes + */ public int getContentLength(); + /** + * Returns an input stream from which the request content can be read. + * The request content length can be obtained with + * {@link #getContentLength()} without reading the full stream contents. + * + * @return + * @throws IOException + */ public InputStream getInputStream() throws IOException; + /** + * Returns the request identifier that identifies the target Vaadin + * window for the request. + * + * @return String identifier for the request target window + */ public String getRequestID(); + /** + * @see javax.servlet.ServletRequest#getAttribute(String) + * @see javax.portlet.PortletRequest#getAttribute(String) + */ public Object getAttribute(String name); - public void setAttribute(String name, Object o); + /** + * @see javax.servlet.ServletRequest#setAttribute(String, Object) + * @see javax.portlet.PortletRequest#setAttribute(String, Object) + */ + public void setAttribute(String name, Object value); + /** + * Gets the underlying request object. The request is typically either a + * {@link ServletRequest} or a {@link PortletRequest}. + * + * @return wrapped request object + */ public Object getWrappedRequest(); } /** - * TODO Document me! - * + * Generic interface of a (HTTP or Portlet) response from the application. + * + * This is a wrapper interface that allows + * {@link AbstractCommunicationManager} to use a unified API. + * + * @see javax.servlet.ServletResponse + * @see javax.portlet.PortletResponse + * * @author peholmst */ protected interface Response { + /** + * Gets the output stream to which the response can be written. + * + * @return + * @throws IOException + */ public OutputStream getOutputStream() throws IOException; + /** + * Sets the MIME content type for the response to be communicated to the + * browser. + * + * @param type + */ public void setContentType(String type); + /** + * Gets the wrapped response object, usually a class implementing either + * {@link ServletResponse} or {@link PortletResponse}. + * + * @return wrapped request object + */ public Object getWrappedResponse(); } /** + * Generic wrapper interface for a (HTTP or Portlet) session. + * + * Several applications can be associated with a single session. + * * TODO Document me! - * + * + * @see javax.servlet.http.HttpSession + * @see javax.portlet.PortletSession + * * @author peholmst */ protected interface Session { @@ -128,7 +242,7 @@ public abstract class AbstractCommunicationManager implements /** * TODO Document me! - * + * * @author peholmst */ protected interface Callback { @@ -144,10 +258,6 @@ public abstract class AbstractCommunicationManager implements } - // FIXME Create an abstract class with custom Request/Response/Session - // interfaces, then create - // subclasses for servlets and portlets. - private static String GET_PARAM_REPAINT_ALL = "repaintAll"; // flag used in the request to indicate that the security token should be @@ -174,7 +284,7 @@ public abstract class AbstractCommunicationManager implements private static final String GET_PARAM_ANALYZE_LAYOUTS = "analyzeLayouts"; - private final ArrayList dirtyPaintabletSet = new ArrayList(); + private final ArrayList dirtyPaintables = new ArrayList(); private final HashMap paintableIdMap = new HashMap(); @@ -196,7 +306,7 @@ public abstract class AbstractCommunicationManager implements /** * TODO New constructor - document me! - * + * * @param application */ public AbstractCommunicationManager(Application application) { @@ -205,27 +315,28 @@ public abstract class AbstractCommunicationManager implements } /** - * TODO New method - document me! - * - * @return + * Create an upload handler that is appropriate to the context in which the + * application is being run (servlet or portlet). + * + * @return new {@link FileUpload} instance */ protected abstract FileUpload createFileUpload(); /** * TODO New method - document me! - * + * * @param upload * @param request * @return * @throws IOException * @throws FileUploadException */ - protected abstract FileItemIterator getItemIterator(FileUpload upload, + protected abstract FileItemIterator getUploadItemIterator(FileUpload upload, Request request) throws IOException, FileUploadException; /** * TODO New method - document me! - * + * * @param request * @param response * @throws IOException @@ -244,7 +355,7 @@ public abstract class AbstractCommunicationManager implements FileItemIterator iter; try { - iter = getItemIterator(upload, request); + iter = getUploadItemIterator(upload, request); /* * ATM this loop is run only once as we are uploading one file per * request. @@ -259,8 +370,6 @@ public abstract class AbstractCommunicationManager implements // ignored, upload requests contains only files } else { final String pid = name.split("_")[0]; - // TODO Remove debug printlns - System.out.println("Looking up upload component with PID " + pid); final Upload uploadComponent = (Upload) idPaintableMap .get(pid); if (uploadComponent == null) { @@ -308,7 +417,7 @@ public abstract class AbstractCommunicationManager implements synchronized (application) { handleChangeVariablesError(application, uploadComponent, e, - new HashMap()); + new HashMap()); } } } @@ -319,7 +428,14 @@ public abstract class AbstractCommunicationManager implements sendUploadResponse(request, response); } - + + /** + * TODO document + * + * @param request + * @param response + * @throws IOException + */ protected void sendUploadResponse(Request request, Response response) throws IOException { response.setContentType("text/html"); final OutputStream out = response.getOutputStream(); @@ -331,8 +447,20 @@ public abstract class AbstractCommunicationManager implements } /** - * TODO New method - document me! - * + * Internally process a UIDL request from the client. + * + * This method calls + * {@link #handleVariables(Request, Response, Callback, Application, Window)} + * to process any changes to variables by the client and then repaints + * affected components using {@link #paintAfterVariableChanges()}. + * + * Also, some cleanup is done when a request arrives for an application that + * has already been closed. + * + * The method handleUidlRequest(...) in subclasses should call this method. + * + * TODO better documentation + * * @param request * @param response * @param callback @@ -417,7 +545,7 @@ public abstract class AbstractCommunicationManager implements } - paintAfterVariablechanges(request, response, callback, repaintAll, + paintAfterVariableChanges(request, response, callback, repaintAll, outWriter, window, analyzeLayouts); if (closingWindowName != null) { @@ -430,7 +558,20 @@ public abstract class AbstractCommunicationManager implements out.close(); } - private void paintAfterVariablechanges(Request request, Response response, + /** + * TODO document + * + * @param request + * @param response + * @param callback + * @param repaintAll + * @param outWriter + * @param window + * @param analyzeLayouts + * @throws PaintException + * @throws IOException + */ + private void paintAfterVariableChanges(Request request, Response response, Callback callback, boolean repaintAll, final PrintWriter outWriter, Window window, boolean analyzeLayouts) throws PaintException, IOException { @@ -527,7 +668,7 @@ public abstract class AbstractCommunicationManager implements if (p.getApplication() == null) { idPaintableMap.remove(paintableIdMap.get(p)); it.remove(); - dirtyPaintabletSet.remove(p); + dirtyPaintables.remove(p); p.removeListener(this); } } @@ -763,6 +904,7 @@ public abstract class AbstractCommunicationManager implements outWriter.print(" }"); } + // add any pending locale definitions requested by the client printLocaleDeclarations(outWriter); outWriter.print("}]"); @@ -773,10 +915,12 @@ public abstract class AbstractCommunicationManager implements } /** + * TODO document + * * If this method returns false, something was submitted that we did not * expect; this is probably due to the client being out-of-sync and sending * variable changes for non-existing pids - * + * * @return true if successful, false if there was an inconsistency */ private boolean handleVariables(Request request, Response response, @@ -833,6 +977,9 @@ public abstract class AbstractCommunicationManager implements final VariableOwner owner = (VariableOwner) idPaintableMap .get(variable[VAR_PID]); if (owner != null && owner.isEnabled()) { + // TODO this should be Map, but the + // VariableOwner API does not guarantee the key is a + // string Map m; if (nextVariable != null && variable[VAR_PID] @@ -845,7 +992,8 @@ public abstract class AbstractCommunicationManager implements variable[VAR_VALUE])); } else { // use optimized single value map - m = new SingleValueMap(variable[VAR_NAME], + m = Collections.singletonMap( + (Object) variable[VAR_NAME], convertVariableValue(variable[VAR_TYPE] .charAt(0), variable[VAR_VALUE])); } @@ -923,7 +1071,7 @@ public abstract class AbstractCommunicationManager implements final PrintWriter outWriter = new PrintWriter( new CharArrayWriter()); - paintAfterVariablechanges(request, response, callback, + paintAfterVariableChanges(request, response, callback, true, outWriter, window, false); } @@ -936,7 +1084,7 @@ public abstract class AbstractCommunicationManager implements /** * Reads the request data from the Request and returns it converted to an * UTF-8 string. - * + * * @param request * @return * @throws IOException @@ -978,8 +1126,26 @@ public abstract class AbstractCommunicationManager implements } + /** + * Handles an error (exception) that occurred when processing variable + * changes from the client or a failure of a file upload. + * + * For {@link AbstractField} components, + * {@link AbstractField#handleError(com.vaadin.ui.AbstractComponent.ComponentErrorEvent)} + * is called. In all other cases (or if the field does not handle the + * error), {@link ErrorListener#terminalError(ErrorEvent)} for the + * application error handler is called. + * + * @param application + * @param owner + * component that the error concerns + * @param e + * exception that occurred + * @param m + * map from variable names to values + */ private void handleChangeVariablesError(Application application, - Component owner, Exception e, Map m) { + Component owner, Exception e, Map m) { boolean handled = false; ChangeVariablesErrorEvent errorEvent = new ChangeVariablesErrorEvent( owner, e, m); @@ -1037,6 +1203,13 @@ public abstract class AbstractCommunicationManager implements return val; } + /** + * Prints the queued (pending) locale definitions to a {@link PrintWriter} in + * a (UIDL) format that can be sent to the client and used there in formatting + * dates, times etc. + * + * @param outWriter + */ private void printLocaleDeclarations(PrintWriter outWriter) { /* * ----------------------------- Sending Locale sensitive date @@ -1143,7 +1316,7 @@ public abstract class AbstractCommunicationManager implements final String timeformat = df.substring(timeStart, df.length()); /* * Doesn't return second or milliseconds. - * + * * We use timeformat to determine 12/24-hour clock */ final boolean twelve_hour_clock = timeformat.indexOf("a") > -1; @@ -1169,7 +1342,7 @@ public abstract class AbstractCommunicationManager implements /** * TODO New method - document me! - * + * * @param request * @param callback * @param application @@ -1256,7 +1429,11 @@ public abstract class AbstractCommunicationManager implements /** * Ends the Application. - * + * + * The browser is redirected to the Application logout URL set with + * {@link Application#setLogoutURL(String)}, or to the application URL if no + * logout URL is given. + * * @param request * the request instance. * @param response @@ -1291,14 +1468,12 @@ public abstract class AbstractCommunicationManager implements /** * Gets the Paintable Id. If Paintable has debug id set it will be used * prefixed with "PID_S". Otherwise a sequenced ID is created. - * + * * @param paintable * @return the paintable Id. */ public String getPaintableId(Paintable paintable) { - // TODO Remove debug println:s from this method - //System.out.println("getPaintableId: " + paintable + " (" + paintable.getClass().getName() + ")"); - + String id = paintableIdMap.get(paintable); if (id == null) { // use testing identifier as id if set @@ -1308,7 +1483,6 @@ public abstract class AbstractCommunicationManager implements } else { id = "PID_S" + id; } - //System.out.println(" id: " + id); Paintable old = idPaintableMap.put(id, paintable); if (old != null && old != paintable) { /* @@ -1340,21 +1514,21 @@ public abstract class AbstractCommunicationManager implements /** * Returns dirty components which are in given window. Components in an * invisible subtrees are omitted. - * + * * @param w * root window for which dirty components is to be fetched * @return */ private ArrayList getDirtyVisibleComponents(Window w) { final ArrayList resultset = new ArrayList( - dirtyPaintabletSet); + dirtyPaintables); // The following algorithm removes any components that would be painted // as a direct descendant of other components from the dirty components // list. The result is that each component should be painted exactly // once and any unmodified components will be painted as "cached=true". - for (final Iterator i = dirtyPaintabletSet.iterator(); i + for (final Iterator i = dirtyPaintables.iterator(); i .hasNext();) { final Paintable p = i.next(); if (p instanceof Component) { @@ -1375,7 +1549,7 @@ public abstract class AbstractCommunicationManager implements && !component.getParent().isVisible()) { /* * Do not return components in an invisible subtree. - * + * * Components that are invisible in visible subree, must * be rendered (to let client know that they need to be * hidden). @@ -1394,112 +1568,24 @@ public abstract class AbstractCommunicationManager implements */ public void repaintRequested(RepaintRequestEvent event) { final Paintable p = event.getPaintable(); - if (!dirtyPaintabletSet.contains(p)) { - dirtyPaintabletSet.add(p); + if (!dirtyPaintables.contains(p)) { + dirtyPaintables.add(p); } } /** - * - * @param p + * Internally mark a {@link Paintable} as painted and start collecting new + * repaint requests for it. + * + * @param paintable */ - private void paintablePainted(Paintable p) { - dirtyPaintabletSet.remove(p); - p.requestRepaintRequests(); - } - - private final class SingleValueMap implements Map, - Serializable { - - private final String name; - - private final Object value; - - private SingleValueMap(String name, Object value) { - this.name = name; - this.value = value; - } - - public void clear() { - throw new UnsupportedOperationException(); - } - - public boolean containsKey(Object key) { - if (name == null) { - return key == null; - } - return name.equals(key); - } - - public boolean containsValue(Object v) { - if (value == null) { - return v == null; - } - return value.equals(v); - } - - public Set> entrySet() { - final Set> s = new HashSet>(); - s.add(new Map.Entry() { - - public Object getKey() { - return name; - } - - public Object getValue() { - return value; - } - - public Object setValue(Object value) { - throw new UnsupportedOperationException(); - } - }); - return s; - } - - public Object get(Object key) { - if (!name.equals(key)) { - return null; - } - return value; - } - - public boolean isEmpty() { - return false; - } - - public Set keySet() { - final Set s = new HashSet(); - s.add(name); - return s; - } - - public Object put(Object key, Object value) { - throw new UnsupportedOperationException(); - } - - public void putAll(Map t) { - throw new UnsupportedOperationException(); - } - - public Object remove(Object key) { - throw new UnsupportedOperationException(); - } - - public int size() { - return 1; - } - - public Collection values() { - final LinkedList s = new LinkedList(); - s.add(value); - return s; - - } + private void paintablePainted(Paintable paintable) { + dirtyPaintables.remove(paintable); + paintable.requestRepaintRequests(); } /** - * Implementation of URIHandler.ErrorEvent interface. + * Implementation of {@link URIHandler.ErrorEvent} interface. */ public class URIHandlerErrorImpl implements URIHandler.ErrorEvent, Serializable { @@ -1509,7 +1595,7 @@ public abstract class AbstractCommunicationManager implements private final Throwable throwable; /** - * + * * @param owner * @param throwable */ @@ -1533,6 +1619,17 @@ public abstract class AbstractCommunicationManager implements } } + /** + * Queues a locale to be sent to the client (browser) for date and time + * entry etc. All locale specific information is derived from server-side + * {@link Locale} instances and sent to the client when needed, eliminating + * the need to use the {@link Locale} class and all the framework behind + * it on the client. + * + * @see Locale#toString() + * + * @param value + */ public void requireLocale(String value) { if (locales == null) { locales = new ArrayList(); @@ -1544,6 +1641,15 @@ public abstract class AbstractCommunicationManager implements } } + /** + * Constructs a {@link Locale} instance to be sent to the client based on a + * short locale description string. + * + * @see #requireLocale(String) + * + * @param value + * @return + */ private Locale generateLocale(String value) { final String[] temp = value.split("_"); if (temp.length == 1) { @@ -1581,7 +1687,7 @@ public abstract class AbstractCommunicationManager implements /** * Helper method to test if a component contains another - * + * * @param parent * @param child */ @@ -1606,19 +1712,22 @@ public abstract class AbstractCommunicationManager implements } /** - * Handles the requested URI. An application can add handlers to do special - * processing, when a certain URI is requested. The handlers are invoked - * before any windows URIs are processed and if a DownloadStream is returned - * it is sent to the client. - * - * @param application - * the Application owning the URI. + * Calls the Window URI handler for a request and returns the + * {@link DownloadStream} returned by the handler. + * + * If the window is the main window of an application, the (deprecated) + * {@link Application#handleURI(java.net.URL, String)} is called first to + * handle {@link ApplicationResource}s, and the window handler is only + * called if it returns null. + * + * @param window + * the target window of the request * @param request - * the request instance. + * the request instance * @param response - * the response to write to. - * @return boolean true if the request was handled and further - * processing should be suppressed, false otherwise. + * the response to write to + * @return DownloadStream if the request was handled and further processing + * should be suppressed, null otherwise. * @see com.vaadin.terminal.URIHandler */ protected DownloadStream handleURI(Window window, Request request, @@ -1690,7 +1799,7 @@ public abstract class AbstractCommunicationManager implements /** * Helper class for terminal to keep track of data that client is expected * to know. - * + * * TODO make customlayout templates (from theme) to be cached here. */ class OpenWindowCache implements Serializable { @@ -1698,7 +1807,7 @@ public abstract class AbstractCommunicationManager implements private Set res = new HashSet(); /** - * + * * @param paintable * @return true if the given class was added to cache */ diff --git a/src/com/vaadin/terminal/gwt/server/CommunicationManager.java b/src/com/vaadin/terminal/gwt/server/CommunicationManager.java index 5a467c35f7..7e9afd358f 100644 --- a/src/com/vaadin/terminal/gwt/server/CommunicationManager.java +++ b/src/com/vaadin/terminal/gwt/server/CommunicationManager.java @@ -1,4 +1,4 @@ -/* +/* @ITMillApache2LicenseForJavaFiles@ */ @@ -18,13 +18,18 @@ import com.vaadin.external.org.apache.commons.fileupload.FileItemIterator; import com.vaadin.external.org.apache.commons.fileupload.FileUpload; import com.vaadin.external.org.apache.commons.fileupload.FileUploadException; import com.vaadin.external.org.apache.commons.fileupload.servlet.ServletFileUpload; +import com.vaadin.terminal.ApplicationResource; import com.vaadin.terminal.DownloadStream; import com.vaadin.ui.Window; /** * Application manager processes changes and paints for single application * instance. + * + * This class handles applications running as servlets. * + * @see AbstractCommunicationManager + * * @author IT Mill Ltd. * @version * @VERSION@ @@ -33,6 +38,11 @@ import com.vaadin.ui.Window; @SuppressWarnings("serial") public class CommunicationManager extends AbstractCommunicationManager { + /** + * Concrete wrapper class for {@link HttpServletRequest}. + * + * @see Request + */ private static class HttpServletRequestWrapper implements Request { private final HttpServletRequest request; @@ -78,6 +88,11 @@ public class CommunicationManager extends AbstractCommunicationManager { } } + /** + * Concrete wrapper class for {@link HttpServletResponse}. + * + * @see Response + */ private static class HttpServletResponseWrapper implements Response { private final HttpServletResponse response; @@ -100,6 +115,11 @@ public class CommunicationManager extends AbstractCommunicationManager { } + /** + * Concrete wrapper class for {@link HttpSession}. + * + * @see Session + */ private static class HttpSessionWrapper implements Session { private final HttpSession session; @@ -174,7 +194,7 @@ public class CommunicationManager extends AbstractCommunicationManager { /** * TODO New constructor - document me! - * + * * @param application */ public CommunicationManager(Application application) { @@ -187,7 +207,7 @@ public class CommunicationManager extends AbstractCommunicationManager { } @Override - protected FileItemIterator getItemIterator(FileUpload upload, + protected FileItemIterator getUploadItemIterator(FileUpload upload, Request request) throws IOException, FileUploadException { return ((ServletFileUpload) upload) .getItemIterator((HttpServletRequest) request @@ -196,7 +216,9 @@ public class CommunicationManager extends AbstractCommunicationManager { /** * Handles file upload request submitted via Upload component. - * + * + * TODO document + * * @param request * @param response * @throws IOException @@ -211,7 +233,9 @@ public class CommunicationManager extends AbstractCommunicationManager { /** * Handles UIDL request - * + * + * TODO document + * * @param request * @param response * @throws IOException @@ -227,9 +251,9 @@ public class CommunicationManager extends AbstractCommunicationManager { } /** - * Gets the existing application or create a new one. Get a window within an - * application based on the requested URI. - * + * Gets the existing application or creates a new one. Get a window within + * an application based on the requested URI. + * * @param request * the HTTP Request. * @param application @@ -237,7 +261,7 @@ public class CommunicationManager extends AbstractCommunicationManager { * @param assumedWindow * if the window has been already resolved once, this parameter * must contain the window. - * @return Window mathing the given URI or null if not found. + * @return Window matching the given URI or null if not found. * @throws ServletException * if an exception has occurred that interferes with the * servlet's normal operation. @@ -252,8 +276,17 @@ public class CommunicationManager extends AbstractCommunicationManager { } /** - * TODO Document me! - * + * Calls the Window URI handler for a request and returns the + * {@link DownloadStream} returned by the handler. + * + * If the window is the main window of an application, the deprecated + * {@link Application#handleURI(java.net.URL, String)} is called first to + * handle {@link ApplicationResource}s and the window handler is only called + * if it returns null. + * + * @see AbstractCommunicationManager#handleURI(Window, Request, Response, + * Callback) + * * @param window * @param request * @param response diff --git a/src/com/vaadin/terminal/gwt/server/JsonPaintTarget.java b/src/com/vaadin/terminal/gwt/server/JsonPaintTarget.java index 09862f66b0..7a653e93e9 100644 --- a/src/com/vaadin/terminal/gwt/server/JsonPaintTarget.java +++ b/src/com/vaadin/terminal/gwt/server/JsonPaintTarget.java @@ -1,4 +1,4 @@ -/* +/* @ITMillApache2LicenseForJavaFiles@ */ @@ -32,6 +32,9 @@ import com.vaadin.ui.CustomLayout; /** * User Interface Description Language Target. * + * TODO document better: role of this class, UIDL format, attributes, variables, + * etc. + * * @author IT Mill Ltd. * @version * @VERSION@ @@ -74,7 +77,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Creates a new XMLPrintWriter, without automatic line flushing. - * + * * @param variableMap * @param manager * @param outWriter @@ -102,18 +105,18 @@ public class JsonPaintTarget implements PaintTarget { /** * Prints the element start tag. - * + * * 
          *   Todo:
      *    Checking of input values
-     * 
+     *
      *
    - * + * * @param tagName * the name of the start tag. * @throws PaintException * if the paint operation failed. - * + * */ public void startTag(String tagName, boolean isChildNode) throws PaintException { @@ -146,10 +149,10 @@ public class JsonPaintTarget implements PaintTarget { /** * Prints the element end tag. - * + * * If the parent tag is closed before every child tag is closed an * PaintException is raised. - * + * * @param tag * the name of the end tag. * @throws Paintexception @@ -202,7 +205,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Substitutes the XML sensitive characters with predefined XML entities. - * + * * @param xml * the String to be substituted. * @return A new string instance where all occurrences of XML sensitive @@ -217,12 +220,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Substitutes the XML sensitive characters with predefined XML entities. - * + * * @param xml * the String to be substituted. * @return A new StringBuilder instance where all occurrences of XML * sensitive characters are substituted with entities. - * + * */ static StringBuilder escapeXML(StringBuilder xml) { if (xml == null || xml.length() <= 0) { @@ -293,7 +296,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Substitutes a XML sensitive character with predefined XML entity. - * + * * @param c * the Character to be replaced with an entity. * @return String of the entity or null if character is not to be replaced @@ -318,11 +321,11 @@ public class JsonPaintTarget implements PaintTarget { /** * Prints XML-escaped text. - * + * * @param str * @throws PaintException * if the paint operation failed. - * + * */ public void addText(String str) throws PaintException { tag.addData("\"" + escapeJSON(str) + "\""); @@ -331,7 +334,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a boolean attribute to component. Atributes must be added before any * content is written. - * + * * @param name * the Attribute name. * @param value @@ -346,12 +349,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a resource attribute to component. Attributes must be added before * any content is written. - * + * * @param name * the Attribute name. * @param value * the Attribute value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -395,12 +398,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a integer attribute to component. Atributes must be added before any * content is written. - * + * * @param name * the Attribute name. * @param value * the Attribute value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -411,12 +414,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a long attribute to component. Atributes must be added before any * content is written. - * + * * @param name * the Attribute name. * @param value * the Attribute value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -427,12 +430,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a float attribute to component. Atributes must be added before any * content is written. - * + * * @param name * the Attribute name. * @param value * the Attribute value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -443,12 +446,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a double attribute to component. Atributes must be added before any * content is written. - * + * * @param name * the Attribute name. * @param value * the Attribute value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -459,12 +462,12 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a string attribute to component. Atributes must be added before any * content is written. - * + * * @param name * the String attribute name. * @param value * the String attribute value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -547,14 +550,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a string type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -565,14 +568,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a int type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -583,14 +586,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a long type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -601,14 +604,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a float type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -619,14 +622,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a double type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -637,14 +640,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a boolean type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -655,14 +658,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a string array type variable. - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. * @param value * the Variable initial value. - * + * * @throws PaintException * if the paint operation failed. */ @@ -673,14 +676,14 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds a upload stream type variable. - * + * * TODO not converted for JSON - * + * * @param owner * the Listener for variable changes. * @param name * the Variable name. - * + * * @throws PaintException * if the paint operation failed. */ @@ -693,9 +696,9 @@ public class JsonPaintTarget implements PaintTarget { /** * Prints the single text section. - * + * * Prints full text section. The section data is escaped - * + * * @param sectionTagName * the name of the tag. * @param sectionData @@ -711,7 +714,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds XML directly to UIDL. - * + * * @param xml * the Xml to be added. * @throws PaintException @@ -737,7 +740,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Adds XML section with namespace. - * + * * @param sectionTagName * the name of the tag. * @param sectionData @@ -746,7 +749,7 @@ public class JsonPaintTarget implements PaintTarget { * the namespace to be added. * @throws PaintException * if the paint operation failed. - * + * * @see com.vaadin.terminal.PaintTarget#addXMLSection(String, String, * String) */ @@ -773,7 +776,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Gets the UIDL already printed to stream. Paint target must be closed * before the getUIDL can be called. - * + * * @return the UIDL. */ public String getUIDL() { @@ -789,7 +792,7 @@ public class JsonPaintTarget implements PaintTarget { * getUIDL can be called. Subsequent attempts to write to paint * target. If the target was already closed, call to this function is * ignored. will generate an exception. - * + * * @throws PaintException * if the paint operation failed. */ @@ -810,7 +813,7 @@ public class JsonPaintTarget implements PaintTarget { /* * (non-Javadoc) - * + * * @see com.vaadin.terminal.PaintTarget#startTag(com.vaadin.terminal * .Paintable, java.lang.String) */ @@ -850,7 +853,7 @@ public class JsonPaintTarget implements PaintTarget { /* * (non-Javadoc) - * + * * @see com.vaadin.terminal.PaintTarget#addCharacterData(java.lang.String ) */ public void addCharacterData(String text) throws PaintException { @@ -862,9 +865,9 @@ public class JsonPaintTarget implements PaintTarget { /** * This is basically a container for UI components variables, that will be * added at the end of JSON object. - * + * * @author mattitahvonen - * + * */ class JsonTag implements Serializable { boolean firstField = false; @@ -935,7 +938,7 @@ public class JsonPaintTarget implements PaintTarget { } /** - * + * * @param s * json string, object or array */ @@ -1143,7 +1146,7 @@ public class JsonPaintTarget implements PaintTarget { /** * Method to check if paintable is already painted into this target. - * + * * @param p * @return true if is not yet painted into this target and is connected to * app diff --git a/src/com/vaadin/terminal/gwt/server/PortletCommunicationManager.java b/src/com/vaadin/terminal/gwt/server/PortletCommunicationManager.java index 1c0ab75171..679468dd0b 100644 --- a/src/com/vaadin/terminal/gwt/server/PortletCommunicationManager.java +++ b/src/com/vaadin/terminal/gwt/server/PortletCommunicationManager.java @@ -177,7 +177,7 @@ public class PortletCommunicationManager extends AbstractCommunicationManager { } @Override - protected FileItemIterator getItemIterator(FileUpload upload, + protected FileItemIterator getUploadItemIterator(FileUpload upload, Request request) throws IOException, FileUploadException { return ((PortletFileUpload) upload) .getItemIterator((ActionRequest) request.getWrappedRequest()); diff --git a/src/com/vaadin/ui/Window.java b/src/com/vaadin/ui/Window.java index d234f7aaac..55db77df32 100644 --- a/src/com/vaadin/ui/Window.java +++ b/src/com/vaadin/ui/Window.java @@ -1,4 +1,4 @@ -/* +/* @ITMillApache2LicenseForJavaFiles@ */ @@ -29,7 +29,7 @@ import com.vaadin.terminal.gwt.client.ui.VView; /** * Application window component. - * + * * @author IT Mill Ltd. * @version * @VERSION@ @@ -126,16 +126,16 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a new empty unnamed window with default layout. - * + * *

    * To show the window in application, it must be added to application with * Application.addWindow method. *

    - * + * *

    * The windows are scrollable by default. *

    - * + * * @param caption * the Title of the window. */ @@ -145,16 +145,16 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a new empty window with default layout. - * + * *

    * To show the window in application, it must be added to application with * Application.addWindow method. *

    - * + * *

    * The windows are scrollable by default. *

    - * + * * @param caption * the Title of the window. */ @@ -164,16 +164,16 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a new window. - * + * *

    * To show the window in application, it must be added to application with * Application.addWindow method. *

    - * + * *

    * The windows are scrollable by default. *

    - * + * * @param caption * the Title of the window. * @param layout @@ -187,7 +187,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the terminal type. - * + * * @return the Value of property terminal. */ public Terminal getTerminal() { @@ -200,7 +200,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Gets the window of the component. Returns the window where this component * belongs to. If the component does not yet belong to a window the returns * null. - * + * * @return the parent window of the component. */ @Override @@ -212,7 +212,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Gets the application instance of the component. Returns the application * where this component belongs to. If the component does not yet belong to * a application the returns null. - * + * * @return the parent application of the component. */ @Override @@ -225,18 +225,18 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Getter for property parent. - * + * *

    * Parent is the visual parent of a component. Each component can belong to * only one ComponentContainer at time. *

    - * + * *

    * For windows attached directly to the application, parent is * null. For windows inside other windows, parent is the window * containing this window. *

    - * + * * @return the Value of property parent. */ @Override @@ -246,12 +246,12 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Setter for property parent. - * + * *

    * Parent is the visual parent of a component. This is mostly called by * containers add method and should not be called directly *

    - * + * * @param parent * the New value of property parent. */ @@ -265,7 +265,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Adds the new URI handler to this window. For sub-windows, URI handlers * are attached to root level window. - * + * * @param handler * the URI handler to add. */ @@ -289,7 +289,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Removes the given URI handler from this window. - * + * * @param handler * the URI handler to remove. */ @@ -312,13 +312,13 @@ public class Window extends Panel implements URIHandler, ParameterHandler { } /** - * Handles uri recursively. Windows uri handler passes uri to all + * Handles URI recursively. Window URI handler passes the URI to all * {@link URIHandler}s added to it. *

    * Note, that instead of overriding this method developer should consider - * using {@link Window#addURIHandler(URIHandler)} to add uri handler to + * using {@link Window#addURIHandler(URIHandler)} to add URI handler to * Window. - * + * * @param context * @param relativeUri */ @@ -351,7 +351,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Adds the new parameter handler to this window. For sub windows, parameter * handlers are attached to parent windows. - * + * * @param handler * the parameter handler to add. */ @@ -376,7 +376,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Removes the given URI handler from this window. - * + * * @param handler * the parameter handler to remove. */ @@ -415,11 +415,11 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the theme for this window. - * + * *

    * Subwindows do not support themes and thus return theme used by the parent *

    - * + * * @return the Name of the theme used in window. If the theme for this * individual window is not explicitly set, the application theme is * used instead. If application is not assigned the @@ -444,11 +444,11 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the theme for this window. - * + * * Setting theme for subwindows is not supported. - * + * * The terminal will reload its host page on theme changes. - * + * * @param theme * the New theme for this window. Null implies the default theme. */ @@ -463,7 +463,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Paints the content of this component. - * + * * @param event * the Paint Event. * @throws PaintException @@ -594,7 +594,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Opens the given resource in this window. - * + * * @param resource */ public void open(Resource resource) { @@ -613,7 +613,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Opens the given resource in named terminal window. Empty or * null window name results the resource to be opened in this * window. - * + * *

    * Note! When opening browser window with name "_self", client will skip * rendering rest of the changes as it considers them irrelevant. This may @@ -621,7 +621,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * inconsistent state with server in case nothing is actually opened to * window (like if browser decided to download the resource instead of * displaying it). - * + * * @param resource * the resource. * @param windowName @@ -643,7 +643,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Opens the given resource in named terminal window with given size and * border properties. Empty or null window name results the * resource to be opened in this window. - * + * * @param resource * @param windowName * @param width @@ -666,7 +666,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Returns the full url of the window, this returns window specific url even * for the main window. - * + * * @return the URL of the window. */ public URL getURL() { @@ -685,7 +685,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the unique name of the window that indentifies it on the terminal. - * + * *

    * Name identifies the URL used to access application-level windows, but is * not used for windows inside other windows. all application-level windows @@ -697,7 +697,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * inside other windows - these windows show as smaller windows inside those * windows. *

    - * + * * @return the Name of the Window. */ public String getName() { @@ -706,7 +706,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Returns the border. - * + * * @return the border. */ public int getBorder() { @@ -715,7 +715,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the border. - * + * * @param border * the border to set. */ @@ -725,7 +725,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the application this window is connected to. - * + * *

    * This method should not be invoked directly. Instead the * {@link com.vaadin.Application#addWindow(Window)} method should be used to @@ -733,12 +733,12 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * {@link com.vaadin.Application#removeWindow(Window)} method for removing * the window from the applicion. These methods call this method implicitly. *

    - * + * *

    * The method invokes {@link Component#attach()} and * {@link Component#detach()} methods when necessary. *

    - * + * * @param application * the application to set. */ @@ -768,12 +768,12 @@ public class Window extends Panel implements URIHandler, ParameterHandler { *

    * The name of the window must be unique inside the application. *

    - * + * *

    * If the name is null, the the window is given name automatically when it * is added to an application. *

    - * + * * @param name * the name to set. */ @@ -792,7 +792,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the terminal type. The terminal type is set by the the terminal * adapter and may change from time to time. - * + * * @param type * the terminal type to set. */ @@ -817,7 +817,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a new open resource. - * + * * @param resource * @param name * @param width @@ -835,7 +835,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Paints the open-tag inside the window. - * + * * @param target * the Paint Event. * @throws PaintException @@ -869,7 +869,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Called when one or more variables handled by the implementing class are * changed. - * + * * @see com.vaadin.terminal.VariableOwner#changeVariables(java.lang.Object, * java.util.Map) */ @@ -921,14 +921,14 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Method that handles window closing (from UI). - * + * *

    * By default, sub-windows are removed from their respective parent windows * and thus visually closed on browser-side. Browser-level windows also * closed on the client-side, but they are not implicitly removed from the * application. *

    - * + * *

    * If one wants change the default behavior, register a window close * listenter and do something else. For example, you could re-open the @@ -951,7 +951,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the distance of Window left border in pixels from left border of the * containing (main window). - * + * * @return the Distance of Window left border in pixels from left border of * the containing (main window). or -1 if unspecified. * @since 4.0.0 @@ -963,7 +963,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the distance of Window left border in pixels from left border of the * containing (main window). - * + * * @param positionX * the Distance of Window left border in pixels from left border * of the containing (main window). or -1 if unspecified. @@ -978,10 +978,10 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the distance of Window top border in pixels from top border of the * containing (main window). - * + * * @return Distance of Window top border in pixels from top border of the * containing (main window). or -1 if unspecified . - * + * * @since 4.0.0 */ public int getPositionY() { @@ -991,11 +991,11 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the distance of Window top border in pixels from top border of the * containing (main window). - * + * * @param positionY * the Distance of Window top border in pixels from top border of * the containing (main window). or -1 if unspecified - * + * * @since 4.0.0 */ public void setPositionY(int positionY) { @@ -1019,7 +1019,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { public class CloseEvent extends Component.Event { /** - * + * * @param source */ public CloseEvent(Component source) { @@ -1028,7 +1028,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the Window. - * + * * @return the window. */ public Window getWindow() { @@ -1042,7 +1042,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Adds the listener. - * + * * @param listener * the listener to add. */ @@ -1052,7 +1052,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Removes the listener. - * + * * @param listener * the listener to remove. */ @@ -1087,7 +1087,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { public class ResizeEvent extends Component.Event { /** - * + * * @param source */ public ResizeEvent(Component source) { @@ -1096,7 +1096,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Get the window form which this event originated - * + * * @return the window */ public Window getWindow() { @@ -1106,7 +1106,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Listener for window resize events. - * + * * @see com.vaadin.ui.Window.ResizeEvent */ public interface ResizeListener extends Serializable { @@ -1115,7 +1115,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Add a resize listener. - * + * * @param listener */ public void addListener(ResizeListener listener) { @@ -1124,7 +1124,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Remove a resize listener. - * + * * @param listener */ public void removeListener(ResizeListener listener) { @@ -1146,18 +1146,18 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Adds a window inside another window. - * + * *

    * Adding windows inside another window creates "subwindows". These windows * should not be added to application directly and are not accessible * directly with any url. Addding windows implicitly sets their parents. *

    - * + * *

    * Only one level of subwindows are supported. Thus you can add windows * inside such windows whose parent is null. *

    - * + * * @param window * @throws IllegalArgumentException * if a window is added inside non-application level window. @@ -1188,7 +1188,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Remove the given subwindow from this window. - * + * * @param window * Window to be removed. */ @@ -1201,7 +1201,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Get the set of all child windows. - * + * * @return Set of child windows. */ public Set getChildWindows() { @@ -1211,7 +1211,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets sub-window modal, so that widgets behind it cannot be accessed. * Note: affects sub-windows only. - * + * * @param modality * true if modality is to be turned on */ @@ -1230,7 +1230,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets sub-window resizable. Note: affects sub-windows only. - * + * * @param resizable * true if resizability is to be turned on */ @@ -1240,7 +1240,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { } /** - * + * * @return true if window is resizable by the end-user, otherwise false. */ public boolean isResizable() { @@ -1259,10 +1259,10 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Shows a notification message on the middle of the window. The message * automatically disappears ("humanized message"). - * + * * @see #showNotification(com.vaadin.ui.Window.Notification) * @see Notification - * + * * @param caption * The message */ @@ -1274,10 +1274,10 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Shows a notification message the window. The position and behavior of the * message depends on the type, which is one of the basic types defined in * {@link Notification}, for instance Notification.TYPE_WARNING_MESSAGE. - * + * * @see #showNotification(com.vaadin.ui.Window.Notification) * @see Notification - * + * * @param caption * The message * @param type @@ -1291,15 +1291,15 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Shows a notification consisting of a bigger caption and a smaller * description on the middle of the window. The message automatically * disappears ("humanized message"). - * + * * @see #showNotification(com.vaadin.ui.Window.Notification) * @see Notification - * + * * @param caption * The caption of the message * @param description * The message description - * + * */ public void showNotification(String caption, String description) { addNotification(new Notification(caption, description)); @@ -1310,10 +1310,10 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * description. The position and behavior of the message depends on the * type, which is one of the basic types defined in {@link Notification}, * for instance Notification.TYPE_WARNING_MESSAGE. - * + * * @see #showNotification(com.vaadin.ui.Window.Notification) * @see Notification - * + * * @param caption * The caption of the message * @param description @@ -1327,13 +1327,13 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Shows a notification message. - * + * * @see Notification * @see #showNotification(String) * @see #showNotification(String, int) * @see #showNotification(String, String) * @see #showNotification(String, String, int) - * + * * @param notification * The notification message to show */ @@ -1355,10 +1355,10 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * Component.Focusable) due we want the last focused component to be focused * in client too. Not the one that is rendered last (the case we'd get if * implemented in Focusable only). - * + * * To focus component from Vaadin application, use Focusable.focus(). See * {@link Focusable}. - * + * * @param focusable * to be focused on next paint */ @@ -1411,7 +1411,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * configured to show up in a custom position, for a specified time (or * until clicked), and with a custom stylename. An icon can also be added. *

    - * + * */ public static class Notification implements Serializable { public static final int TYPE_HUMANIZED_MESSAGE = 1; @@ -1439,7 +1439,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a "humanized" notification message. - * + * * @param caption * The message to show */ @@ -1449,7 +1449,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a notification message of the specified type. - * + * * @param caption * The message to show * @param type @@ -1462,7 +1462,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a "humanized" notification message with a bigger caption and * smaller description. - * + * * @param caption * The message caption * @param description @@ -1475,7 +1475,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Creates a notification message of the specified type, with a bigger * caption and smaller description. - * + * * @param caption * The message caption * @param description @@ -1513,7 +1513,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the caption part of the notification message. - * + * * @return The message caption */ public String getCaption() { @@ -1522,7 +1522,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the caption part of the notification message - * + * * @param caption * The message caption */ @@ -1550,7 +1550,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the description part of the notification message. - * + * * @return The message description. */ public String getDescription() { @@ -1559,7 +1559,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the description part of the notification message. - * + * * @param description */ public void setDescription(String description) { @@ -1568,7 +1568,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the position of the notification message. - * + * * @return The position */ public int getPosition() { @@ -1577,7 +1577,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the position of the notification message. - * + * * @param position * The desired notification position */ @@ -1587,7 +1587,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the icon part of the notification message. - * + * * @return The message icon */ public Resource getIcon() { @@ -1596,7 +1596,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the icon part of the notification message. - * + * * @param icon * The desired message icon */ @@ -1606,7 +1606,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the delay before the notification disappears. - * + * * @return the delay in msec, -1 indicates the message has to be * clicked. */ @@ -1616,7 +1616,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the delay before the notification disappears. - * + * * @param delayMsec * the desired delay in msec, -1 to require the user to click * the message @@ -1627,7 +1627,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Sets the style name for the notification message. - * + * * @param styleName * The desired style name. */ @@ -1637,7 +1637,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Gets the style name for the notification message. - * + * * @return */ public String getStyleName() { @@ -1647,13 +1647,13 @@ public class Window extends Panel implements URIHandler, ParameterHandler { /** * Executes JavaScript in this window. - * + * *

    * This method allows one to inject javascript from the server to client. A * client implementation is not required to implement this functionality, * but currently all web-based clients do implement this. *

    - * + * *

    * Executing javascript this way often leads to cross-browser compatibility * issues and regressions that are hard to resolve. Use of this method @@ -1661,7 +1661,7 @@ public class Window extends Panel implements URIHandler, ParameterHandler { * with GWT. For more info on creating own, reusable client-side widgets in * Java, read the corresponding chapter in Book of Vaadin. *

    - * + * * @param script * JavaScript snippet that will be executed. */