From 954dc9c537d82c4e65b3e5b817abb845f71af266 Mon Sep 17 00:00:00 2001
From: Martin Oberhuber < martin.oberhuber@windriver.com>
Date: Wed, 26 Sep 2007 18:33:47 +0000
Subject: [PATCH] [204710] Update Javadoc to mention that getUserHome() may
 return null

---
 .../eclipse/rse/services/files/IFileService.java  | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

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 37659ba915e..d8e2ed6fb14 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
@@ -14,6 +14,7 @@
  * Martin Oberhuber (Wind River) - [186128] Move IProgressMonitor last in all API
  * Martin Oberhuber (Wind River) - [183824] Forward SystemMessageException from IRemoteFileSubsystem
  * Martin Oberhuber (Wind River) - [199548] Avoid touching files on setReadOnly() if unnecessary
+ * Martin Oberhuber (Wind River) - [204710] Update Javadoc to mention that getUserHome() may return null
  ********************************************************************************/
 
 package org.eclipse.rse.services.files;
@@ -153,8 +154,18 @@ public interface IFileService extends IService
 	public IHostFile[] getRoots(IProgressMonitor monitor) throws SystemMessageException;
 	
 	/**
-	 * @return the String containing the name of the user's home directory on this
-	 * connection that would be contained in implementations of this service.
+	 * Return the user's home directory on this connection.
+	 * 
+	 * The resulting IHostFile object is just a handle, so there is no guarantee 
+	 * that it refers to an existing file.
+	 * 
+	 * This method may also return <code>null</code> if the home directory could
+	 * not be determined (for instance, because the connection is not yet connected).
+	 * In this case, clients are encouraged to query the home directory again once
+	 * the connection is connected.
+	 *  
+	 * @return A handle to the current user's home directory, or <code>null</code>
+	 *     if the home directory could not be determined.  
 	 */
 	public IHostFile getUserHome();