From: Matti Tahvonen Date: Wed, 17 Mar 2010 15:35:41 +0000 (+0000) Subject: DD related javadocs, cleanup, small refactoring X-Git-Tag: 6.7.0.beta1~1905 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=0a049a0d913a548cd327542320bc8c22f5184f91;p=vaadin-framework.git DD related javadocs, cleanup, small refactoring svn changeset:11938/svn branch:6.3 --- 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. + *

+ * 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. + *

+ * 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. * *

- * Translator should remove variables it handled from rawVariables. All non - * handled variables are added to Transferable automatically by terminal. - *

- * + * 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. *

* * @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 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. + *

+ * 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. + *

+ * Based on information from {@link AcceptCriterion} components may display + * some hints for the end user whether the drop will be accepted or not. + *

+ * 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. *

- * 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}. + *

+ * 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 data = new HashMap(); + private DropTarget dropTarget; - public DropTargetDetailsImpl(Map rawDropData) { + protected DropTargetDetailsImpl(Map rawDropData) { data.putAll(rawDropData); } + public DropTargetDetailsImpl(Map 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). *

- * 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,