com.sshtools.sftp

Class SftpSubsystemChannel

java.lang.Object

com.sshtools.ssh.SubsystemChannel

com.sshtools.sftp.SftpSubsystemChannel

public class SftpSubsystemChannel
extends SubsystemChannel

This class implements the SFTP protocol which is executed as an SSH subsystem. The basic initialization procedure is as follows:

 // Create an SshClient
 SshConnector con = SshConnector.getInstance();
 
 // Connect and authenticate an SshClient
 SshClient ssh = con.connect(....);
 ....
 
 // Create and initialize an SftpSubsystemChannel
 SshSession session = ssh.openSessionChannel();
 if(session instanceof Ssh2Session)
    ((Ssh2Session)session).startSubsystem("sftp");
 
 SftpSubsystemChannel sftp = new SftpSubsystemChannel(session);
 sftp.initialize();
 

Author:

Lee David Painter

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_VERSION
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_TEXT File open flag, causes the file to be opened in text mode.
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.

Fields inherited from class com.sshtools.ssh.SubsystemChannel

channel

Constructor Summary

Constructors

Constructor and Description
SftpSubsystemChannel(SshSession session)
SftpSubsystemChannel(SshSession session, int Max_Version)

Method Summary

Methods

Modifier and Type	Method and Description
void	changePermissions(SftpFile file, int permissions) Change the permissions of a file.
void	changePermissions(String filename, int permissions) Change the permissions of a file.
void	changePermissions(String filename, String permissions) Change the permissions of a file.
void	close() Close the subsystem
void	closeFile(SftpFile file) Close a file or directory.
void	createSymbolicLink(String targetpath, String linkpath) Create a symbolic link.
String	getAbsolutePath(SftpFile file) Get the absolute path of a file.
String	getAbsolutePath(String path) Get the absolute path of a file.
SftpFileAttributes	getAttributes(SftpFile file) Get the attributes of a file.
SftpFileAttributes	getAttributes(String path) Get the attributes of a file.
protected SftpFileAttributes	getAttributes(String path, int messageId)
byte[]	getCanonicalNewline() Returns the canonical newline convention in use when reading/writing text files.
String	getCharsetEncoding() Get the current encoding being used for filename Strings.
String	getDefaultDirectory() Gets the users default directory.
byte[]	getExtension(String name) Get the data value of a supported SFTP extension.
SftpFile	getFile(String path) Utility method to obtain an SftpFile instance for a given path.
SftpFileAttributes	getLinkAttributes(String path) Get the attributes of a file.
void	getOKRequestStatus(UnsignedInteger32 requestId) Verify that an OK status has been returned for a request id.
int	getServerVersion() Version 4 of the SFTP protocol allows the server to return its maximum supported version instead of the actual version to be used.
String	getSymbolicLinkTarget(String linkpath) Get the target path of a symbolic link.
int	getVersion() When called after the initialize method this will return the version in operation for this sftp session.
void	initialize() Initializes the sftp subsystem and negotiates a version with the server.
int	listChildren(SftpFile file, Vector<SftpFile> children) List the children of a directory.
void	makeDirectory(String path) Make a directory.
void	makeDirectory(String path, SftpFileAttributes attrs) Make a directory.
SftpFile	openDirectory(String path) Open a directory.
SftpFile	openFile(String absolutePath, int flags) Open a file.
SftpFile	openFile(String absolutePath, int flags, SftpFileAttributes attrs) Open a file.
void	performOptimizedRead(byte[] handle, long length, int blocksize, OutputStream out, int outstandingRequests, FileTransferProgress progress) Performs an optimized read of a file through use of asynchronous messages.
void	performOptimizedRead(byte[] handle, long length, int blocksize, OutputStream out, int outstandingRequests, FileTransferProgress progress, long position) Performs an optimized read of a file through use of asynchronous messages.
void	performOptimizedWrite(byte[] handle, int blocksize, int outstandingRequests, InputStream in, int buffersize, FileTransferProgress progress) Performs an optimized write of a file through asynchronous messaging and through buffering the local file into memory.
void	performOptimizedWrite(byte[] handle, int blocksize, int outstandingRequests, InputStream in, int buffersize, FileTransferProgress progress, long position) Performs an optimized write of a file through asynchronous messaging and through buffering the local file into memory.
void	performSynchronousRead(byte[] handle, int blocksize, OutputStream out, FileTransferProgress progress, long position) Perform a synchronous read of a file from the remote file system.
UnsignedInteger32	postReadRequest(byte[] handle, long offset, int len) Post a read request to the server and return the request id; this is used to optimize file downloads.
UnsignedInteger32	postWriteRequest(byte[] handle, long position, byte[] data, int off, int len) Send a write request for an open file but do not wait for the response from the server.
int	readFile(byte[] handle, UnsignedInteger64 offset, byte[] output, int off, int len) Read a block of data from an open file.
void	recurseMakeDirectory(String path) Recurse through a hierarchy of directories creating them as necessary.
void	removeDirectory(String path) Remove an empty directory.
void	removeFile(String filename) Remove a file.
void	renameFile(String oldpath, String newpath) Rename an existing file.
SftpMessage	sendExtensionMessage(String request, byte[] requestData) Send an extension message and return the response.
void	setAttributes(SftpFile file, SftpFileAttributes attrs) Sets the attributes of a file.
void	setAttributes(String path, SftpFileAttributes attrs) Sets the attributes of a file.
void	setCharsetEncoding(String charset) Allows the default character encoding to be overriden for filename strings.
static void	setMaxSftpVersion(int MAX_VERSION) Sets the maximum SFTP protocol version to use, this should be <=4.
void	setThisMaxSftpVersion(int MAX_VERSION) Sets the maximum SFTP protocol version to use for this instance, this should be <=4.
boolean	supportsExtension(String name) Does the server support an SFTP extension? This checks the extensions returned by the server during the SFTP version negotiation.
void	writeFile(byte[] handle, UnsignedInteger64 offset, byte[] data, int off, int len) Write a block of data to an open file.

Methods inherited from class com.sshtools.ssh.SubsystemChannel

createPacket, isClosed, nextMessage, sendMessage, sendMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OPEN_READ

public static final int OPEN_READ

File open flag, opens the file for reading.

See Also:

Constant Field Values

OPEN_WRITE

public static final int OPEN_WRITE

File open flag, opens the file for writing.

See Also:

Constant Field Values

OPEN_APPEND

public 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

public 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

public 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

public 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

OPEN_TEXT

public static final int OPEN_TEXT

File open flag, causes the file to be opened in text mode. This instructs the server to convert the text file to the canonical newline convention in use. Any files retrieved using this mode should then be converted from the canonical newline convention to that of the clients.

See Also:

Constant Field Values

MAX_VERSION

public static int MAX_VERSION

Constructor Detail

SftpSubsystemChannel

public SftpSubsystemChannel(SshSession session)
                     throws SshException

Throws:

SshException

SftpSubsystemChannel

public SftpSubsystemChannel(SshSession session,
                    int Max_Version)
                     throws SshException

Throws:

SshException

Method Detail

setMaxSftpVersion

public static void setMaxSftpVersion(int MAX_VERSION)

Sets the maximum SFTP protocol version to use, this should be <=4.

Parameters:

MAX_VERSION -

setThisMaxSftpVersion

public void setThisMaxSftpVersion(int MAX_VERSION)

Sets the maximum SFTP protocol version to use for this instance, this should be <=4.

Parameters:

MAX_VERSION -

getVersion

public int getVersion()

When called after the initialize method this will return the version in operation for this sftp session.

Returns:

int

getCanonicalNewline

public byte[] getCanonicalNewline()
                           throws SftpStatusException

Returns the canonical newline convention in use when reading/writing text files.

Returns:

String

Throws:

SftpStatusException

initialize

public void initialize()
                throws SshException,
                       UnsupportedEncodingException

Initializes the sftp subsystem and negotiates a version with the server. This method must be the first method called after the channel has been opened. This implementation current supports SFTP protocol version 4 and below.

Throws:

SshException

UnsupportedEncodingException

close

public void close()
           throws IOException

Description copied from class: SubsystemChannel

Close the subsystem

Overrides:

close in class SubsystemChannel

Throws:

IOException

setCharsetEncoding

public void setCharsetEncoding(String charset)
                        throws SshException,
                               UnsupportedEncodingException

Allows the default character encoding to be overriden for filename strings. This method should only be called once the channel has been initialized, if the version of the protocol is less than or equal to 3 the encoding is defaulted to latin1 as no encoding is specified by the protocol. If the version is greater than 3 the default encoding will be UTF-8.

Parameters:

charset -

Throws:

UnsupportedEncodingException

SshException

getServerVersion

public int getServerVersion()

Version 4 of the SFTP protocol allows the server to return its maximum supported version instead of the actual version to be used. This method returns the value provided by the server, if the servers version is less than or equal to 3 then this method will return the protocol number in use, otherwise it returns the maximum version supported by the server.

Returns:

int

getCharsetEncoding

public String getCharsetEncoding()

Get the current encoding being used for filename Strings.

Returns:

String

supportsExtension

public boolean supportsExtension(String name)

Does the server support an SFTP extension? This checks the extensions returned by the server during the SFTP version negotiation.

Parameters:

name - String

Returns:

boolean

getExtension

public byte[] getExtension(String name)

Get the data value of a supported SFTP extension. Call supportsExtension(String) before calling this method to determine if the extension is available.

Parameters:

name - String

Returns:

String

sendExtensionMessage

public SftpMessage sendExtensionMessage(String request,
                               byte[] requestData)
                                 throws SshException,
                                        SftpStatusException

Send an extension message and return the response. This is for advanced use only.

Parameters:

request - String

requestData - byte[]

Returns:

SftpMessage

Throws:

SshException

SftpStatusException

changePermissions

public void changePermissions(SftpFile file,
                     int permissions)
                       throws SftpStatusException,
                              SshException

Change the permissions of a file.

Parameters:

file - the file

permissions - an integer value containing a file permissions mask

Throws:

SshException - ,SftpStatusException

SftpStatusException

changePermissions

public void changePermissions(String filename,
                     int permissions)
                       throws SftpStatusException,
                              SshException

Change the permissions of a file.

Parameters:

filename - the path to the file.

permissions - an integer value containing a file permissions mask.

Throws:

SshException - ,SftpStatusException

SftpStatusException

changePermissions

public void changePermissions(String filename,
                     String permissions)
                       throws SftpStatusException,
                              SshException

Change the permissions of a file.

Parameters:

filename - the path to the file.

permissions - a string containing the permissions, for example "rw-r--r--"

Throws:

SftpStatusException - , SshException

SshException

setAttributes

public void setAttributes(String path,
                 SftpFileAttributes attrs)
                   throws SftpStatusException,
                          SshException

Sets the attributes of a file.

Parameters:

path - the path to the file.

attrs - the file attributes.

Throws:

SftpStatusException - , SshException

SshException

setAttributes

public void setAttributes(SftpFile file,
                 SftpFileAttributes attrs)
                   throws SftpStatusException,
                          SshException

Sets the attributes of a file.

Parameters:

file - the file object.

attrs - the new attributes.

Throws:

SshException

SftpStatusException

postWriteRequest

public UnsignedInteger32 postWriteRequest(byte[] handle,
                                 long position,
                                 byte[] data,
                                 int off,
                                 int len)
                                   throws SftpStatusException,
                                          SshException

Send a write request for an open file but do not wait for the response from the server.

Parameters:

handle -

position -

data -

off -

len -

Returns:

UnsignedInteger32

Throws:

SshException

SftpStatusException

writeFile

public void writeFile(byte[] handle,
             UnsignedInteger64 offset,
             byte[] data,
             int off,
             int len)
               throws SftpStatusException,
                      SshException

Write a block of data to an open file.

Parameters:

handle - the open file handle.

offset - the offset in the file to start writing

data - a buffer containing the data to write

off - the offset to start in the buffer

len - the length of data to write (setting to false will increase file transfer but may miss errors)

Throws:

SshException

SftpStatusException

performOptimizedWrite

public void performOptimizedWrite(byte[] handle,
                         int blocksize,
                         int outstandingRequests,
                         InputStream in,
                         int buffersize,
                         FileTransferProgress progress)
                           throws SftpStatusException,
                                  SshException,
                                  TransferCancelledException

Performs an optimized write of a file through asynchronous messaging and through buffering the local file into memory.

Parameters:

handle - the open file handle to write to

blocksize - the block size to send data, should be between 4096 and 65535

outstandingRequests - the maximum number of requests that can be outstanding at any one time

in - the InputStream to read from

buffersize - the size of the temporary buffer to read from the InputStream. Data is buffered into a temporary buffer so that the number of local filesystem reads is reducted to a minimum. This increases performance and so the buffer size should be as high as possible. The default operation, if buffersize <= 0 is to allocate a buffer the same size as the blocksize, meaning no buffer optimization is performed.

progress - provides progress information, may be null.

Throws:

SshException

SftpStatusException

TransferCancelledException

performOptimizedWrite

public void performOptimizedWrite(byte[] handle,
                         int blocksize,
                         int outstandingRequests,
                         InputStream in,
                         int buffersize,
                         FileTransferProgress progress,
                         long position)
                           throws SftpStatusException,
                                  SshException,
                                  TransferCancelledException

Performs an optimized write of a file through asynchronous messaging and through buffering the local file into memory.

Parameters:

handle - the open file handle to write to

blocksize - the block size to send data, should be between 4096 and 65535

outstandingRequests - the maximum number of requests that can be outstanding at any one time

in - the InputStream to read from

buffersize - the size of the temporary buffer to read from the InputStream. Data is buffered into a temporary buffer so that the number of local filesystem reads is reducted to a minimum. This increases performance and so the buffer size should be as high as possible. The default operation, if buffersize <= 0 is to allocate a buffer the same size as the blocksize, meaning no buffer optimization is performed.

progress - provides progress information, may be null.

position - the position in the file to start writing to.

Throws:

SshException

SftpStatusException

TransferCancelledException

performOptimizedRead

public void performOptimizedRead(byte[] handle,
                        long length,
                        int blocksize,
                        OutputStream out,
                        int outstandingRequests,
                        FileTransferProgress progress)
                          throws SftpStatusException,
                                 SshException,
                                 TransferCancelledException

Performs an optimized read of a file through use of asynchronous messages. The total number of outstanding read requests is configurable. This should be safe on file objects as the SSH protocol states that file read operations should return the exact number of bytes requested in each request. However the server is not required to return the exact number of bytes on device files and so this method should not be used for device files.

Parameters:

handle - the open files handle

length - the length of the file

blocksize - the blocksize to read

out - an OutputStream to output the file into

outstandingRequests - the maximum number of read requests to

progress -

Throws:

SshException

SftpStatusException

TransferCancelledException

performOptimizedRead

public void performOptimizedRead(byte[] handle,
                        long length,
                        int blocksize,
                        OutputStream out,
                        int outstandingRequests,
                        FileTransferProgress progress,
                        long position)
                          throws SftpStatusException,
                                 SshException,
                                 TransferCancelledException

Performs an optimized read of a file through use of asynchronous messages. The total number of outstanding read requests is configurable. This should be safe on file objects as the SSH protocol states that file read operations should return the exact number of bytes requested in each request. However the server is not required to return the exact number of bytes on device files and so this method should not be used for device files.

Parameters:

handle - the open files handle

length - the amount of the file file to be read, equal to the file length when reading the whole file

blocksize - the blocksize to read

out - an OutputStream to output the file into

outstandingRequests - the maximum number of read requests to

progress -

position - the postition from which to start reading the file

Throws:

SshException

SftpStatusException

TransferCancelledException

performSynchronousRead

public void performSynchronousRead(byte[] handle,
                          int blocksize,
                          OutputStream out,
                          FileTransferProgress progress,
                          long position)
                            throws SftpStatusException,
                                   SshException,
                                   TransferCancelledException

Perform a synchronous read of a file from the remote file system. This implementation waits for acknowledgement of every data packet before requesting additional data.

Parameters:

handle -

blocksize -

out -

progress -

position -

Throws:

SftpStatusException

SshException

TransferCancelledException

postReadRequest

public UnsignedInteger32 postReadRequest(byte[] handle,
                                long offset,
                                int len)
                                  throws SftpStatusException,
                                         SshException

Post a read request to the server and return the request id; this is used to optimize file downloads. In normal operation the files are transfered by using a synchronous set of requests, however this slows the download as the client has to wait for the servers response before sending another request.

Parameters:

handle -

offset -

len -

Returns:

UnsignedInteger32

Throws:

SshException

SftpStatusException

readFile

public int readFile(byte[] handle,
           UnsignedInteger64 offset,
           byte[] output,
           int off,
           int len)
             throws SftpStatusException,
                    SshException

Read a block of data from an open file.

Parameters:

handle - the open file handle

offset - the offset to start reading in the file

output - a buffer to write the returned data to

off - the starting offset in the output buffer

len - the length of data to read

Returns:

int

Throws:

SshException

SftpStatusException

getFile

public SftpFile getFile(String path)
                 throws SftpStatusException,
                        SshException

Utility method to obtain an SftpFile instance for a given path.

Parameters:

path -

Returns:

SftpFile

Throws:

SftpStatusException

SshException

getAbsolutePath

public String getAbsolutePath(SftpFile file)
                       throws SftpStatusException,
                              SshException

Get the absolute path of a file.

Parameters:

file -

Returns:

String

Throws:

SshException

SftpStatusException

createSymbolicLink

public void createSymbolicLink(String targetpath,
                      String linkpath)
                        throws SftpStatusException,
                               SshException

Create a symbolic link.

Parameters:

targetpath - the symbolic link to create

linkpath - the path to which the symbolic link points

Throws:

SshException - if the remote SFTP version is < 3 an exception is thrown as this feature is not supported by previous versions of the protocol.

SftpStatusException

getSymbolicLinkTarget

public String getSymbolicLinkTarget(String linkpath)
                             throws SftpStatusException,
                                    SshException

Get the target path of a symbolic link.

Parameters:

linkpath -

Returns:

String

Throws:

SshException - if the remote SFTP version is < 3 an exception is thrown as this feature is not supported by previous versions of the protocol.

SftpStatusException

getDefaultDirectory

public String getDefaultDirectory()
                           throws SftpStatusException,
                                  SshException

Gets the users default directory.

Returns:

String

Throws:

SshException

SftpStatusException

getAbsolutePath

public String getAbsolutePath(String path)
                       throws SftpStatusException,
                              SshException

Get the absolute path of a file.

Parameters:

path -

Returns:

String

Throws:

SshException

SftpStatusException

listChildren

public int listChildren(SftpFile file,
               Vector<SftpFile> children)
                 throws SftpStatusException,
                        SshException

List the children of a directory.

To use this method first open a directory with the openDirectory method and then create a Vector to store the results. To retrieve the results keep calling this method until it returns -1 which indicates no more results will be returned.

 SftpFile dir = sftp.openDirectory("code/foobar");
 Vector results = new Vector();
 while (sftp.listChildren(dir, results) > -1)
        ;
 sftp.closeFile(dir);
 

Parameters:

file -

children -

Returns:

int

Throws:

SftpStatusException - , SshException

SshException

recurseMakeDirectory

public void recurseMakeDirectory(String path)
                          throws SftpStatusException,
                                 SshException

Recurse through a hierarchy of directories creating them as necessary.

Parameters:

path -

Throws:

SftpStatusException - , SshException

SshException

openFile

public SftpFile openFile(String absolutePath,
                int flags)
                  throws SftpStatusException,
                         SshException

Open a file.

Parameters:

absolutePath -

flags -

Returns:

SftpFile

Throws:

SftpStatusException - , SshException

SshException

openFile

public SftpFile openFile(String absolutePath,
                int flags,
                SftpFileAttributes attrs)
                  throws SftpStatusException,
                         SshException

Open a file.

Parameters:

absolutePath -

flags -

attrs -

Returns:

SftpFile

Throws:

SftpStatusException - , SshException

SshException

openDirectory

public SftpFile openDirectory(String path)
                       throws SftpStatusException,
                              SshException

Open a directory.

Parameters:

path -

Returns:

sftpfile

Throws:

SftpStatusException - , SshException

SshException

closeFile

public void closeFile(SftpFile file)
               throws SftpStatusException,
                      SshException

Close a file or directory.

Parameters:

file -

Throws:

SftpStatusException - , SshException

SshException

removeDirectory

public void removeDirectory(String path)
                     throws SftpStatusException,
                            SshException

Remove an empty directory.

Parameters:

path -

Throws:

SftpStatusException - , SshException

SshException

removeFile

public void removeFile(String filename)
                throws SftpStatusException,
                       SshException

Remove a file.

Parameters:

filename -

Throws:

SftpStatusException - , SshException

SshException

renameFile

public void renameFile(String oldpath,
              String newpath)
                throws SftpStatusException,
                       SshException

Rename an existing file.

Parameters:

oldpath -

newpath -

Throws:

SftpStatusException - , SshException

SshException

getAttributes

public SftpFileAttributes getAttributes(String path)
                                 throws SftpStatusException,
                                        SshException

Get the attributes of a file. This method follows symbolic links

Parameters:

path -

Returns:

SftpFileAttributes

Throws:

SshException

SftpStatusException

getLinkAttributes

public SftpFileAttributes getLinkAttributes(String path)
                                     throws SftpStatusException,
                                            SshException

Get the attributes of a file. This method does not follow symbolic links so will return the attributes of an actual link, not its target.

Parameters:

path -

Returns:

Throws:

SftpStatusException

SshException

getAttributes

protected SftpFileAttributes getAttributes(String path,
                               int messageId)
                                    throws SftpStatusException,
                                           SshException

Throws:

SftpStatusException

SshException

getAttributes

public SftpFileAttributes getAttributes(SftpFile file)
                                 throws SftpStatusException,
                                        SshException

Get the attributes of a file.

Parameters:

file -

Returns:

SftpFileAttributes

Throws:

SftpStatusException - , SshException

SshException

makeDirectory

public void makeDirectory(String path)
                   throws SftpStatusException,
                          SshException

Make a directory. If the directory exists this method will throw an exception.

Parameters:

path -

Throws:

SftpStatusException - , SshException

SshException

makeDirectory

public void makeDirectory(String path,
                 SftpFileAttributes attrs)
                   throws SftpStatusException,
                          SshException

Make a directory. If the directory exists this method will throw an exception.

Parameters:

path -

attrs -

Throws:

SftpStatusException - , SshException

SshException

getOKRequestStatus

public void getOKRequestStatus(UnsignedInteger32 requestId)
                        throws SftpStatusException,
                               SshException

Verify that an OK status has been returned for a request id.

Parameters:

requestId -

Throws:

SftpStatusException - , SshException

SshException