Some drag'n'drop javadoc improvements and a new method in DataBoundTransferable.

svn changeset:11831/svn branch:6.3

11 files changed, 111 insertions, 25 deletions

diff --git a/src/com/vaadin/event/DataBoundTransferable.java b/src/com/vaadin/event/DataBoundTransferable.java
index 75263b2dac..edef4c4427 100644
--- a/src/com/vaadin/event/DataBoundTransferable.java
+++ b/src/com/vaadin/event/DataBoundTransferable.java
@@ -5,8 +5,22 @@ package com.vaadin.event;
 
 import java.util.Map;
 
+import com.vaadin.data.Container;
 import com.vaadin.ui.Component;
 
+/**
+ * Parent class for {@link Transferable} implementations that have a Vaadin
+ * container as a data source. The transfer is associated with an item
+ * (identified by its Id) and optionally also a property identifier (e.g. a
+ * table column identifier when transferring a single table cell).
+ * 
+ * The component must implement the interface {@link Container.Viewer}.
+ * 
+ * In most cases, receivers of data transfers should depend on this class
+ * instead of its concrete subclasses.
+ * 
+ * @since 6.3
+ */
 public abstract class DataBoundTransferable extends TransferableImpl {
 
     public DataBoundTransferable(Component sourceComponent,
@@ -14,8 +28,38 @@ public abstract class DataBoundTransferable extends TransferableImpl {
         super(sourceComponent, rawVariables);
     }
 
+    /**
+     * Returns the identifier of the item being transferred.
+     * 
+     * @return item identifier
+     */
     public abstract Object getItemId();
 
+    /**
+     * Returns the optional property identifier that the transfer concerns.
+     * 
+     * This can be e.g. the table column from which a drag operation originated.
+     * 
+     * @return property identifier
+     */
     public abstract Object getPropertyId();
 
+    /**
+     * Returns the container data source from which the transfer occurs.
+     * 
+     * {@link Container.Viewer#getContainerDataSource()} is used to obtain the
+     * underlying container of the source component.
+     * 
+     * @return Container
+     */
+    public Container getSourceContainer() {
+        Component sourceComponent = getSourceComponent(); 
+        if (sourceComponent instanceof Container.Viewer) {
+            return ((Container.Viewer) sourceComponent)
+                    .getContainerDataSource();
+        } else {
+            // this should not happen
+            return null;
+        }
+    }
 }
diff --git a/src/com/vaadin/event/dd/DropTarget.java b/src/com/vaadin/event/dd/DropTarget.java
index 7bd3efa8ee..1d032c42e4 100644
--- a/src/com/vaadin/event/dd/DropTarget.java
+++ b/src/com/vaadin/event/dd/DropTarget.java
@@ -10,7 +10,7 @@ import com.vaadin.ui.Component;
 /**
  * DropTarget is an interface for components supporting drop operations. A
  * component that wants to receive drop events should implement this interface
- * and provide a DropHandler which will handle the actual drop event.
+ * and provide a {@link DropHandler} which will handle the actual drop event.
  * 
  * @since 6.3
  */
diff --git a/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java b/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java
index 4b9ce0fe18..d65c64d81e 100644
--- a/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java
+++ b/src/com/vaadin/event/dd/acceptCriteria/AcceptCriterion.java
@@ -15,20 +15,36 @@ import com.vaadin.terminal.PaintException;
 import com.vaadin.terminal.PaintTarget;
 
 /**
- * TODO Javadoc
+ * Criterion that can be used create policy to accept/discard dragged content
+ * (presented by {@link Transferable}).
  * 
- * @since 6.3
+ * The drag and drop mechanism will verify the criteria returned by
+ * {@link DropHandler#getAcceptCriterion()} before calling
+ * {@link DropHandler#drop(DragAndDropEvent)}.
+ * 
+ * The criteria can be evaluated either on the client (browser - see
+ * {@link ClientSideCriterion}) or on the server (see
+ * {@link ServerSideCriterion}). If no constraints are needed, an
+ * {@link AcceptAll} can be used.
+ * 
+ * In addition to accepting or rejecting a possible drop, criteria can provide
+ * additional hints for client side painting.
  * 
+ * @see DropHandler
+ * @see ClientSideCriterion
+ * @see ServerSideCriterion
+ * 
+ * @since 6.3
  */
 public interface AcceptCriterion extends Serializable {
 
     /**
-     * Criterion that can be used create policy to accept/discard dragged
-     * content (presented by {@link Transferable}).
+     * Returns whether the criteria can be checked on the client or whether a
+     * server request is needed to check the criteria.
      * 
-     * May depend on state, like in OR or AND, so to be really
-     * ClientSideVerifiable needs to return true here (instead of just
-     * implementing marker interface).
+     * This requirement may depend on the state of the criterion (e.g. logical
+     * operations between criteria), so this cannot be based on a marker
+     * interface.
      */
     public boolean isClientSideVerifiable();
 
@@ -46,11 +62,11 @@ public interface AcceptCriterion extends Serializable {
     public void paintResponse(PaintTarget target) throws PaintException;
 
     /**
-     * Validates the data in event to be approriate for
+     * Validates the data in event to be appropriate for
      * {@link DropHandler#drop(com.vaadin.event.dd.DropEvent)} method.
      * <p>
-     * Note, that event if your criterion is matched on client side, it is a
-     * very good manner to validate the data on server side too.
+     * Note that even if your criterion is matched on client side, it is a very
+     * good manner to validate the data on server side too.
      * 
      * @param dragEvent
      * @return
diff --git a/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java b/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java
index 849f25bc0a..e406535958 100644
--- a/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java
+++ b/src/com/vaadin/event/dd/acceptCriteria/ClientSideCriterion.java
@@ -13,6 +13,11 @@ import com.vaadin.terminal.PaintTarget;
  * All classes that provide criteria that can be completely validated on client
  * side should extend this class.
  * 
+ * It is recommended that subclasses of ClientSideCriterion re-validate the
+ * condition on the server side in
+ * {@link AcceptCriterion#accepts(com.vaadin.event.dd.DragAndDropEvent)} after
+ * the client side validation has accepted a transfer.
+ * 
  * @since 6.3
  */
 public abstract class ClientSideCriterion implements Serializable,
diff --git a/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java b/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java
index 8011586950..e4a6956141 100644
--- a/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java
+++ b/src/com/vaadin/event/dd/acceptCriteria/ServerSideCriterion.java
@@ -5,15 +5,27 @@ package com.vaadin.event.dd.acceptCriteria;
 
 import java.io.Serializable;
 
+import com.vaadin.event.Transferable;
 import com.vaadin.terminal.PaintException;
 import com.vaadin.terminal.PaintTarget;
 import com.vaadin.terminal.gwt.client.ui.dd.VServerAccept;
 
 /**
- * TODO Javadoc
+ * Parent class for criteria that are verified on the server side during a drag
+ * operation to accept/discard dragged content (presented by
+ * {@link Transferable}).
  * 
- * @since 6.3
+ * Subclasses should implement the
+ * {@link AcceptCriterion#accepts(com.vaadin.event.dd.DragAndDropEvent)} method.
+ * 
+ * As all server side state can be used to make a decision, this is more
+ * flexible than {@link ClientSideCriterion}. However, this does require
+ * additional requests from the browser to the server during a drag operation.
  * 
+ * @see AcceptCriterion
+ * @see ClientSideCriterion
+ * 
+ * @since 6.3
  */
 @ClientCriterion(VServerAccept.class)
 public abstract class ServerSideCriterion implements Serializable,
diff --git a/src/com/vaadin/ui/Table.java b/src/com/vaadin/ui/Table.java
index 71ceb3a230..c0ac21b274 100644
--- a/src/com/vaadin/ui/Table.java
+++ b/src/com/vaadin/ui/Table.java
@@ -3340,7 +3340,15 @@ public class Table extends AbstractSelect implements Action.Container,
         requestRepaint();
     }
 
-    class TableTransferable extends DataBoundTransferable {
+    /**
+     * Concrete implementation of {@link DataBoundTransferable} for data
+     * transferred from a table.
+     * 
+     * @see {@link DataBoundTransferable}.
+     * 
+     * @since 6.3
+     */
+    protected class TableTransferable extends DataBoundTransferable {
 
         public TableTransferable(Map<String, Object> rawVariables) {
             super(Table.this, rawVariables);
@@ -3357,6 +3365,7 @@ public class Table extends AbstractSelect implements Action.Container,
 
         @Override
         public Object getPropertyId() {
+            // FIXME incorrect implementation, drag can also concern a cell
             return getItemCaptionPropertyId();
         }
 
diff --git a/src/com/vaadin/ui/Tree.java b/src/com/vaadin/ui/Tree.java
index 4c1c7136fb..9f3649ebe9 100644
--- a/src/com/vaadin/ui/Tree.java
+++ b/src/com/vaadin/ui/Tree.java
@@ -1220,11 +1220,14 @@ public class Tree extends AbstractSelect implements Container.Hierarchical,
     }
 
     /**
-     * TODO Javadoc!
+     * Concrete implementation of {@link DataBoundTransferable} for data
+     * transferred from a tree.
+     * 
+     * @see {@link DataBoundTransferable}.
      * 
      * @since 6.3
      */
-    public class TreeTransferable extends DataBoundTransferable {
+    protected class TreeTransferable extends DataBoundTransferable {
 
         public TreeTransferable(Component sourceComponent,
                 Map<String, Object> rawVariables) {
diff --git a/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java b/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java
index c07051ef32..38ecc308b5 100644
--- a/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java
+++ b/tests/src/com/vaadin/tests/dd/AcceptAnythingWindow.java
@@ -62,9 +62,7 @@ public class AcceptAnythingWindow extends Window {
 
                         } else {
                             // we have a component that is been dragged, add
-                            // it
-                            // to
-                            // this
+                            // it to this
                             layout.addComponent(component);
                         }
 
diff --git a/tests/src/com/vaadin/tests/dd/DDTest2.java b/tests/src/com/vaadin/tests/dd/DDTest2.java
index 929542b175..3a3fad5d54 100644
--- a/tests/src/com/vaadin/tests/dd/DDTest2.java
+++ b/tests/src/com/vaadin/tests/dd/DDTest2.java
@@ -139,10 +139,10 @@ public class DDTest2 extends TestBase {
                 DataBoundTransferable tr = (DataBoundTransferable) event
                         .getTransferable();
                 Object itemId = tr.getItemId();
-                Container sourceContainer = (Container) tr.getSourceComponent();
-                if (sourceContainer != tree1) {
+                Container sourceContainer = tr.getSourceContainer();
+                if (tr.getSourceComponent() != tree1) {
                     // if the source is from table (not from tree1 itself),
-                    // transfer Name property and use it as an indentifier in
+                    // transfer Name property and use it as an identifier in
                     // tree1
                     String name = sourceContainer.getItem(itemId)
                             .getItemProperty("Name").toString();
diff --git a/tests/src/com/vaadin/tests/dd/DDTest6.java b/tests/src/com/vaadin/tests/dd/DDTest6.java
index 39d1f1fb7b..6df55917fa 100644
--- a/tests/src/com/vaadin/tests/dd/DDTest6.java
+++ b/tests/src/com/vaadin/tests/dd/DDTest6.java
@@ -37,7 +37,6 @@ import com.vaadin.ui.Tree;
 import com.vaadin.ui.AbsoluteLayout.ComponentPosition;
 import com.vaadin.ui.Tree.TreeDragMode;
 import com.vaadin.ui.Tree.TreeDropTargetDetails;
-import com.vaadin.ui.Tree.TreeTransferable;
 
 public class DDTest6 extends TestBase {
 
@@ -311,7 +310,7 @@ public class DDTest6 extends TestBase {
 
                 // dragged something from tree to the folder shown
 
-                File draggedFile = (File) ((TreeTransferable) dropEvent
+                File draggedFile = (File) ((DataBoundTransferable) dropEvent
                         .getTransferable()).getItemId();
                 DDTest6.get().setParent(draggedFile, folder);
             }
diff --git a/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java b/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java
index 95011ffd42..fbaf70b276 100644
--- a/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java
+++ b/tests/src/com/vaadin/tests/dd/HorizontalLayoutSortableWithWrappers.java
@@ -96,7 +96,7 @@ public class HorizontalLayoutSortableWithWrappers extends Window {
     };
 
     public HorizontalLayoutSortableWithWrappers() {
-        setCaption("Horizontally sortable layout via (ddwrappers):Try sorting blocks by draggin them");
+        setCaption("Horizontally sortable layout via (ddwrappers): Try sorting blocks by dragging them");
         DragAndDropWrapper pane = new DragAndDropWrapper(layout);
         setContent(pane);
         pane.setSizeFull();