IFileServiceContants
- * @param monitor the progress monitor
* @since 3.0
*/
public IRemoteFile[] listMultiple(IRemoteFile[] parents, int[] fileTypes, IProgressMonitor monitor) throws SystemMessageException;
/**
- * Return a list of remote folders and/or files in the given folder. Only file names are filtered
- * by the given file name filters. It can be null for no sub-setting.
+ * Return a list of remote folders and/or files in the given folders.
+ * + * Semantics as well as exceptions thrown are the same as in + * {@link #list(IRemoteFile, String, IRemoteFileContext, int, IProgressMonitor)} + * , and a default context is assumed for all elements. Implementations are + * expected to update all parent remote file handles with updated status + * information. + *
+ * File names are filtered by the given file name filters; in case of
+ * retrieving folders only (type {@link IFileService#FILE_TYPE_FOLDERS},
+ * these are also subject to filtering for a parent, otherwise folders are
+ * unfiltered. A null filter performs no filtering.
+ *
+ * In case an error condition occurs while the operation is ongoing, but
+ * after some parents have been successfully queried, the implementation is
+ * expected to update status as well as children information on those parent
+ * IRemoteFile handles that were successfully queried as a side effect. The
+ * first error encountered stops the operation and is returned as a
+ * SystemMessageException. If clients want to know which of the parents have
+ * been successfully queried before an error occurred, they need to tag the
+ * parent handles in some way such that the required side-effect status
+ * information update clears that tag.
*
* @param parents The parent folders to list folders and files in
- * @param fileNameFilters The name patterns to subset the file list by, or null to return all files.
- * There should be exactly one fileNameFilter per parent.
- * @param fileTypes - indicates whether to query files, folders, both or some other type. There
- * should be exactly one fileType specified per parent.
- * For the default list of available file types see IFileServiceContants
+ * @param fileNameFilters The name patterns to subset the file list by, or
+ * null to return all files. There should be exactly one
+ * fileNameFilter per parent.
+ * @param fileTypes - indicates whether to query files, folders, both or
+ * some other type. There should be exactly one fileType
+ * specified per parent. For the default list of available file
+ * types see IFileServiceContants
* @param monitor the progress monitor
* @since 3.0
+ * @see #list(IRemoteFile, String, IRemoteFileContext, int,
+ * IProgressMonitor)
*/
public IRemoteFile[] listMultiple(IRemoteFile[] parents, String[] fileNameFilters, int[] fileTypes, IProgressMonitor monitor) throws SystemMessageException;
/**
- * Return a list of all remote folders and/or files in the given folders. This list is not filtered.
+ * Return a list of all remote folders and/or files in the given folders.
+ * Convenience method for
+ * {@link #listMultiple(IRemoteFile[], String[], int[], IProgressMonitor)}
+ * without a filter and querying the same file type kinds for all parents.
*
- * @param parents The parent folders to list folders and/or files in
- * @param fileType - indicates whether to query files, folders, both or some other type. This fileType is used for each parent query.
- * For the default list of available file types see IFileServiceContants
- * @param monitor the progress monitor
* @since 3.0
*/
public IRemoteFile[] listMultiple(IRemoteFile[] parents, int fileType, IProgressMonitor monitor) throws SystemMessageException;
/**
- * Return a list of remote folders and/or files in the given folder. Only file names are filtered
- * by the given file name filters. It can be null for no sub-setting.
+ * Return a list of remote folders and/or files in the given folders.
+ * Convenience method for
+ * {@link #listMultiple(IRemoteFile[], String[], int[], IProgressMonitor)}
+ * where the same file type kind is requested for all parents.
*
- * @param parents The parent folders to list folders and files in
- * @param fileNameFilters The name patterns to subset the file list by, or null to return all files.
- * There should be exactly one fileNameFilter per parent.
- * @param fileType - indicates whether to query files, folders, both or some other type.
- * Available file types include {@link IFileService#FILE_TYPE_FILES},
- * {@link IFileService#FILE_TYPE_FOLDERS}, and
- * {@link IFileService#FILE_TYPE_FILES_AND_FOLDERS}.
- * @param monitor the progress monitor
* @since 3.0
*/
public IRemoteFile[] listMultiple(IRemoteFile[] parents, String[] fileNameFilters, int fileType, IProgressMonitor monitor) throws SystemMessageException;
-
/**
- * Return a list of all remote folders and/or files in the given folder. The list is not filtered.
+ * Return a list of all remote folders and/or files in the given folder.
+ * Convenience method for
+ * {@link #list(IRemoteFile, String, IRemoteFileContext, int, IProgressMonitor)}
+ * with a default context, no filtering and returning both file and folder
+ * children.
*
- * @param parent The parent folder to list folders and/or files in
- * @param monitor the progress monitor
* @since 3.0
*/
public IRemoteFile[] list(IRemoteFile parent, IProgressMonitor monitor) throws SystemMessageException;
/**
- * Return a list of all remote folders and/or files in the given folder. The list is not filtered.
+ * Return a list of all remote folders and/or files in the given folder.
+ * Convenience method for
+ * {@link #list(IRemoteFile, String, IRemoteFileContext, int, IProgressMonitor)}
+ * with a default context and no filtering.
*
- * @param parent The parent folder to list folders and files in
- * @param fileType - indicates whether to query files, folders, both or some other type.
- * Available file types include {@link IFileService#FILE_TYPE_FILES},
- * {@link IFileService#FILE_TYPE_FOLDERS}, and
- * {@link IFileService#FILE_TYPE_FILES_AND_FOLDERS}.
- * @param monitor the progress monitor
* @since 3.0
*/
public IRemoteFile[] list(IRemoteFile parent, int fileType, IProgressMonitor monitor) throws SystemMessageException;
/**
- * Return a list of remote folders and/or files in the given folder. Only file names are filtered
- * by the given file name filter. It can be null for no filtering.
+ * Return a list of remote folders and/or files in the given folder.
+ * Convenience method for
+ * {@link #list(IRemoteFile, String, IRemoteFileContext, int, IProgressMonitor)}
+ * with a default context.
*
- * @param parent The parent folder to list folders and files in
- * @param fileNameFilter The name pattern to subset the file list by, or null to return all files.
- * @param fileType - indicates whether to query files, folders, both or some other type.
- * For the default list of available file types see IFileServiceContants
- * @param monitor the progress monitor
* @since 3.0
*/
public IRemoteFile[] list(IRemoteFile parent, String fileNameFilter, int fileType, IProgressMonitor monitor) throws SystemMessageException;
/**
- * Return a list of remote folders and/or files in the given folder. The files part of the list is filtered
- * by the given file name filter. It can be null for no filtering.
- *
- * @param parent The parent folder to list folders and files in
- * @param fileNameFilter The name pattern to subset the file list by, or null to return all files.
- * @param context The holder of state information
- * - indicates whether to query files, folders, both or some other type
- * @param fileType - indicates whether to query files, folders, both or some other type
- * For the default list of available file types see IFileServiceContants
- * @param monitor the progress monitor
+ * Return a list of remote folders and/or files in the given folder.
+ *
+ * The files part of the list is filtered by the given file name filter; in + * case only folders are requested by the file type ( + * {@link IFileService#FILE_TYPE_FOLDERS}), the folders are filtered by the + * given file name filter. Otherwise, the filter applies to the file names + * only, if folders are also requested they are not filtered. The filter can + * also be null for no filtering at all. + *
+ * Implementations are expected to update the status (properties) of the
+ * parent IRemoteFile as a side-effect of this call. Special folders like
+ * "." or ".." on UNIX must not be returned by the implementation.
+ *
+ * @param parent The parent folder to list folders and files in. The folder
+ * object must be updated to represent latest status as a
+ * side-effect of the query.
+ * @param fileNameFilter The name pattern to subset the file list by, or
+ * null to return all files.
+ * @param context The holder of state information - indicates whether to
+ * query files, folders, both or some other type
+ * @param fileType - indicates whether to query files, folders, both or some
+ * other type For the default list of available file types see
+ * {@link IFileService#FILE_TYPE_FILES} and related constants.
+ * @param monitor the progress monitor
+ * @throws SystemMessageException in case of any failure or cancellation.
+ * Exceptions expected for special situations include
+ * {@link SystemOperationCancelledException} in case of
+ * cancellation, {@link SystemElementNotFoundException} in case
+ * the parent folder did not exist,
+ * {@link SystemRemoteSecurityException} in case of a permission
+ * problem, and {@link SystemNetworkIOException} in case of a
+ * communication problem.
* @since 3.0
-
*/
public IRemoteFile[] list(IRemoteFile parent, String fileNameFilter, IRemoteFileContext context, int fileType, IProgressMonitor monitor) throws SystemMessageException;
-
-
/**
* Given a search configuration, searches for its results.
* @param searchConfig a search configuration.