com.maverick.sshd.sftp

Interface FileSystem<T extends FileSystemMount>

All Known Implementing Classes:

AbstractFileSystem

public interface FileSystem<T extends FileSystemMount>

Provides native file system access for the built in SFTP server. Your server may implement the methods here to provide file system support. This is an optional feature since the server is preconfigured to use the VirtualFileSystem.

The SFTP protocol represents file names as strings. File names are assumed to use the slash ('/') character as a directory separator.

File names starting with a slash are "absolute", and are relative to the root of the file system. Names starting with any other character are relative to the user's default directory (home directory). It should noted that Windows style paths ARE NOT supported by the Virtual file system. Any path not starting with / are relative to the users home directory.

Implementations SHOULD interpret a path name component ".." as referring to the parent directory, and "." as referring to the current directory. If the implementation limits access to certain parts of the file system, it must be extra careful in parsing file names when enforcing such restrictions. There have been numerous reported security bugs where a ".." in a path name has allowed access outside the intended area.

An empty path name is valid, and it refers to the user's default directory (usually the user's home directory).

All file paths input and output from the provider must adhere to this format; conversion to a native file system is the responsibility of your own file system provider.

Author:

Lee David Painter

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTHORIZED_KEYS_STORE
static int	OPEN_APPEND File open flag, forces all writes to append data at the end of the file.
static int	OPEN_CREATE File open flag, if specified a new file will be created if one does not already exist.
static int	OPEN_EXCLUSIVE File open flag, causes an open request to fail if the named file already exists.
static int	OPEN_READ File open flag, opens the file for reading.
static int	OPEN_TRUNCATE File open flag, forces an existing file with the same name to be truncated to zero length when creating a file by specifying OPEN_CREATE.
static int	OPEN_WRITE File open flag, opens the file for writing.
static String	SCP
static String	SFTP
static String	SSH

Method Summary

Methods

Modifier and Type	Method and Description
void	closeFile(byte[] handle) Close an open file or directory.
void	closeFilesystem() The filesystem instance is being closed and no further use of the instance is required.
void	createSymbolicLink(String link, String target) Create a symbolic link.
boolean	fileExists(String path) Determine whether a file exists and return the result
String	getDefaultPath() Get the default path for the current session.
SftpFileAttributes	getFileAttributes(byte[] handle) Get the attributes for a given file handle.
SftpFileAttributes	getFileAttributes(String path) Get the attributes for a given file.
MountManager<T>	getMountManager()
String	getRealPath(String path) Get the real path for a given path.
boolean	makeDirectory(String path, SftpFileAttributes attrs) Create a directory.
byte[]	openDirectory(String path) Open a directory for reading and allocate an open file handle.
byte[]	openFile(String path, com.maverick.util.UnsignedInteger32 flags, SftpFileAttributes attrs) Open a file for reading/writing and allocate an open file handle.
SftpFile[]	readDirectory(byte[] handle) Read the contents of a directory.
int	readFile(byte[] handle, com.maverick.util.UnsignedInteger64 offset, byte[] buffer, int start, int numBytesToRead) Read a block of data from an open file.
SftpFile	readSymbolicLink(String path) Read the target location of a symbolic link.
void	removeDirectory(String path) Remove an empty directory from the file system.
void	removeFile(String path) Remove a file.
void	renameFile(String oldpath, String newpath) Rename a file.
void	setFileAttributes(byte[] handle, SftpFileAttributes attrs) Set the open files attributes
void	setFileAttributes(String path, SftpFileAttributes attrs) Set the files attributes.
boolean	supportsMounting()
void	writeFile(byte[] handle, com.maverick.util.UnsignedInteger64 offset, byte[] data, int off, int len) Write a block of data to an open file.

Field Detail

OPEN_READ

static final int OPEN_READ

File open flag, opens the file for reading.

See Also:

Constant Field Values

OPEN_WRITE

static final int OPEN_WRITE

File open flag, opens the file for writing.

See Also:

Constant Field Values

OPEN_APPEND

static final int OPEN_APPEND

File open flag, forces all writes to append data at the end of the file.

See Also:

Constant Field Values

OPEN_CREATE

static final int OPEN_CREATE

File open flag, if specified a new file will be created if one does not already exist.

See Also:

Constant Field Values

OPEN_TRUNCATE

static final int OPEN_TRUNCATE

File open flag, forces an existing file with the same name to be truncated to zero length when creating a file by specifying OPEN_CREATE.

See Also:

Constant Field Values

OPEN_EXCLUSIVE

static final int OPEN_EXCLUSIVE

File open flag, causes an open request to fail if the named file already exists. OPEN_CREATE must also be specified if this flag is used.

See Also:

Constant Field Values

AUTHORIZED_KEYS_STORE

static final String AUTHORIZED_KEYS_STORE

See Also:

Constant Field Values

SFTP

static final String SFTP

See Also:

Constant Field Values

SCP

static final String SCP

See Also:

Constant Field Values

SSH

static final String SSH

See Also:

Constant Field Values

Method Detail

closeFilesystem

void closeFilesystem()

The filesystem instance is being closed and no further use of the instance is required.

fileExists

boolean fileExists(String path)
                   throws IOException,
                          PermissionDeniedException

Determine whether a file exists and return the result

Parameters:

path - String

Returns:

boolean true if the file exists, otherwise false.

Throws:

IOException

PermissionDeniedException

getRealPath

String getRealPath(String path)
                   throws IOException,
                          FileNotFoundException,
                          PermissionDeniedException

Get the real path for a given path. This requires that the path be processed and a full path be returned, for example '/usr/../var' would be returned as '/var'. This should also expand relative paths using the users home directory as a base.

Parameters:

path - String the path to canonicalize.

Returns:

String the absolute path to the file.

Throws:

IOException - if an unrecoverable error occurs.

FileNotFoundException - if the path cannot be found.

PermissionDeniedException

makeDirectory

boolean makeDirectory(String path,
                    SftpFileAttributes attrs)
                      throws PermissionDeniedException,
                             FileNotFoundException,
                             IOException

Create a directory. A false value should be returned if the file or directory with the specified path already exists.

Parameters:

path - String the absolute path to the new directory.

attrs -

Returns:

boolean true if the directory was created, false if the directory already exists.

Throws:

PermissionDeniedException - if the user cannot perform this operation.

FileNotFoundException - if the parent directory does not exist.

IOException

getFileAttributes

SftpFileAttributes getFileAttributes(String path)
                                     throws IOException,
                                            FileNotFoundException,
                                            PermissionDeniedException

Get the attributes for a given file. This requires that you build a file attributes object based upon all the information that you can determine.

Parameters:

path - String the absolute path to the file

Returns:

SftpFileAttributes

Throws:

IOException

FileNotFoundException - if the file cannot be found

PermissionDeniedException - if the user does not have access to this file

See Also:

com.maverick.sftp.SftpFileAttributes

getFileAttributes

SftpFileAttributes getFileAttributes(byte[] handle)
                                     throws IOException,
                                            InvalidHandleException,
                                            PermissionDeniedException

Get the attributes for a given file handle. This requires that you build a file attributes object based upon all the information that you can determine from the file whose open handle has been provided.

Parameters:

handle - byte[]

Returns:

SftpFileAttributes

Throws:

IOException

InvalidHandleException

PermissionDeniedException

openDirectory

byte[] openDirectory(String path)
                     throws PermissionDeniedException,
                            FileNotFoundException,
                            IOException

Open a directory for reading and allocate an open file handle. Open file handles can be whatever you require but the length of the handle string MUST NOT exceed 256 data bytes. Subsequent calls to readDirectory and closeFile will provide the handle returned from this method.

Parameters:

path - String

Returns:

byte[]

Throws:

PermissionDeniedException

FileNotFoundException

IOException

readDirectory

SftpFile[] readDirectory(byte[] handle)
                         throws InvalidHandleException,
                                EOFException,
                                IOException,
                                PermissionDeniedException

Read the contents of a directory. Each call to this method should return one or more file objects with full file attributes for each file. The client will call this method repeatedly until an EOFException is thrown indicating that there are no more files to read from the directory. If there are no files to list then the EOFException should be thrown upon first call.

IMPORTANT: Each SftpFile object should be initialized with the relative path of the file AND NOT the absolute path.

Parameters:

handle - byte[]

Returns:

SftpFile[] an array of SftpFile objects.

Throws:

InvalidHandleException - the handle supplied is invalid.

EOFException - thrown once all the files contained with the directory have been read.

IOException - an error occurred

PermissionDeniedException

openFile

byte[] openFile(String path,
              com.maverick.util.UnsignedInteger32 flags,
              SftpFileAttributes attrs)
                throws PermissionDeniedException,
                       FileNotFoundException,
                       IOException

Open a file for reading/writing and allocate an open file handle. Open file handles can be whatever you require but the length of the handle string MUST NOT exceed 256 data bytes. Subsequent calls to readDirectory and closeFile will provide the handle returned from this method. The method specifes one or more file open flags which determine which mode the file should be opened in.

Parameters:

path - String

flags - UnsignedInteger32

attrs - SftpFileAttributes

Returns:

byte[]

Throws:

PermissionDeniedException

FileNotFoundException

IOException

readFile

int readFile(byte[] handle,
           com.maverick.util.UnsignedInteger64 offset,
           byte[] buffer,
           int start,
           int numBytesToRead)
             throws InvalidHandleException,
                    EOFException,
                    IOException

Read a block of data from an open file. You should read from the file offset provided and write the data into the buffer array from the start position and return no more data than is requested by numBytesToRead; return the actual number of bytes read in the return value and if the file offset specified is passed EOF you should throw an EOFException.

Parameters:

handle - byte[]

offset - UnsignedInteger64

buffer - byte[]

start - int

numBytesToRead - int

Returns:

int

Throws:

InvalidHandleException

EOFException

IOException

writeFile

void writeFile(byte[] handle,
             com.maverick.util.UnsignedInteger64 offset,
             byte[] data,
             int off,
             int len)
               throws InvalidHandleException,
                      IOException

Write a block of data to an open file. You should write the data from the offset for as many bytes as are supplied.

Parameters:

handle - byte[]

offset - UnsignedInteger64

data - byte[]

off - int

len - int

Throws:

InvalidHandleException

IOException

closeFile

void closeFile(byte[] handle)
               throws InvalidHandleException,
                      IOException

Close an open file or directory.

Parameters:

handle - byte[]

Throws:

InvalidHandleException

IOException

removeFile

void removeFile(String path)
                throws PermissionDeniedException,
                       IOException,
                       FileNotFoundException

Remove a file.

Parameters:

path - String

Throws:

PermissionDeniedException

IOException

FileNotFoundException

renameFile

void renameFile(String oldpath,
              String newpath)
                throws PermissionDeniedException,
                       FileNotFoundException,
                       IOException

Rename a file. It is an error if there already exists a file with the name specified by newpath.

Parameters:

oldpath - String

newpath - String

Throws:

PermissionDeniedException

FileNotFoundException

IOException

removeDirectory

void removeDirectory(String path)
                     throws PermissionDeniedException,
                            FileNotFoundException,
                            IOException

Remove an empty directory from the file system. This method should fail if the directory has any file system objects as children.

Parameters:

path - String

Throws:

PermissionDeniedException

FileNotFoundException

IOException

setFileAttributes

void setFileAttributes(String path,
                     SftpFileAttributes attrs)
                       throws PermissionDeniedException,
                              IOException,
                              FileNotFoundException

Set the files attributes.

Parameters:

path - String

attrs - SftpFileAttributes

Throws:

PermissionDeniedException

IOException

FileNotFoundException

setFileAttributes

void setFileAttributes(byte[] handle,
                     SftpFileAttributes attrs)
                       throws PermissionDeniedException,
                              IOException,
                              InvalidHandleException

Set the open files attributes

Parameters:

handle - byte[]

attrs - SftpFileAttributes

Throws:

PermissionDeniedException

IOException

InvalidHandleException

readSymbolicLink

SftpFile readSymbolicLink(String path)
                          throws UnsupportedFileOperationException,
                                 FileNotFoundException,
                                 IOException,
                                 PermissionDeniedException

Read the target location of a symbolic link. If the file system does not support links then an UnsupportedOperationException should be thrown. Otherwise the full path to the target of the link should be returned.

Parameters:

path - String

Returns:

SftpFile

Throws:

UnsupportedFileOperationException

FileNotFoundException

IOException

PermissionDeniedException

createSymbolicLink

void createSymbolicLink(String link,
                      String target)
                        throws UnsupportedFileOperationException,
                               FileNotFoundException,
                               IOException,
                               PermissionDeniedException

Create a symbolic link. If the file system does not support the creation of links then an UnsupportedOperationException should be thrown.

Parameters:

link - String

target - String

Throws:

UnsupportedFileOperationException

FileNotFoundException

IOException

PermissionDeniedException

getDefaultPath

String getDefaultPath()
                      throws FileNotFoundException,
                             IOException,
                             PermissionDeniedException

Get the default path for the current session. The default path is normally the users home directory.

Returns:

String the absolute path to the default path.

Throws:

FileNotFoundException - if the users default path does not exist.

PermissionDeniedException

IOException

supportsMounting

boolean supportsMounting()

getMountManager

MountManager<T> getMountManager()
                                                        throws IOException,
                                                               PermissionDeniedException

Throws:

IOException

PermissionDeniedException