DD related javadocs, cleanup, small refactoring

svn changeset:11938/svn branch:6.3

9 files changed, 128 insertions, 41 deletions

diff --git a/src/com/vaadin/event/dd/DragAndDropEvent.java b/src/com/vaadin/event/dd/DragAndDropEvent.java
index d572739ef2..275e212701 100644
--- a/src/com/vaadin/event/dd/DragAndDropEvent.java
+++ b/src/com/vaadin/event/dd/DragAndDropEvent.java
@@ -6,9 +6,18 @@ package com.vaadin.event.dd;
 import java.io.Serializable;
 
 import com.vaadin.event.Transferable;
+import com.vaadin.event.dd.acceptCriteria.AcceptCriterion;
 
 /**
- * TODO Javadoc
+ * DragAndDropEvent wraps information related to drag and drop operation. It is
+ * passed by terminal implementation for
+ * {@link DropHandler#drop(DragAndDropEvent)} and
+ * {@link AcceptCriterion#accepts(DragAndDropEvent)} methods.
+ * <p>
+ * DragAndDropEvent instances contains both the dragged data in
+ * {@link Transferable} (generated by {@link DragSource} and details about the
+ * current drop event in {@link DropTargetDetails} (generated by
+ * {@link DropTarget}.
  * 
  * @since 6.3
  * 
@@ -24,10 +33,18 @@ public class DragAndDropEvent implements Serializable {
         this.dropTargetDetails = dropTargetDetails;
     }
 
+    /**
+     * @return the Transferable instance representing the data dragged in this
+     *         drag and drop event
+     */
     public Transferable getTransferable() {
         return transferable;
     }
 
+    /**
+     * @return the DropTargetDetails containing drop target related details of
+     *         drag and drop operation
+     */
     public DropTargetDetails getDropTargetDetails() {
         return dropTargetDetails;
     }
diff --git a/src/com/vaadin/event/dd/DragSource.java b/src/com/vaadin/event/dd/DragSource.java
index 3751ed00e6..3635bf5468 100644
--- a/src/com/vaadin/event/dd/DragSource.java
+++ b/src/com/vaadin/event/dd/DragSource.java
@@ -3,35 +3,49 @@
  */
 package com.vaadin.event.dd;
 
-import java.io.Serializable;
 import java.util.Map;
 
 import com.vaadin.event.Transferable;
+import com.vaadin.event.dd.acceptCriteria.AcceptCriterion;
+import com.vaadin.ui.Component;
+import com.vaadin.ui.Tree;
 
 /**
- * TODO Javadoc
+ * DragSource is a {@link Component} that builds a {@link Transferable} for a
+ * drag and drop operation.
+ * <p>
+ * In Vaadin the drag and drop operation practically starts from client side
+ * component. The client side component initially defines the data that will be
+ * present in {@link Transferable} object on server side. If the server side
+ * counterpart of the component implements this interface, terminal
+ * implementation lets it create the {@link Transferable} instance from the raw
+ * client side "seed data". This way server side implementation may translate or
+ * extend the data that will be available for {@link DropHandler}.
  * 
  * @since 6.3
  * 
  */
-public interface DragSource extends Serializable {
+public interface DragSource extends Component {
 
     /**
-     * DragSource may convert client side variables to meaningful values on
-     * server side. For example Tree converts item identifiers to generated
-     * string keys for the client side. Translators in Selects should convert
-     * them back to item identifiers.
+     * DragSource may convert data added by client side component to meaningful
+     * values for server side developer or add other data based on it.
      * 
      * <p>
-     * Translator should remove variables it handled from rawVariables. All non
-     * handled variables are added to Transferable automatically by terminal.
-     * </p>
-     * 
+     * For example Tree converts item identifiers to generated string keys for
+     * the client side. Vaadin developer don't and can't know anything about
+     * these generated keys, only about item identifiers. When tree node is
+     * dragged client puts that key to {@link Transferable}s client side
+     * counterpart. In {@link Tree#getTransferable(Map)} the key is converted
+     * back to item identifier that the server side developer can use.
      * <p>
      * 
      * @since 6.3
      * @param rawVariables
-     * @return the drag source related transferable
+     *            the data that client side initially included in
+     *            {@link Transferable}s client side counterpart.
+     * @return the {@link Transferable} instance that will be passed to
+     *         {@link DropHandler} (and/or {@link AcceptCriterion})
      */
     public Transferable getTransferable(Map<String, Object> rawVariables);
 
diff --git a/src/com/vaadin/event/dd/DropHandler.java b/src/com/vaadin/event/dd/DropHandler.java
index 555bd7136b..c1c720ae2c 100644
--- a/src/com/vaadin/event/dd/DropHandler.java
+++ b/src/com/vaadin/event/dd/DropHandler.java
@@ -7,25 +7,50 @@ import java.io.Serializable;
 
 import com.vaadin.event.dd.acceptCriteria.AcceptAll;
 import com.vaadin.event.dd.acceptCriteria.AcceptCriterion;
+import com.vaadin.event.dd.acceptCriteria.ServerSideCriterion;
 
 /**
- * TODO Javadoc
+ * DropHandlers contain the actual business logic for drag and drop operations.
+ * <p>
+ * The {@link #drop(DragAndDropEvent)} method is used to receive the transferred
+ * data and the #getAcceptCriterion()} method contains the (possibly client side
+ * verifiable) criterion whether the dragged data will be handled at all.
  * 
  * @since 6.3
  * 
  */
 public interface DropHandler extends Serializable {
 
+    /**
+     * Drop method is called when the end user has finished the drag operation
+     * on a {@link DropTarget} and {@link DragAndDropEvent} has passed
+     * {@link AcceptCriterion} defined by {@link #getAcceptCriterion()} method.
+     * The actual business logic of drag and drop operation is implemented into
+     * this method.
+     * 
+     * @param event
+     *            the event related to this drop
+     */
     public void drop(DragAndDropEvent event);
 
     /**
      * Returns the {@link AcceptCriterion} used to evaluate whether the
-     * {@link Transferable} will be handed over to {@link DropHandler}. If
-     * client side can't verify the {@link AcceptCriterion}, the same criteria
-     * may be tested also prior to actual drop - during the drag operation.
+     * {@link Transferable} will be handed over to
+     * {@link DropHandler#drop(DragAndDropEvent)} method. If client side can't
+     * verify the {@link AcceptCriterion}, the same criteria may be tested also
+     * prior to actual drop - during the drag operation.
+     * <p>
+     * Based on information from {@link AcceptCriterion} components may display
+     * some hints for the end user whether the drop will be accepted or not.
+     * <p>
+     * Vaadin contains a variety of criteria built in that can be composed to
+     * more complex criterion. If the build in criteria are not enough,
+     * developer can use a {@link ServerSideCriterion} or build own custom
+     * criterion with client side counterpart.
      * <p>
-     * If everything is accepted developer can return {@link AcceptAll}
-     * instance.
+     * If developer wants to handle everything in the
+     * {@link #drop(DragAndDropEvent)} method, {@link AcceptAll} instance can be
+     * returned.
      * 
      * @return the {@link AcceptCriterion}
      */
diff --git a/src/com/vaadin/event/dd/DropTarget.java b/src/com/vaadin/event/dd/DropTarget.java
index 1d032c42e4..b2ab244c43 100644
--- a/src/com/vaadin/event/dd/DropTarget.java
+++ b/src/com/vaadin/event/dd/DropTarget.java
@@ -16,17 +16,24 @@ import com.vaadin.ui.Component;
  */
 public interface DropTarget extends Component {
 
+    /**
+     * @return the drop hanler that will receive the dragged data or null if
+     *         drops are not currently accepted
+     */
     public DropHandler getDropHandler();
 
     /**
-     * Called before a drop operation to translate the drop target details
-     * provided by the client widget (drop target). Should return a DropData
-     * implementation with the new values. If null is returned the terminal
-     * implementation will automatically create a {@link DropTargetDetails} with
-     * all the client variables.
+     * Called before the {@link DragAndDropEvent} is passed to
+     * {@link DropHandler}. Implementation may for exmaple translate the drop
+     * target details provided by the client side (drop target) to meaningful
+     * server side values. If null is returned the terminal implementation will
+     * automatically create a {@link DropTargetDetails} with raw client side
+     * data.
+     * 
+     * @see DragSource#getTransferable(Map)
      * 
      * @param rawVariables
-     *            Parameters passed from the client side widget.
+     *            data passed from the DropTargets client side counterpart.
      * @return A DropTargetDetails object with the translated data or null to
      *         use a default implementation.
      */
diff --git a/src/com/vaadin/event/dd/DropTargetDetails.java b/src/com/vaadin/event/dd/DropTargetDetails.java
index 1e3b38333d..770d58d9d3 100644
--- a/src/com/vaadin/event/dd/DropTargetDetails.java
+++ b/src/com/vaadin/event/dd/DropTargetDetails.java
@@ -5,18 +5,33 @@ package com.vaadin.event.dd;
 
 import java.io.Serializable;
 
+import com.vaadin.ui.Tree.TreeDropTargetDetails;
+
 /**
- * TODO Javadoc
+ * DropTargetDetails wraps drop target related information about
+ * {@link DragAndDropEvent}.
+ * <p>
+ * When a DropTargetDetails object is used in {@link DropHandler} it is often
+ * preferable to cast the DropTargetDetail to an implementation provided by
+ * DropTarget like {@link TreeDropTargetDetails}. They often provide better
+ * typed, drop target specific API.
  * 
  * @since 6.3
  * 
  */
 public interface DropTargetDetails extends Serializable {
 
+    /**
+     * Gets target data associated to given string key
+     * 
+     * @param key
+     * @return
+     */
     public Object getData(String key);
 
-    public Object setData(String key, Object value);
-
+    /**
+     * @return the drop target on which the {@link DragAndDropEvent} happened.
+     */
     public DropTarget getTarget();
 
 }
diff --git a/src/com/vaadin/event/dd/DropTargetDetailsImpl.java b/src/com/vaadin/event/dd/DropTargetDetailsImpl.java
index 2e6641c2ca..bcc35c623c 100644
--- a/src/com/vaadin/event/dd/DropTargetDetailsImpl.java
+++ b/src/com/vaadin/event/dd/DropTargetDetailsImpl.java
@@ -6,22 +6,29 @@ package com.vaadin.event.dd;
 import java.util.HashMap;
 import java.util.Map;
 
-import com.vaadin.terminal.gwt.server.DragAndDropService;
-
 /**
- * TODO Javadoc
+ * A HashMap backed implementation of {@link DropTargetDetails} for terminal
+ * implementation and for extension.
  * 
  * @since 6.3
  * 
  */
 public class DropTargetDetailsImpl implements DropTargetDetails {
 
+    private static final long serialVersionUID = -5099462771593036776L;
     private HashMap<String, Object> data = new HashMap<String, Object>();
+    private DropTarget dropTarget;
 
-    public DropTargetDetailsImpl(Map<String, Object> rawDropData) {
+    protected DropTargetDetailsImpl(Map<String, Object> rawDropData) {
         data.putAll(rawDropData);
     }
 
+    public DropTargetDetailsImpl(Map<String, Object> rawDropData,
+            DropTarget dropTarget) {
+        this(rawDropData);
+        this.dropTarget = dropTarget;
+    }
+
     public Object getData(String key) {
         return data.get(key);
     }
@@ -31,7 +38,7 @@ public class DropTargetDetailsImpl implements DropTargetDetails {
     }
 
     public DropTarget getTarget() {
-        return (DropTarget) data.get(DragAndDropService.DROPTARGET_KEY);
+        return dropTarget;
     }
 
 }
\ No newline at end of file
diff --git a/src/com/vaadin/terminal/gwt/client/ui/dd/VTransferable.java b/src/com/vaadin/terminal/gwt/client/ui/dd/VTransferable.java
index 1574a6f6b4..57b4d90e07 100644
--- a/src/com/vaadin/terminal/gwt/client/ui/dd/VTransferable.java
+++ b/src/com/vaadin/terminal/gwt/client/ui/dd/VTransferable.java
@@ -34,7 +34,7 @@ public class VTransferable {
      * Sets the component currently being dragged or from which the transferable
      * is created (eg. a tree which node is dragged).
      * <p>
-     * The server side counterpart of the componennt may implement
+     * The server side counterpart of the component may implement
      * {@link DragSource} interface if it wants to translate or complement the
      * server side instance of this Transferable.
      * 
diff --git a/src/com/vaadin/terminal/gwt/server/DragAndDropService.java b/src/com/vaadin/terminal/gwt/server/DragAndDropService.java
index bcba64d884..a314ebc967 100644
--- a/src/com/vaadin/terminal/gwt/server/DragAndDropService.java
+++ b/src/com/vaadin/terminal/gwt/server/DragAndDropService.java
@@ -6,8 +6,8 @@ package com.vaadin.terminal.gwt.server;
 import java.io.PrintWriter;
 import java.util.Map;
 
-import com.vaadin.event.TransferableImpl;
 import com.vaadin.event.Transferable;
+import com.vaadin.event.TransferableImpl;
 import com.vaadin.event.dd.DragAndDropEvent;
 import com.vaadin.event.dd.DragSource;
 import com.vaadin.event.dd.DropHandler;
@@ -24,8 +24,6 @@ public class DragAndDropService implements VariableOwner {
 
     private static final long serialVersionUID = -4745268869323400203L;
 
-    public static final String DROPTARGET_KEY = "target";
-
     private int lastVisitId;
 
     private int currentEventId;
@@ -148,11 +146,9 @@ public class DragAndDropService implements VariableOwner {
 
         if (dropData == null) {
             // Create a default DragDropDetails with all the raw variables
-            dropData = new DropTargetDetailsImpl(rawDragDropDetails);
+            dropData = new DropTargetDetailsImpl(rawDragDropDetails, dropTarget);
         }
 
-        dropData.setData(DROPTARGET_KEY, dropTarget);
-
         return dropData;
     }
 
diff --git a/tests/src/com/vaadin/tests/dd/DDTest6.java b/tests/src/com/vaadin/tests/dd/DDTest6.java
index ea3859c664..00fffdbaf0 100644
--- a/tests/src/com/vaadin/tests/dd/DDTest6.java
+++ b/tests/src/com/vaadin/tests/dd/DDTest6.java
@@ -2,6 +2,7 @@ package com.vaadin.tests.dd;
 
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
+import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.util.Collection;
@@ -400,7 +401,12 @@ public class DDTest6 extends TestBase {
                     for (Html5File html5File : files2) {
                         String fileName = html5File.getFileName();
                         // int bytes = html5File.getFileSize();
-                        final ByteArrayOutputStream bas = new ByteArrayOutputStream();
+                        final ByteArrayOutputStream bas = new ByteArrayOutputStream() {
+                            @Override
+                            public void close() throws IOException {
+                                super.close();
+                            }
+                        };
 
                         Receiver receiver = new Receiver() {
                             public OutputStream receiveUpload(String filename,