From 17795ab5793099a61aa6634d077640a62230828f Mon Sep 17 00:00:00 2001
From: Martin Oberhuber < martin.oberhuber@windriver.com>
Date: Fri, 27 Jul 2007 17:14:55 +0000
Subject: [PATCH] Improve Javadoc of IHostFile#getFile()

---
 .../rse/internal/services/ssh/files/SftpFileService.java     | 5 +++--
 .../src/org/eclipse/rse/services/files/IFileService.java     | 5 ++++-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/rse/plugins/org.eclipse.rse.services.ssh/src/org/eclipse/rse/internal/services/ssh/files/SftpFileService.java b/rse/plugins/org.eclipse.rse.services.ssh/src/org/eclipse/rse/internal/services/ssh/files/SftpFileService.java
index b1497b478ee..523f867c021 100644
--- a/rse/plugins/org.eclipse.rse.services.ssh/src/org/eclipse/rse/internal/services/ssh/files/SftpFileService.java
+++ b/rse/plugins/org.eclipse.rse.services.ssh/src/org/eclipse/rse/internal/services/ssh/files/SftpFileService.java
@@ -245,9 +245,10 @@ public class SftpFileService extends AbstractFileService implements IFileService
 	
 	public IHostFile getFile(String remoteParent, String fileName, IProgressMonitor monitor) throws SystemMessageException
 	{
-		//TODO getFile() must return a dummy even for non-existent files,
-		//or the move() operation will fail. This needs to be described in 
+		//getFile() must return a dummy even for non-existent files,
+		//or the move() operation will fail. This is described in 
 		//the API docs.
+		//TODO when monitor is canceled, it is unclear whether we should return an empty file node or throw a canceled exception.
 		SftpHostFile node = null;
 		SftpATTRS attrs = null;
 		if (fDirChannelMutex.waitForLock(monitor, fDirChannelTimeout)) {
diff --git a/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java b/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java
index 55bbf157b72..86ffb00d11e 100644
--- a/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java
+++ b/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java
@@ -94,7 +94,10 @@ public interface IFileService extends IService
 	 * @param remoteParent
 	 * @param name
 	 * @param monitor the monitor for this potentially long running operation
-	 * @return the host file given the parent path and file name
+	 * @return the host file given the parent path and file name.
+	 *     Must not return <code>null</code>, non-existing files should be
+	 *     reported with an IHostFile object where {@link IHostFile#exists()}
+	 *     returns <code>false</code>.
 	 * @throws SystemMessageException if an error occurs. 
 	 * Typically this would be one of those in the RemoteFileException family.
 	 */