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 078d6f3a866..cab7f5d7ad9 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 @@ -28,6 +28,7 @@ * Radoslav Gerganov (ProSyst) - [230919] IFileService.delete() should not return a boolean * Martin Oberhuber (Wind River) - [234026] Clarify IFileService#createFolder() Javadocs * Martin Oberhuber (Wind River) - [274568] Dont use SftpMonitor for Streams transfer + * Martin Oberhuber (Wind River) - [285942][api] Throw exception if list() on a non-folder *******************************************************************************/ package org.eclipse.rse.services.files; @@ -262,7 +263,6 @@ public interface IFileService extends IService */ public IHostFile getFile(String remoteParent, String name, IProgressMonitor monitor) throws SystemMessageException; - /** * List the contents of a remote folder. * @@ -276,7 +276,9 @@ public interface IFileService extends IService * @param monitor the monitor for this potentially long running operation * @return the list of host files. * @throws SystemMessageException if an error occurs. Typically this would - * be one of those in the RemoteFileException family. + * be one of those in the RemoteFileException family. Exceptions + * are particularly expected when the remoteParent does not + * exist, or is not a folder. * * @since org.eclipse.rse.services 3.0 */ @@ -304,9 +306,11 @@ public interface IFileService extends IService /** * List the contents of multiple remote folders. *

- * If an error occurs during the retrieval of the contents of a folder, this operation stops on that folder and a {@link SystemMessageException} is thrown. - * Items retrieved before that folder will be returned. Items in folders after that folder will not be retrieved. - * The items in the folder on which the error occurs will not be returned. + * If an error occurs during the retrieval of the contents of a folder, this + * operation stops on that folder and a {@link SystemMessageException} is + * thrown. Items retrieved before that folder will be returned. Items in + * folders after that folder will not be retrieved. The items in the folder + * on which the error occurs will not be returned. * * @param remoteParents - the names of the parent directories on the remote * file system from which to retrieve the collective child list. @@ -319,10 +323,13 @@ public interface IFileService extends IService * some other type. For each remoteParent, there must be a * corresponding fileType. For the default list of available file * types see IFileServiceContants - * @param hostFiles a list to which the found {@link IHostFile} objects will be appended + * @param hostFiles a list to which the found {@link IHostFile} objects will + * be appended * @param monitor the monitor for this potentially long running operation * @throws SystemMessageException if an error occurs. Typically this would - * be one of those in the RemoteFileException family. + * be one of those in the RemoteFileException family. Exceptions + * are particularly expected when a remoteParent does not exist, + * or is not a folder. * * @since org.eclipse.rse.services 3.0 */ @@ -331,10 +338,12 @@ public interface IFileService extends IService /** * List the contents of multiple remote folders. *

- * If an error occurs during the retrieval of the contents of a folder, this operation stops on that folder and a {@link SystemMessageException} is thrown. - * Items retrieved before that folder will be returned. Items in folders after that folder will not be retrieved. - * The items in the folder on which the error occurs will not be returned. - * + * If an error occurs during the retrieval of the contents of a folder, this + * operation stops on that folder and a {@link SystemMessageException} is + * thrown. Items retrieved before that folder will be returned. Items in + * folders after that folder will not be retrieved. The items in the folder + * on which the error occurs will not be returned. + * * @param remoteParents - the names of the parent directories on the remote * file system from which to retrieve the collective child list. * @param fileFilters - a set of strings that can be used to filter the @@ -346,11 +355,14 @@ public interface IFileService extends IService * other type. All results will be of the specified type. For the * default list of available file types see * IFileServiceContants - * @param hostFiles a list to which the found {@link IHostFile} objects will be appended + * @param hostFiles a list to which the found {@link IHostFile} objects will + * be appended * @param monitor the monitor for this potentially long running operation * @throws SystemMessageException if an error occurs. Typically this would - * be one of those in the RemoteFileException family. - * + * be one of those in the RemoteFileException family. Exceptions + * are particularly expected when a remoteParent does not exist, + * or is not a folder. + * * @since org.eclipse.rse.services 3.0 */ public void listMultiple(String[] remoteParents, String[] fileFilters, int fileType, List hostFiles, IProgressMonitor monitor) throws SystemMessageException;