org.eclipse.rse.services.files
Interface IFileService

All Superinterfaces:

IService

All Known Implementing Classes:

AbstractFileService

public interface IFileService
extends IService

A IFileService is an abstraction of a file service that runs over some sort of connection. It can be shared among multiple instances of a subsystem. At some point this file service layer may become official API but for now it is experimental. Each subsystem is currently responsible for layering an abstraction over whatever it wants to construct as a service.

This is a very bare bones definition. A real definition would probably have changed terminology, use URI's rather than Strings, and have much more robust error handling.

Implementers of this interface will have to either be instantiated, initialized, or somehow derive a connection as part of its state.

Method Summary

boolean	copy(String srcParent, String srcName, String tgtParent, String tgtName, IProgressMonitor monitor) Copy the file or folder to the specified destination
boolean	copyBatch(String[] srcParents, String[] srcNames, String tgtParent, IProgressMonitor monitor) Copy a set of files or folders to the specified destination
IHostFile	createFile(String remoteParent, String fileName, IProgressMonitor monitor) Create a file on the host
IHostFile	createFolder(String remoteParent, String folderName, IProgressMonitor monitor) Create a folder on the host
boolean	delete(String remoteParent, String fileName, IProgressMonitor monitor) Deletes a file or folder on the host
boolean	deleteBatch(String[] remoteParents, String[] fileNames, IProgressMonitor monitor) Deletes a set of files or folders on the host.
boolean	download(String remoteParent, String remoteFile, File localFile, boolean isBinary, String hostEncoding, IProgressMonitor monitor) Copy a file from the remote file system to the local system.
String	getEncoding(IProgressMonitor monitor) Gets the remote encoding.
IHostFile	getFile(String remoteParent, String name, IProgressMonitor monitor)
IHostFile[]	getFiles(String remoteParent, String fileFilter, IProgressMonitor monitor)
IHostFile[]	getFilesAndFolders(String remoteParent, String fileFilter, IProgressMonitor monitor)
IHostFile[]	getFolders(String remoteParent, String fileFilter, IProgressMonitor monitor)
InputStream	getInputStream(String remoteParent, String remoteFile, boolean isBinary, IProgressMonitor monitor) Gets the input stream to access the contents a remote file.
OutputStream	getOutputStream(String remoteParent, String remoteFile, boolean isBinary, IProgressMonitor monitor) Gets the output stream to write to a remote file.
IHostFile[]	getRoots(IProgressMonitor monitor)
IHostFile	getUserHome() Return the user's home directory on this connection.
boolean	isCaseSensitive() Indicates whether the file system is case sensitive
boolean	move(String srcParent, String srcName, String tgtParent, String tgtName, IProgressMonitor monitor) Move the file or folder specified
boolean	rename(String remoteParent, String oldName, String newName, IHostFile oldFile, IProgressMonitor monitor) Renames a file or folder on the host
boolean	rename(String remoteParent, String oldName, String newName, IProgressMonitor monitor) Renames a file or folder on the host
boolean	setLastModified(String parent, String name, long timestamp, IProgressMonitor monitor) Sets the last modified stamp of the file or folder with the specified timestamp
boolean	setReadOnly(String parent, String name, boolean readOnly, IProgressMonitor monitor) Sets the readonly permission of the file or folder
boolean	upload(File localFile, String remoteParent, String remoteFile, boolean isBinary, String srcEncoding, String hostEncoding, IProgressMonitor monitor) Copy a file to the remote file system.
boolean	upload(InputStream stream, String remoteParent, String remoteFile, boolean isBinary, String hostEncoding, IProgressMonitor monitor) Copy a file to the remote file system.

Methods inherited from interface org.eclipse.rse.services.IService

getDescription, getMessage, getName, initService, uninitService

Method Detail

upload

boolean upload(InputStream stream,
               String remoteParent,
               String remoteFile,
               boolean isBinary,
               String hostEncoding,
               IProgressMonitor monitor)
               throws SystemMessageException

Copy a file to the remote file system. The remote target is denoted by a string representing the parent and a string representing the file.

Parameters:

stream - input stream to transfer

remoteParent - - a string designating the parent folder of the target for this file.

remoteFile - - a string designating the name of the file to be written on the remote system.

isBinary - - indicates whether the file is text or binary

hostEncoding - - the tgt encoding of the file (if text)

monitor - the monitor for this potentially long running operation

Returns:

true if the file was uploaded

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

upload

boolean upload(File localFile,
               String remoteParent,
               String remoteFile,
               boolean isBinary,
               String srcEncoding,
               String hostEncoding,
               IProgressMonitor monitor)
               throws SystemMessageException

Copy a file to the remote file system. The remote target is denoted by a string representing the parent and a string representing the file.

Parameters:

localFile - - a real file in the local file system.

remoteParent - - a string designating the parent folder of the target for this file.

remoteFile - - a string designating the name of the file to be written on the remote system.

isBinary - - indicates whether the file is text or binary

srcEncoding - - the src encoding of the file (if text)

hostEncoding - - the tgt encoding of the file (if text)

monitor - the monitor for this potentially long running operation

Returns:

true if the file was uploaded

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

download

boolean download(String remoteParent,
                 String remoteFile,
                 File localFile,
                 boolean isBinary,
                 String hostEncoding,
                 IProgressMonitor monitor)
                 throws SystemMessageException

Copy a file from the remote file system to the local system.

Parameters:

remoteParent - - a String designating the remote parent.

remoteFile - - a String designating the remote file residing in the parent.

localFile - - The file that is to be written. If the file exists it is overwritten.

isBinary - - indicates whether the file is text on binary

hostEncoding - - the encoding on the host (if text)

monitor - the monitor for this potentially long running operation

Returns:

true if the file was copied from the remote system.

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

getFile

IHostFile getFile(String remoteParent,
                  String name,
                  IProgressMonitor monitor)
                  throws SystemMessageException

Parameters:

remoteParent -

name -

monitor - the monitor for this potentially long running operation

Returns:

the host file given the parent path and file name. Must not return null, non-existing files should be reported with an IHostFile object where IHostFile.exists() returns false.

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

getFilesAndFolders

IHostFile[] getFilesAndFolders(String remoteParent,
                               String fileFilter,
                               IProgressMonitor monitor)
                               throws SystemMessageException

Parameters:

remoteParent - - the name of the parent directory on the remote file system from which to retrieve the child list.

fileFilter - - a string that can be used to filter the children. Only those files matching the filter make it into the list. The interface does not dictate where the filtering occurs.

monitor - the monitor for this potentially long running operation

Returns:

the list of host files.

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

getFiles

IHostFile[] getFiles(String remoteParent,
                     String fileFilter,
                     IProgressMonitor monitor)
                     throws SystemMessageException

Parameters:

remoteParent - - the name of the parent directory on the remote file system from which to retrieve the child list.

fileFilter - - a string that can be used to filter the children. Only those files matching the filter make it into the list. The interface does not dictate where the filtering occurs.

monitor - the monitor for this potentially long running operation

Returns:

the list of host files.

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

getFolders

IHostFile[] getFolders(String remoteParent,
                       String fileFilter,
                       IProgressMonitor monitor)
                       throws SystemMessageException

Parameters:

remoteParent - - the name of the parent directory on the remote file system from which to retrieve the child list.

fileFilter - - a string that can be used to filter the children. Only those files matching the filter make it into the list. The interface does not dictate where the filtering occurs.

monitor - the monitor for this potentially long running operation

Returns:

the list of host files.

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

getRoots

IHostFile[] getRoots(IProgressMonitor monitor)
                     throws SystemMessageException

Parameters:

monitor - the monitor for this potentially long running operation Return the list of roots for this system

Returns:

the list of host files.

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

getUserHome

IHostFile getUserHome()

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 null 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.

Returns:

A handle to the current user's home directory, or null if the home directory could not be determined.

createFile

IHostFile createFile(String remoteParent,
                     String fileName,
                     IProgressMonitor monitor)
                     throws SystemMessageException

Create a file on the host

Parameters:

remoteParent - the parent directory

fileName - the name of the new file

monitor - the monitor for this potentially long running operation

Returns:

the newly created file

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

createFolder

IHostFile createFolder(String remoteParent,
                       String folderName,
                       IProgressMonitor monitor)
                       throws SystemMessageException

Create a folder on the host

Parameters:

remoteParent - the parent directory

folderName - the name of the new folder

monitor - the progress monitor

Returns:

the newly created folder

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

delete

boolean delete(String remoteParent,
               String fileName,
               IProgressMonitor monitor)
               throws SystemMessageException

Deletes a file or folder on the host

Parameters:

remoteParent - the folder containing the file to delete

fileName - the name of the file or folder to delete

monitor - the progress monitor

Returns:

true if successful

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

deleteBatch

boolean deleteBatch(String[] remoteParents,
                    String[] fileNames,
                    IProgressMonitor monitor)
                    throws SystemMessageException

Deletes a set of files or folders on the host. Should throw an exception if some files and folders were deleted and others were not due to an exception during the operation. Without an exception thrown in such cases, views may not be refreshed correctly to account for deleted resources.

Parameters:

remoteParents - the array of folders containing the files to delete

fileNames - the names of the files or folders to delete

monitor - the progress monitor

Returns:

true iff all deletes are successful

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

rename

boolean rename(String remoteParent,
               String oldName,
               String newName,
               IProgressMonitor monitor)
               throws SystemMessageException

Renames a file or folder on the host

Parameters:

remoteParent - the folder containing the file to rename

oldName - the old name of the file or folder to rename

newName - the new name for the file

monitor - the progress monitor

Returns:

true if successful

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

rename

boolean rename(String remoteParent,
               String oldName,
               String newName,
               IHostFile oldFile,
               IProgressMonitor monitor)
               throws SystemMessageException

Renames a file or folder on the host

Parameters:

remoteParent - the folder containing the file to rename

oldName - the old name of the file or folder to rename

newName - the new name for the file

oldFile - the file to update with the change

monitor - the progress monitor

Returns:

true if successful

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

move

boolean move(String srcParent,
             String srcName,
             String tgtParent,
             String tgtName,
             IProgressMonitor monitor)
             throws SystemMessageException

Move the file or folder specified

Parameters:

srcParent - the folder containing the file or folder to move

srcName - the new of the file or folder to move

tgtParent - the destination folder for the move

tgtName - the name of the moved file or folder

monitor - the progress monitor

Returns:

true if the file was moved

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

copy

boolean copy(String srcParent,
             String srcName,
             String tgtParent,
             String tgtName,
             IProgressMonitor monitor)
             throws SystemMessageException

Copy the file or folder to the specified destination

Parameters:

srcParent - the folder containing the file or folder to copy

srcName - the new of the file or folder to copy

tgtParent - the destination folder for the copy

tgtName - the name of the copied file or folder

monitor - the progress monitor

Returns:

true if the file was copied successfully

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

copyBatch

boolean copyBatch(String[] srcParents,
                  String[] srcNames,
                  String tgtParent,
                  IProgressMonitor monitor)
                  throws SystemMessageException

Copy a set of files or folders to the specified destination

Parameters:

srcParents - the folders containing each file or folder to copy

srcNames - the names of the files or folders to copy

tgtParent - the destination folder for the copy

monitor - the progress monitor

Returns:

true if all files were copied

Throws:

SystemMessageException - if an error occurs. Typically this would be one of those in the RemoteFileException family.

isCaseSensitive

boolean isCaseSensitive()

Indicates whether the file system is case sensitive

Returns:

true if the file system has case sensitive file names

setLastModified

boolean setLastModified(String parent,
                        String name,
                        long timestamp,
                        IProgressMonitor monitor)
                        throws SystemMessageException

Sets the last modified stamp of the file or folder with the specified timestamp

Parameters:

parent - the parent path of the file to set

name - the name of the file to set

timestamp - the new timestamp

monitor - the progress monitor

Returns:

true if the file timestamp was changed successfully

Throws:

SystemMessageException

setReadOnly

boolean setReadOnly(String parent,
                    String name,
                    boolean readOnly,
                    IProgressMonitor monitor)
                    throws SystemMessageException

Sets the readonly permission of the file or folder

Parameters:

parent - the parent path of the file to set

name - the name of the file to set

readOnly - indicates whether to make the file readonly or read-write

monitor - the progress monitor

Returns:

true if the readonly permission was changed successfully, or the permission already was as desired

Throws:

SystemMessageException

getEncoding

String getEncoding(IProgressMonitor monitor)
                   throws SystemMessageException

Gets the remote encoding.

Parameters:

monitor - the progress monitor.

Returns:

the encoding.

Throws:

SystemMessageException - if an error occurs.

Since:

2.0

getInputStream

InputStream getInputStream(String remoteParent,
                           String remoteFile,
                           boolean isBinary,
                           IProgressMonitor monitor)
                           throws SystemMessageException

Gets the input stream to access the contents a remote file. Clients should close the input stream when done.

Parameters:

remoteParent - the absolute path of the parent.

remoteFile - the name of the remote file.

isBinary - true if the file is a binary file, false otherwise.

monitor - the progress monitor.

Returns:

the input stream to access the contents of the remote file.

Throws:

SystemMessageException - if an error occurs.

Since:

2.0

getOutputStream

OutputStream getOutputStream(String remoteParent,
                             String remoteFile,
                             boolean isBinary,
                             IProgressMonitor monitor)
                             throws SystemMessageException

Gets the output stream to write to a remote file. Clients should close the output stream when done.

Parameters:

remoteParent - the absolute path of the parent.

remoteFile - the name of the remote file.

isBinary - true if the file is a binary file, false otherwise.

monitor - the progress monitor.

Returns:

the input stream to access the contents of the remote file.

Throws:

SystemMessageException - if an error occurs.

Since:

2.0