[234026] Clarify IFileService#createFolder() Javadocs

rse/plugins/org.eclipse.rse.efs/src/org/eclipse/rse/internal/efs/RSEFileStoreImpl.java

@@ -30,6 +30,7 @@
  * David Dykstal (IBM) [230821] fix IRemoteFileSubSystem API to be consistent with IFileService
  * Martin Oberhuber (Wind River) - [233993] Improve EFS error reporting
  * Martin Oberhuber (Wind River) - [220300] EFS Size Property not properly updated after saving
+ * Martin Oberhuber (Wind River) - [234026] Clarify IFileService#createFolder() Javadocs
  ********************************************************************************/
 
 package org.eclipse.rse.internal.efs;
@@ -636,14 +637,6 @@ public class RSEFileStoreImpl extends FileStore
 	 */
 	public IFileStore mkdir(int options, IProgressMonitor monitor) throws CoreException
 	{
-		//TODO bug 234026: Check should be done by IRemoteFileSubSystem.createFolders()
-		if ((options & EFS.SHALLOW) == 0) {
-			IFileStore parent = getParent();
-			if (parent != null) {
-				parent.mkdir(options, monitor);
-			}
-		}
-
 		cacheRemoteFile(null);
 		IRemoteFile remoteFile = getRemoteFileObject(monitor, false);
 		if (remoteFile==null) {
@@ -656,7 +649,8 @@ public class RSEFileStoreImpl extends FileStore
 		if (!remoteFile.exists()) {
 			try {
 				if ((options & EFS.SHALLOW) != 0) {
-					//TODO following check should be obsolete
+					//MUST NOT create parents, so we need to check ourselves
+					//here according to IRemoteFileSubSystem.createFolder() docs
 					if (!remoteFile.getParentRemoteFile().exists()) {
 						throw new CoreException(new Status(IStatus.ERROR,
 								Activator.getDefault().getBundle().getSymbolicName(),

rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java

@@ -26,6 +26,7 @@
  * David Dykstal (IBM) - [221211] clarifying javadoc on batch operations
  * David Dykstal (IBM) - [221211] fix IFileService API for batch operations
  * Radoslav Gerganov (ProSyst) - [230919] IFileService.delete() should not return a boolean
+ * Martin Oberhuber (Wind River) - [234026] Clarify IFileService#createFolder() Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.services.files;
@@ -396,6 +397,12 @@ public interface IFileService extends IService
 	/**
 	 * Create a folder on the host.
 	 *
+	 * Implementations are free to create missing parent folders or fail with a
+	 * SystemMessageException if the parent folder does not yet exist. In
+	 * general, creating missing parent folders is recommended if it doesn't
+	 * require additional client-server round trips. Therefore the "Local" and
+	 * "DStore" services do create missing parent folders.
+	 *
 	 * @param remoteParent the parent directory
 	 * @param folderName the name of the new folder
 	 * @param monitor the progress monitor
@@ -407,14 +414,14 @@ public interface IFileService extends IService
 
 	/**
 	 * Delete a file or folder on the host.
-	 * 
+	 *
 	 * @param remoteParent the folder containing the file to delete
 	 * @param fileName the name of the file or folder to delete
 	 * @param monitor the progress monitor
 	 * @throws SystemMessageException if an error occurs or the user canceled
 	 * 		the operation. SystemElementNotFoundException is thrown if the remote
 	 * 		file doesn't exist.
-	 * 
+	 *
 	 * @since org.eclipse.rse.services 3.0
 	 */
 	public void delete(String remoteParent, String fileName, IProgressMonitor monitor) throws SystemMessageException;

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/servicesubsystem/FileServiceSubSystem.java

@@ -42,6 +42,7 @@
  * Martin Oberhuber (Wind River) - [235360][ftp][ssh][local] Return proper "Root" IHostFile
  * David McKnight   (IBM)        - [223461] [Refresh][api] Refresh expanded folder under filter refreshes Filter
  * Martin Oberhuber (Wind River) - [240704] Protect against illegal API use of getRemoteFileObject() with relative path as name
+ * Martin Oberhuber (Wind River) - [234026] Clarify IFileService#createFolder() Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.subsystems.files.core.servicesubsystem;
@@ -924,7 +925,39 @@ public class FileServiceSubSystem extends RemoteFileSubSystem implements IFileSe
 
 	public IRemoteFile createFolders(IRemoteFile folderToCreate, IProgressMonitor monitor) throws SystemMessageException
 	{
+		try {
+			//As per IFileService#createFolder() API Docs, Services *may* create parent folders.
+			//Therefore, first try this shortcut before actually iterating to create parents.
 			return createFolder(folderToCreate, monitor);
+		} catch (SystemMessageException e) {
+			//Parent did not exist? Need to create parent folders on this Service
+			IFileService service = getFileService();
+			List parents = new ArrayList();
+			IRemoteFile parent = folderToCreate;
+			while (!parent.isRoot()) {
+				parent = parent.getParentRemoteFile();
+				IHostFile parentFile = service.getFile(parent.getParentPath(), parent.getName(), monitor);
+				if (parentFile.exists()) {
+					//Update cache with newest info, since we just got it
+					getHostFileToRemoteFileAdapter().convertToRemoteFile(this, getDefaultContext(), parent.getParentRemoteFile(), parentFile);
+					break;
+				} else {
+					parents.add(parent);
+				}
+			}
+			if (parents.size()==0) {
+				//No parents missing -- throw original exception
+				throw e;
+			}
+			for (int i=parents.size()-1; i>=0; i--) {
+				parent = (IRemoteFile)parents.get(i);
+				// Remote side will change due to createFolder, so mark it stale
+				parent.markStale(true, true);
+				// Create new folder and cache the contents
+				createFolder(parent, monitor);
+			}
+			return createFolder(folderToCreate, monitor);
+		}
 	}
 
 	/**

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFileSubSystem.java

@@ -22,6 +22,7 @@
  * David McKnight   (IBM)        - [209704] added supportsEncodingConversion()
  * Martin Oberhuber (Wind River) - [226574][api] Add ISubSystemConfiguration#supportsEncoding()
  * David Dykstal (IBM) [230821] fix IRemoteFileSubSystem API to be consistent with IFileService
+ * Martin Oberhuber (Wind River) - [234026] Clarify IFileService#createFolder() Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.subsystems.files.core.subsystems;
@@ -327,9 +328,11 @@ public interface IRemoteFileSubSystem extends ISubSystem {
 	 * Create a new folder, given its IRemoteFile object (these do not have to represent existing folders)
 	 * <p>
 	 * <ul>
-	 *    <li>The parent folder must exist for this to succeed.
+	 *    <li>The parent folder must exist for this to succeed. If the parent 
-	 *    <li>If this folder already exists, this is a no-op.
+	 *        folder does not yet exist, implementations are free to create
-	 *    <li>If the given object is a file, not a folder, this is a no-op.
+	 *        missing parents or fail (see also {@link IFileService#createFolder(String, String, IProgressMonitor)}).</li>
+	 *    <li>If this folder already exists, this is a no-op.</li>
+	 *    <li>If the given object is a file, not a folder, this is a no-op.</li>
 	 * </ul>
 	 *
 	 * @see #createFolders(IRemoteFile, IProgressMonitor)