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

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

5 files changed, 152 insertions, 26 deletions

diff --git a/src/com/vaadin/event/ClientEventList.java b/src/com/vaadin/event/ClientEventList.java
index 633026ca8b..e2008085c4 100644
--- a/src/com/vaadin/event/ClientEventList.java
+++ b/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) {

diff --git a/src/com/vaadin/event/FieldEvents.java b/src/com/vaadin/event/FieldEvents.java
index ab81ac85c0..3becb58aef 100644
--- a/src/com/vaadin/event/FieldEvents.java
+++ b/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(

diff --git a/src/com/vaadin/event/MouseEvents.java b/src/com/vaadin/event/MouseEvents.java
index 19fdff8cc4..bf417c1ebf 100644
--- a/src/com/vaadin/event/MouseEvents.java
+++ b/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(
diff --git a/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java b/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java
index f309f79979..2df8f9bf11 100644
--- a/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java
+++ b/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

diff --git a/src/com/vaadin/ui/AbstractComponent.java b/src/com/vaadin/ui/AbstractComponent.java
index c624cf3224..ee07a560e4 100644
--- a/src/com/vaadin/ui/AbstractComponent.java
+++ b/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) {