refining code splitting + adding documentation. Monolithic client side is now default (6.3 style), but the package includes other generator strategies that can be thrown in for custom requirements.

svn changeset:13669/svn branch:6.4

1 files changed, 31 insertions, 21 deletions

diff --git a/src/com/vaadin/ui/ClientWidget.java b/src/com/vaadin/ui/ClientWidget.java
index 0848309b31..1bfe58da66 100644
--- a/src/com/vaadin/ui/ClientWidget.java
+++ b/src/com/vaadin/ui/ClientWidget.java
@@ -12,6 +12,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import com.vaadin.terminal.gwt.client.Paintable;
+import com.vaadin.terminal.gwt.widgetsetutils.CustomWidgetMapGenerator;
+import com.vaadin.terminal.gwt.widgetsetutils.EagerWidgetMapGenerator;
+import com.vaadin.terminal.gwt.widgetsetutils.LazyWidgetMapGenerator;
 import com.vaadin.terminal.gwt.widgetsetutils.WidgetMapGenerator;
 
 /**
@@ -21,10 +24,9 @@ import com.vaadin.terminal.gwt.widgetsetutils.WidgetMapGenerator;
  * With this annotation server side Vaadin component is marked to have a client
  * side counterpart. The value of the annotation is the class of client side
  * implementation.
- * 
  * <p>
  * Note, even though client side implementation is needed during development,
- * one may safely remove them from classpath of the production server.
+ * one may safely remove them from the classpath of the production server.
  * 
  * @since 6.2
  */
@@ -37,33 +39,41 @@ public @interface ClientWidget {
     Class<? extends Paintable> value();
 
     /**
-     * TODO rewrite for EAGER, DEFERRED, LAZY
-     * 
-     * The lazy loading of a widget implementation means the client side
-     * component is not included in the initial JavaScript application loaded
-     * when the application starts. Instead the implementation is loaded to the
-     * client when it is first needed.
+     * Depending on the used WidgetMap generator, these optional hints may be
+     * used to define how the client side components are loaded by the browser.
+     * The default is to eagerly load all widgets
+     * {@link EagerWidgetMapGenerator}, but if the {@link WidgetMapGenerator} is
+     * used by the widgetset, these load style hints are respected.
+     * <p>
+     * Lazy loading of a widget implementation means the client side component
+     * is not included in the initial JavaScript application loaded when the
+     * application starts. Instead the implementation is loaded to the client
+     * when it is first needed. Lazy loaded widget can be achieved by giving
+     * {@link LoadStyle#LAZY} value in ClientWidget annotation.
      * <p>
      * Lazy loaded widgets don't stress the size and startup time of the client
      * side as much as eagerly loaded widgets. On the other hand there is a
      * slight latency when lazy loaded widgets are first used as the client side
      * needs to visit the server to fetch the client side implementation.
      * <p>
-     * In common situations the default value should be fine. If the widget
-     * implementation commonly used and often on first view it is better set
-     * lazy loading off for it. Also if the component implementation is really
-     * thing, it may by justified to make the widget implementation eagerly
-     * loaded.
+     * The {@link LoadStyle#DEFERRED} will also not stress the initially loaded
+     * JavaScript file. If this load style is defined, the widget implementation
+     * is preemptively loaded to the browser after the application is started
+     * and the communication to server idles. This load style kind of combines
+     * the best of both worlds.
      * <p>
-     * Tunings to widget loading can also be made by overriding
-     * {@link WidgetMapGenerator} in GWT module. Tunings might be helpful if the
-     * end users have slow connections and especially if they have high latency
-     * in their network.
+     * Fine tunings to widget loading can also be made by overriding
+     * {@link WidgetMapGenerator} in the GWT module. Tunings might be helpful if
+     * the end users have slow connections and especially if they have high
+     * latency in their network. The {@link CustomWidgetMapGenerator} is an
+     * abstract generator implementation for easy customization. Vaadin package
+     * also includes {@link LazyWidgetMapGenerator} that makes as many widgets
+     * lazily loaded as possible.
+     * 
+     * @since 6.4
      * 
-     * @return if true (default), the GWT code generator will make the client
-     *         side implementation lazy loaded. Displaying it first time on the
-     *         screen slightly increases, but widgets implementation does not
-     *         stress the initialization of the client side engine.
+     * @return the hint for the widget set generator how the client side
+     *         implementation should be loaded to the browser
      */
     LoadStyle loadStyle() default LoadStyle.DEFERRED;