Patch #4 from #3234 "JavaDoc and ClientEventList Update"

svn changeset:9959/svn branch:event-framework-3234

src/com/vaadin/event/ClientEventList.java

@@ -9,11 +9,13 @@ import java.util.Map;
 
 /**
  * 
- * this class is used to store the registered events so a list of the required
- * client event identifiers (that the client-side should listen for and send to
- * the server-side) can be sent to the client-side via a variable.
+ * <code>ClientEventList</code> class used to store the registered events so a
+ * list of the required client event identifiers (that the client-side should
+ * listen for and send to the server-side) can be sent to the client-side via a
+ * variable.
  * 
  * @author davengo GmbH (Germany/Berlin, www.davengo.com)
+ * @since 6.2
  * 
  */
 public class ClientEventList {
@@ -21,11 +23,15 @@ public class ClientEventList {
     /**
      * the list containing the registered client events (as strings for
      * client-side transfer)
+     * 
+     * @since 6.2
      */
     private Map<String, Integer> clientEvents = null;
 
     /**
      * initializes the list if necessary
+     * 
+     * @since 6.2
      */
     private void checkList() {
         if (clientEvents == null) {
@@ -40,14 +46,23 @@ public class ClientEventList {
      * 
      * @param eventIdentifier
      *            the identifier of the event to listen for
+     * 
+     * @return true, if the event is newly added to the list<br>
+     *         false, if the list already contained the event (the internal
+     *         counter was incremented)
+     * 
+     * @since 6.2
      */
-    public void listenEvent(String eventIdentifier) {
+    public boolean listenEvent(String eventIdentifier) {
         checkList();
-        if (!clientEvents.keySet().contains(eventIdentifier))
+        if (!clientEvents.keySet().contains(eventIdentifier)) {
             clientEvents.put(eventIdentifier, 1);
-        else
+            return true;
+        } else {
             clientEvents.put(eventIdentifier,
                     clientEvents.get(eventIdentifier) + 1);
+            return false;
+        }
     }
 
     /**
@@ -58,19 +73,28 @@ public class ClientEventList {
      * 
      * @param eventIdentifier
      *            the identifier of the event to stop listening for
+     * @return true, if the event was removed from the list<br>
+     *         false, if the event is hold in list (the internal counter was
+     *         greater than zero)
      */
-    public void unlistenEvent(String eventIdentifier) {
+    public boolean unlistenEvent(String eventIdentifier) {
         checkList();
         if (clientEvents.keySet().contains(eventIdentifier)) {
             clientEvents.put(eventIdentifier,
                     clientEvents.get(eventIdentifier) - 1);
-            if (clientEvents.get(eventIdentifier) <= 0)
+            if (clientEvents.get(eventIdentifier) <= 0) {
                 clientEvents.remove(eventIdentifier);
+                return true;
+            }
+            return false;
         }
+        return false;
     }
 
     /**
      * @return a string array containing all registered events
+     * 
+     * @since 6.2
      */
     public String[] getEvents() {
         if (clientEvents == null) {

src/com/vaadin/event/FieldEvents.java

@@ -1,3 +1,7 @@
+/* 
+@ITMillApache2LicenseForJavaFiles@
+ */
+
 package com.vaadin.event;
 
 import java.lang.reflect.Method;
@@ -7,10 +11,12 @@ import com.vaadin.ui.Component;
 
 public interface FieldEvents {
 
-    /*
-     * component focus event and listener
+    /**
+     * <code>FocusEvent</code> class for holding additional event information.
+     * Fired when a <code>Field</code> receives keyboard focus.
+     * 
+     * @since 6.2
      */
-
     public class FocusEvent extends Component.Event {
 
         private static final long serialVersionUID = -7644184999481404162L;
@@ -20,6 +26,13 @@ public interface FieldEvents {
         }
     }
 
+    /**
+     * <code>FocusListener</code> interface for listening for
+     * <code>FocusEvent</code> fired by a <code>Field</code>.
+     * 
+     * @see FocusEvent
+     * @since 6.2
+     */
     public interface FocusListener extends ComponentEventListener {
 
         public static final Method focusMethod = ReflectTools.findMethod(
@@ -34,10 +47,12 @@ public interface FieldEvents {
         public void focus(FocusEvent event);
     }
 
-    /*
-     * component blur event and listener
+    /**
+     * <code>BlurEvent</code> class for holding additional event information.
+     * Fired when a <code>Field</code> loses keyboard focus.
+     * 
+     * @since 6.2
      */
-
     public class BlurEvent extends Component.Event {
 
         private static final long serialVersionUID = -7644184999481404162L;
@@ -47,6 +62,13 @@ public interface FieldEvents {
         }
     }
 
+    /**
+     * <code>BlurListener</code> interface for listening for
+     * <code>BlurEvent</code> fired by a <code>Field</code>.
+     * 
+     * @see BlurEvent
+     * @since 6.2
+     */
     public interface BlurListener extends ComponentEventListener {
 
         public static final Method blurMethod = ReflectTools.findMethod(
@@ -61,10 +83,12 @@ public interface FieldEvents {
         public void blur(BlurEvent event);
     }
 
-    /*
-     * component value change event
+    /**
+     * <code>ValueChangeEvent</code> class for holding additional event
+     * information. Fired when the value of a <code>Field</code> changes.
+     * 
+     * @since 6.2
      */
-
     public class ValueChangeEvent extends Component.Event {
 
         private static final long serialVersionUID = -7644184999481404162L;
@@ -74,6 +98,13 @@ public interface FieldEvents {
         }
     }
 
+    /**
+     * <code>ValueChangeListener</code> interface for listening for
+     * <code>ValueChangeEvent</code> fired by a <code>Field</code>.
+     * 
+     * @see ValueChangeEvent
+     * @since 6.2
+     */
     public interface ValueChangeListener extends ComponentEventListener {
 
         public static final Method valueChangeMethod = ReflectTools.findMethod(

src/com/vaadin/event/MouseEvents.java

@@ -1,3 +1,7 @@
+/* 
+@ITMillApache2LicenseForJavaFiles@
+ */
+
 package com.vaadin.event;
 
 import java.lang.reflect.Method;
@@ -8,12 +12,18 @@ import com.vaadin.ui.Component;
 public interface MouseEvents {
 
     /**
-     * defines the clicked mouse button for a ComponentClickEvents
+     * defines the clicked mouse button for ClickEvents
      */
     public enum MouseButton {
         LEFT, RIGHT, MIDDLE
     }
 
+    /**
+     * <code>ClickEvent</code> class for holding additional event information.
+     * Fired when the user clicks on a <code>Component</code>.
+     * 
+     * @since 6.2
+     */
     public class ClickEvent extends Component.Event {
 
         private MouseButton mouseButton;
@@ -37,6 +47,13 @@ public interface MouseEvents {
 
     }
 
+    /**
+     * <code>ClickListener</code> interface for listening for
+     * <code>ClickEvent</code> fired by a <code>Component</code>.
+     * 
+     * @see ClickEvent
+     * @since 6.2
+     */
     public interface ClickListener extends ComponentEventListener {
 
         public static final Method clickMethod = ReflectTools.findMethod(
@@ -51,10 +68,13 @@ public interface MouseEvents {
         public void click(ClickEvent event);
     }
 
-    /*
-     * component double click event
+    /**
+     * <code>DoubleClickEvent</code> class for holding additional event
+     * information. Fired when the user double-clicks on a
+     * <code>Component</code>.
+     * 
+     * @since 6.2
      */
-
     public class DoubleClickEvent extends Component.Event {
 
         private static final long serialVersionUID = -7644184999481404162L;
@@ -64,6 +84,13 @@ public interface MouseEvents {
         }
     }
 
+    /**
+     * <code>DoubleClickListener</code> interface for listening for
+     * <code>DoubleClickEvent</code> fired by a <code>Component</code>.
+     * 
+     * @see DoubleClickEvent
+     * @since 6.2
+     */
     public interface DoubleClickListener extends ComponentEventListener {
 
         public static final Method doubleClickMethod = ReflectTools.findMethod(

src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java

@@ -12,6 +12,7 @@ import java.util.List;
  * class for event handlers used by ComponentEventHandler
  * 
  * @author davengo GmbH (Germany/Berlin, www.davengo.com)
+ * @since 6.2
  * 
  */
 public class ComponentEventHandler {
@@ -23,6 +24,20 @@ public class ComponentEventHandler {
     private ComponentDetail detail;
     private ApplicationConnection client;
 
+    /**
+     * creates a new <code>ComponentEventHandler</code> instance for the given
+     * <code>ComponentDetail</code> and <code>ApplicationConntection</code>
+     * instance.
+     * 
+     * @param detail
+     *            the attached ComponentDetail
+     * @param client
+     *            the <code>ApplicationConnection</code> for sending events
+     * 
+     * @see ApplicationConnection
+     * @see ComponentDetail
+     * @since 6.2
+     */
     public ComponentEventHandler(ComponentDetail detail,
             ApplicationConnection client) {
         this.detail = detail;
@@ -39,6 +54,7 @@ public class ComponentEventHandler {
      *            the unique identifier for the event
      * @param parameters
      *            the parameters for the event (can be null)
+     * @since 6.2
      */
     public void fireEvent(String eventIdentifier, String... parameters) {
         fireEvent(eventIdentifier, false, parameters);
@@ -54,11 +70,24 @@ public class ComponentEventHandler {
      *            the unique identifier for the event
      * @param parameters
      *            the parameters for the event (can be null)
+     * @since 6.2
      */
     public void fireComponentEvent(String eventIdentifier, String... parameters) {
         fireEvent(eventIdentifier, true, parameters);
     }
 
+    /**
+     * Transmit the event to the Server (Fires a event which is transmitted to
+     * the server and passed on the the components handleEvent method)
+     * 
+     * @param eventIdentifier
+     *            the unique identifier for the event
+     * @param forceTransmission
+     *            enforce the transmission to the server
+     * @param parameters
+     *            the parameters for the event (can be null)
+     * @since 6.2
+     */
     private void fireEvent(String eventIdentifier, boolean forceTransmission,
             String... parameters) {
 
@@ -86,6 +115,12 @@ public class ComponentEventHandler {
         }
     }
 
+    /**
+     * Registers the Events listened on the server-side from the UIDL
+     * 
+     * @param componentUIDL
+     * @since 6.2
+     */
     void registerEventsFromUIDL(UIDL componentUIDL) {
 
         // read out the request event handlers

src/com/vaadin/ui/AbstractComponent.java

@@ -688,7 +688,6 @@ public abstract class AbstractComponent implements Component, MethodEventSource
                     target.addAttribute("description", getDescription());
                 }
 
-                // davengo GmbH: add client event variables
                 String[] trigger = new String[] {};
                 String[] events = new String[] {};
                 if (clientEvents != null) {
@@ -866,13 +865,15 @@ public abstract class AbstractComponent implements Component, MethodEventSource
      * event-api mechanism for listening on events.
      * 
      * @param eventIdentifier
+     * @since 6.2
      */
     private void listenEvent(String eventIdentifier) {
         if (clientEvents == null) {
             clientEvents = new ClientEventList();
         }
-        clientEvents.listenEvent(eventIdentifier);
-        requestRepaint();
+        final boolean repaint = clientEvents.listenEvent(eventIdentifier);
+        if (repaint)
+            requestRepaint();
     }
 
     /**
@@ -886,11 +887,13 @@ public abstract class AbstractComponent implements Component, MethodEventSource
      * event-api mechanism for listening on events.
      * 
      * @param eventIdentifier
+     * @since 6.2
      */
     private void unlistenEvent(String eventIdentifier) {
         if (clientEvents != null) {
-            clientEvents.unlistenEvent(eventIdentifier);
-            requestRepaint();
+            final boolean repaint = clientEvents.unlistenEvent(eventIdentifier);
+            if (repaint)
+                requestRepaint();
         }
     }
 
@@ -957,6 +960,8 @@ public abstract class AbstractComponent implements Component, MethodEventSource
      *            the object instance who owns the activation method.
      * @param method
      *            the activation method.
+     * 
+     * @since 6.2
      */
     protected void addEventListener(String eventIdentifier, Class<?> eventType,
             Object object, Method method) {
@@ -992,6 +997,8 @@ public abstract class AbstractComponent implements Component, MethodEventSource
      * @param target
      *            the target object that has registered to listen to events of
      *            type <code>eventType</code> with one or more methods.
+     * 
+     * @since 6.2
      */
     protected void removeEventListener(String eventIdentifier,
             Class<?> eventType, Object target) {
@@ -1027,6 +1034,8 @@ public abstract class AbstractComponent implements Component, MethodEventSource
      * @param method
      *            the method owned by <code>target</code> that's registered to
      *            listen to events of type <code>eventType</code>.
+     * 
+     * @since 6.2
      */
     protected void removeEventListener(String eventIdentifier, Class eventType,
             Object target, Method method) {