Added documentation/javadocs for sendRetrieveRequest

2 files changed, 27 insertions, 5 deletions

diff --git a/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/IRetrieveFileTransferContainerAdapter.java b/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/IRetrieveFileTransferContainerAdapter.java
index d1183a9be..904b49d4c 100644
--- a/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/IRetrieveFileTransferContainerAdapter.java
+++ b/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/IRetrieveFileTransferContainerAdapter.java
@@ -72,7 +72,14 @@ public interface IRetrieveFileTransferContainerAdapter extends IAdaptable {
 	 * parameter). File transfer events are asynchronously delivered a file
 	 * transfer listener (second parameter). The given remoteFileID and
 	 * transferListener must not be null.
-	 * 
+	 * <p>
+	 * <b>NOTE</b>: if this method completes successfully, the given transferListener 
+	 * will be asynchronously notified via an IIncomingFileTransferReceiveDoneEvent 
+	 * (along with other possible events).  All implementations are required to 
+	 * issue this event whether successful or failed.  Listeners
+	 * can consult {@link IIncomingFileTransferReceiveDoneEvent#getClass()} to 
+	 * determine whether the transfer operation completed successfully.
+	 * </p>
 	 * @param remoteFileID
 	 *            reference to the remote target file (e.g.
 	 *            http://www.eclipse.org/index.html) or a reference to a
@@ -92,7 +99,7 @@ public interface IRetrieveFileTransferContainerAdapter extends IAdaptable {
 	 * 
 	 * Must not be <code>null</code>.
 	 * @param transferListener
-	 *            a listener for file transfer events. Must not be null
+	 *            a listener for file transfer events. Must not be null.  Must not be null.  See <b>Note</b> above.
 	 * @param options
 	 *            a Map of options associated with sendRetrieveRequest. The
 	 *            particular name/value pairs will be unique to the individual
@@ -109,7 +116,14 @@ public interface IRetrieveFileTransferContainerAdapter extends IAdaptable {
 	 * parameter). File transfer events are asynchronously delivered a file
 	 * transfer listener (third parameter). The given remoteFileID and
 	 * transferListener must not be null.
-	 * 
+	 * <p>
+	 * <b>NOTE</b>: if this method completes successfully, the given transferListener 
+	 * will be asynchronously notified via an IIncomingFileTransferReceiveDoneEvent 
+	 * (along with other possible events).  All implementations are required to 
+	 * issue this event whether successful or failed.  Listeners
+	 * can consult {@link IIncomingFileTransferReceiveDoneEvent#getClass()} to 
+	 * determine whether the transfer operation completed successfully.
+	 * </p>
 	 * @param remoteFileID
 	 *            reference to the remote target file (e.g.
 	 *            http://www.eclipse.org/index.html) or a reference to a
@@ -134,7 +148,7 @@ public interface IRetrieveFileTransferContainerAdapter extends IAdaptable {
 	 * rangeSpecification has a start value of 1 and end value of 3, and the total length of the file is
 	 * 5 bytes with content [a, b, c, d, e], a successful retrieve request would transfer bytes 'b', 'c', and 'd', but not 'a', and 'e'.
 	 * @param transferListener
-	 *            a listener for file transfer events. Must not be null
+	 *            a listener for file transfer events. Must not be null.  See <b>Note</b> above.
 	 * @param options
 	 *            a Map of options associated with sendRetrieveRequest. The
 	 *            particular name/value pairs will be unique to the individual
diff --git a/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/events/IRemoteFileSystemBrowseEvent.java b/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/events/IRemoteFileSystemBrowseEvent.java
index ec433a36a..6a4b598d1 100644
--- a/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/events/IRemoteFileSystemBrowseEvent.java
+++ b/framework/bundles/org.eclipse.ecf.filetransfer/src/org/eclipse/ecf/filetransfer/events/IRemoteFileSystemBrowseEvent.java
@@ -1,5 +1,5 @@
 /****************************************************************************
- * Copyright (c) 2007 Composent, Inc. and others.
+ * Copyright (c) 2007, 2009 Composent, Inc., IBM and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -7,6 +7,7 @@
  *
  * Contributors:
  *    Composent, Inc. - initial API and implementation
+ *    Henrich Kraemer - bug 263613, [transport] Update site contacting / downloading is not cancelable
  *****************************************************************************/
 
 package org.eclipse.ecf.filetransfer.events;
@@ -15,6 +16,10 @@ import org.eclipse.ecf.filetransfer.IRemoteFile;
 
 /**
  * Event that indicates that a directory list is available via {@link #getRemoteFiles()}.
+ * <p>
+ * This event is fired even if the browse failed or has been canceled. In this case
+ * the cause is provided via {@link #getException()}.
+ * </p> 
  */
 public interface IRemoteFileSystemBrowseEvent extends IRemoteFileSystemEvent {
 
@@ -22,9 +27,12 @@ public interface IRemoteFileSystemBrowseEvent extends IRemoteFileSystemEvent {
 	 * Get the list of files associated with this browse event.  If the original
 	 * file ID available via {@link IRemoteFileSystemEvent#getFileID()} is a regular
 	 * file, the array will be of length 1.  If a directory, will be of length n.
+	 * Is null if the associated IRemoteFileSystemRequest failed or was canceled.
+	 * The cause will be available in {@link #getException()}. 
 	 * @return IRemoteFile[] the array of remote files for the given browse.  If the original
 	 * file ID available via {@link IRemoteFileSystemEvent#getFileID()} is a regular
 	 * file, the array will be of length 1.  If a directory, will be of length n.
+	 * May be null. 
 	 */
 	public IRemoteFile[] getRemoteFiles();