improving documentation for Receiver

svn changeset:15569/svn branch:6.5

2 files changed, 26 insertions, 11 deletions

diff --git a/src/com/vaadin/terminal/PaintTarget.java b/src/com/vaadin/terminal/PaintTarget.java
index 52ac490863..3912af02dd 100644
--- a/src/com/vaadin/terminal/PaintTarget.java
+++ b/src/com/vaadin/terminal/PaintTarget.java
@@ -152,14 +152,21 @@ public interface PaintTarget extends Serializable {
     public void addAttribute(String name, Resource value) throws PaintException;
 
     /**
-     * Adds a Receiver attribute to component. Eg. in web terminals Receivers
-     * are typically URIs, where the client side can do an http post (multipart
-     * request).
+     * Adds details about {@link Receiver} to the UIDL stream. Eg. in web
+     * terminals Receivers are typically rendered for the client side as URLs,
+     * where the client side implementation can do an http post request.
+     * <p>
+     * Note that a Reveiver can only be used once per "paint". The same Receiver
+     * can be used several times, but it must be repainted before the next
+     * stream can be received.
      * 
+     * @param owner
+     *            the ReceiverOwner that can trac to progress of streaming to
+     *            given Receiver
      * @param name
-     *            the Attribute name
+     *            an identifying name for the Receiver
      * @param value
-     *            the Attribute value
+     *            the Receiver to paint
      * 
      * @throws PaintException
      *             if the paint operation failed.
diff --git a/src/com/vaadin/terminal/Receiver.java b/src/com/vaadin/terminal/Receiver.java
index 6958cfdf0b..38bf05d70f 100644
--- a/src/com/vaadin/terminal/Receiver.java
+++ b/src/com/vaadin/terminal/Receiver.java
@@ -4,23 +4,31 @@ import java.io.OutputStream;
 import java.io.Serializable;
 
 /**
- * 
- * Interface that must be implemented by the upload receivers to provide the
- * Upload component an output stream to write the uploaded data.
+ * Receiver is a special kind of variable which value is streamed to given
+ * {@link OutputStream}. E.g. in web terminals Receivers can be used to send
+ * large files from browsers to the server.
+ * <p>
+ * Note, writing to the {@link OutputStream} is not synchronized by the terminal
+ * (not to avoid stalls in other operations when eg. streaming to a slow network
+ * service). If UI is changed as a side effect of writing to given output
+ * stream, developer must handle synchronization manually.
+ * <p>
  * 
  * @author IT Mill Ltd.
  * @version
  * @VERSION@
  * @since 6.5
+ * @see PaintTarget#addVariable(ReceiverOwner, String, Receiver)
+ * @see ReceiverOwner
  */
 public interface Receiver extends Serializable {
 
     /**
-     * Invoked when a new upload arrives.
+     * Invoked by the terminal when a new upload arrives.
      * 
      * @param filename
-     *            the desired filename of the upload, usually as specified by
-     *            the client.
+     *            the filename of the upload if known by the terminal, usually
+     *            as specified by the client.
      * @param MIMEType
      *            the MIME type of the uploaded file.
      * @return Stream to which the uploaded file should be written.