com.mindbright.ssh2

Class SSH2SFTPClient

java.lang.Object

com.mindbright.ssh2.SSH2SFTP

com.mindbright.ssh2.SSH2SFTPClient

All Implemented Interfaces:

SSH2SFTP.Callback

public final class SSH2SFTPClient
extends SSH2SFTP
implements SSH2SFTP.Callback

Implements the client side of the sftp protocol. File reads and writes can be either synchronous (blocking) or asynchronous (non-blocking). Asynchronous operation is much faster but is more complicated to use when the interface is used for reading parts of files. In asynchronous mode read and write return immediately before the operation has finished. The asyncWait method waits until all operations have been completed and must be called before read buffers are accessed.

Nested Class Summary

Nested classes/interfaces inherited from class com.mindbright.ssh2.SSH2SFTP

SSH2SFTP.AsyncListener, SSH2SFTP.Callback, SSH2SFTP.FileAttributes, SSH2SFTP.FileHandle, SSH2SFTP.FileSystemAttributes, SSH2SFTP.SFTPAsyncAbortException, SSH2SFTP.SFTPDisconnectException, SSH2SFTP.SFTPEOFException, SSH2SFTP.SFTPException, SSH2SFTP.SFTPFailureException, SSH2SFTP.SFTPNoSuchFileException, SSH2SFTP.SFTPPacket, SSH2SFTP.SFTPPermissionDeniedException, SSH2SFTP.SFTPUnsupportedException

Field Summary

Fields inherited from class com.mindbright.ssh2.SSH2SFTP

SSH_ATTR_EXTENDED, SSH_ATTR_MODTIME, SSH_ATTR_PERM, SSH_ATTR_SIZE, SSH_ATTR_UIDGID, SSH_FILEXFER_VERSION, SSH_FX_BAD_MESSAGE, SSH_FX_CONNECTION_LOST, SSH_FX_EOF, SSH_FX_FAILURE, SSH_FX_INVALID_HANDLE, SSH_FX_NO_CONNECTION, SSH_FX_NO_SUCH_FILE, SSH_FX_OK, SSH_FX_OP_UNSUPPORTED, SSH_FX_PERMISSION_DENIED, SSH_FXF_APPEND, SSH_FXF_CREAT, SSH_FXF_EXCL, SSH_FXF_READ, SSH_FXF_TRUNC, SSH_FXF_WRITE, SSH_FXP_ATTRS, SSH_FXP_CLOSE, SSH_FXP_DATA, SSH_FXP_EXTENDED, SSH_FXP_EXTENDED_REPLY, SSH_FXP_FSETSTAT, SSH_FXP_FSTAT, SSH_FXP_HANDLE, SSH_FXP_INIT, SSH_FXP_LSTAT, SSH_FXP_MKDIR, SSH_FXP_NAME, SSH_FXP_OLD_STAT, SSH_FXP_OPEN, SSH_FXP_OPENDIR, SSH_FXP_READ, SSH_FXP_READDIR, SSH_FXP_READLINK, SSH_FXP_REALPATH, SSH_FXP_REMOVE, SSH_FXP_RENAME, SSH_FXP_RMDIR, SSH_FXP_SETSTAT, SSH_FXP_STAT, SSH_FXP_STATUS, SSH_FXP_SYMLINK, SSH_FXP_VERSION, SSH_FXP_WRITE

Constructor Summary

Constructors

Constructor and Description
SSH2SFTPClient(SSH2Connection connection, boolean isBlocking) Create a new SFTP client which connects to the server.
SSH2SFTPClient(SSH2Connection connection, boolean isBlocking, int maxSize) Create a new SFTP client which connects to the server.

Method Summary

Methods

Modifier and Type	Method and Description
void	asyncWait(SSH2SFTP.FileHandle handle) Wait for all outstanding asynchronous operations on the given file to complete.
void	close(SSH2SFTP.FileHandle handle) Close a file.
void	fsetstat(SSH2SFTP.FileHandle handle, SSH2SFTP.FileAttributes attrs) Set attributes on an open file.
SSH2SFTP.FileAttributes	fstat(SSH2SFTP.FileHandle handle) Get attributes of an open file on the server.
SSH2SFTP.FileSystemAttributes	fstatvfs(SSH2SFTP.FileHandle handle) Get attributes of a filesystem on the server.
SSH2SessionChannel	getSessionChannel()
void	hardlink(java.lang.String oldpath, java.lang.String newpath) Create a hard link on the server.
SSH2SFTP.FileAttributes	lstat(java.lang.String name) Get attributes of a file on the server.
void	mkdir(java.lang.String name, SSH2SFTP.FileAttributes attrs) Create a new directory on the server.
SSH2SFTP.FileHandle	open(java.lang.String name, int flags, SSH2SFTP.FileAttributes attrs) Open a file on the server.
SSH2SFTP.FileHandle	opendir(java.lang.String path) Opens a directory on the server.
void	packetReceived(SSH2SFTP.SFTPPacket pkt)
void	posixRename(java.lang.String oldName, java.lang.String newName) Rename a file on the server with Posix semantics.
int	read(SSH2SFTP.FileHandle handle, long fileOffset, byte[] buf, int off, int len) Read data from an open file on the server and stores it in a local buffer.
int	read(SSH2SFTP.FileHandle handle, long fileOffset, java.io.RandomAccessFile fileTarget, int len) Read data from an open file on the server and stores it in a local file.
SSH2SFTP.FileAttributes[]	readdir(SSH2SFTP.FileHandle handle) Gets a list of files, and other objects, in an open directory.
void	readFailed(SSH2SFTP.SFTPException e)
int	readFully(SSH2SFTP.FileHandle handle, java.io.OutputStream out) Read the entire file on the server and store in a local stream.
java.lang.String	readlink(java.lang.String path) Read target of a symbolic link
SSH2SFTP.FileAttributes	realpath(java.lang.String nameIn) Canonalize a given path.
void	remove(java.lang.String name) Remove a file from the server.
void	rename(java.lang.String oldName, java.lang.String newName) Rename a file on the server.
void	restart() Reopens the connection to the server.
void	rmdir(java.lang.String name) Removes a directory from the server
void	setstat(java.lang.String name, SSH2SFTP.FileAttributes attrs) Set attributes on a file.
SSH2SFTP.FileAttributes	stat(java.lang.String name) Get attributes of a file on the server.
SSH2SFTP.FileSystemAttributes	statvfs(java.lang.String name) Get attributes of a filesystem on the server.
void	symlink(java.lang.String linkpath, java.lang.String targetpath) Create a symbolic link on the server.
void	terminate() Terminate the connection and abort any asynchronous calls which are in progress.
void	write(SSH2SFTP.FileHandle handle, long fileOffset, byte[] buf, int off, int len) Write data to a remote file.
long	writeFully(SSH2SFTP.FileHandle handle, byte[] in, boolean append) Write data buffer to a file on the server.
long	writeFully(SSH2SFTP.FileHandle handle, java.io.InputStream in) Write an entire stream to a file on the server.
long	writeFully(SSH2SFTP.FileHandle handle, java.io.InputStream in, boolean append) Write an entire stream to a file on the server.
protected void	writeInternal(SSH2SFTP.FileHandle handle, SSH2SFTP.SFTPPacket pkt, int len) Internal write function.

Methods inherited from class java.lang.Object

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

Constructor Detail

SSH2SFTPClient

public SSH2SFTPClient(SSH2Connection connection,
              boolean isBlocking)
               throws SSH2SFTP.SFTPException

Create a new SFTP client which connects to the server.

Parameters:

connection - Connection to run over.

isBlocking - True if read and write operations should be synchronous.

Throws:

SSH2SFTP.SFTPException

SSH2SFTPClient

public SSH2SFTPClient(SSH2Connection connection,
              boolean isBlocking,
              int maxSize)
               throws SSH2SFTP.SFTPException

Create a new SFTP client which connects to the server.

Parameters:

connection - Connection to run over.

isBlocking - True if read and write operations should be synchronous.

maxSize - Max packet size, must be 1..32768.

Throws:

SSH2SFTP.SFTPException

Method Detail

terminate

public void terminate()

Terminate the connection and abort any asynchronous calls which are in progress.

getSessionChannel

public SSH2SessionChannel getSessionChannel()

restart

public void restart()
             throws SSH2SFTP.SFTPException

Reopens the connection to the server. Any outstanding asynchronous operations are aborted.

Throws:

SSH2SFTP.SFTPException

open

public SSH2SFTP.FileHandle open(java.lang.String name,
                       int flags,
                       SSH2SFTP.FileAttributes attrs)
                         throws SSH2SFTP.SFTPException

Open a file on the server.

Parameters:

name - Name of file

flags - Mode to open file with. Valid values are SSH2SFTP.SSH_FXF_*.

attrs - File attributes for new files.

Returns:

A handle identifying the file.

Throws:

SSH2SFTP.SFTPException

close

public void close(SSH2SFTP.FileHandle handle)
           throws SSH2SFTP.SFTPException

Close a file. This will wait for any outstanding asynchronous operations.

Parameters:

handle - Handle identifying file.

Throws:

SSH2SFTP.SFTPException

asyncWait

public void asyncWait(SSH2SFTP.FileHandle handle)
               throws SSH2SFTP.SFTPException

Wait for all outstanding asynchronous operations on the given file to complete.

Parameters:

handle - Handle identifying file.

Throws:

SSH2SFTP.SFTPException

read

public int read(SSH2SFTP.FileHandle handle,
       long fileOffset,
       java.io.RandomAccessFile fileTarget,
       int len)
         throws SSH2SFTP.SFTPException,
                java.io.IOException

Read data from an open file on the server and stores it in a local file. The data is stored at the same position in the local file as it is read from in the remote file.

Note that if the client is operating in asynchronous mode then the method will return before data has been written to the stream. In this case the asyncWait method must be called, or the sftp file closed, before the stream can be closed.

Parameters:

handle - Handle identifying file.

fileOffset - Where in the file to start to read.

fileTarget - Local file to write the data into.

len - Number of bytes to read. Must be less than maxDataSize, which by default is 32768 bytes.

Returns:

The number of read bytes.

Throws:

SSH2SFTP.SFTPException

java.io.IOException

read

public int read(SSH2SFTP.FileHandle handle,
       long fileOffset,
       byte[] buf,
       int off,
       int len)
         throws SSH2SFTP.SFTPException

Read data from an open file on the server and stores it in a local buffer. Note that if the client is operating in asynchronous mode then the method will return before data has been placed in the buffer. In this case the asyncWait method must be called, or the file closed, before the data can be safely accessed.

Parameters:

handle - Handle identifying file.

fileOffset - Where in the file to start to read.

buf - Local buffer to store data in. Must hold len bytes at the given offset.

off - Offset in buffer to store data at.

len - Number of bytes to read. Must be less than maxDataSize, which by default is 32768 bytes.

Returns:

The number of read bytes.

Throws:

SSH2SFTP.SFTPException

readFully

public int readFully(SSH2SFTP.FileHandle handle,
            java.io.OutputStream out)
              throws SSH2SFTP.SFTPException,
                     java.io.IOException

Read the entire file on the server and store in a local stream. This method will be much faster if asynchronous mode is used. It will always wait until the operation has completed before returning, even if running in asynchronous mode.

Parameters:

handle - Handle identifying file. The handle will be closed when the transfer has completed.

out - Stream to store data in.

Returns:

Number of bytes read.

Throws:

SSH2SFTP.SFTPException

java.io.IOException

writeInternal

protected void writeInternal(SSH2SFTP.FileHandle handle,
                 SSH2SFTP.SFTPPacket pkt,
                 int len)
                      throws SSH2SFTP.SFTPException

Internal write function.

Throws:

SSH2SFTP.SFTPException

write

public void write(SSH2SFTP.FileHandle handle,
         long fileOffset,
         byte[] buf,
         int off,
         int len)
           throws SSH2SFTP.SFTPException

Write data to a remote file.

Parameters:

handle - Handle identifying file.

fileOffset - Offset to store data at.

buf - Buffer containing data to write.

off - Offset in buf to read data at.

len - Number of bytes to write. Must be less than maxDataSize, which by default is 32768 bytes.

Throws:

SSH2SFTP.SFTPException

writeFully

public long writeFully(SSH2SFTP.FileHandle handle,
              java.io.InputStream in)
                throws SSH2SFTP.SFTPException,
                       java.io.IOException

Write an entire stream to a file on the server. This method will be much faster if asynchronous mode is used. It will always wait until the operation has completed before returning, even if running in asynchronous mode.

Parameters:

handle - Handle identifying file. The handle will be closed when the transfer has completed.

in - Stream to read data to write from.

Throws:

SSH2SFTP.SFTPException

java.io.IOException

writeFully

public long writeFully(SSH2SFTP.FileHandle handle,
              java.io.InputStream in,
              boolean append)
                throws SSH2SFTP.SFTPException,
                       java.io.IOException

Write an entire stream to a file on the server. This method will be much faster if asynchronous mode is used. It will always wait until the operation has completed before returning, even if running in asynchronous mode.

Parameters:

handle - Handle identifying file. The handle will be closed when the transfer has completed.

in - Stream to read data to write from.

append - if true then the data is written at the end of the opened file. In this case the handle must have been opened in append mode.

Throws:

SSH2SFTP.SFTPException

java.io.IOException

writeFully

public long writeFully(SSH2SFTP.FileHandle handle,
              byte[] in,
              boolean append)
                throws SSH2SFTP.SFTPException,
                       java.io.IOException

Write data buffer to a file on the server. This method will be much faster if asynchronous mode is used. It will always wait until the operation has completed before returning, even if running in asynchronous mode.

Parameters:

handle - Handle identifying file. The handle will be closed when the transfer has completed.

in - Buffer containing data to write.

append - if true then the data is written at the end of the opened file. In this case the handle must have been opened in append mode.

Throws:

SSH2SFTP.SFTPException

java.io.IOException

lstat

public SSH2SFTP.FileAttributes lstat(java.lang.String name)
                              throws SSH2SFTP.SFTPException

Get attributes of a file on the server. If the name refers to a symbolic link, then this version will return information about the actual link.

Parameters:

name - Name of file to get attributes of.

Returns:

The attributes of the given name.

Throws:

SSH2SFTP.SFTPException

stat

public SSH2SFTP.FileAttributes stat(java.lang.String name)
                             throws SSH2SFTP.SFTPException

Get attributes of a file on the server. If the name refers to a symbolic link, then this version will return information about the file the link points at.

Parameters:

name - Name of file to get attributes of.

Returns:

The attributes of the given name.

Throws:

SSH2SFTP.SFTPException

fstat

public SSH2SFTP.FileAttributes fstat(SSH2SFTP.FileHandle handle)
                              throws SSH2SFTP.SFTPException

Get attributes of an open file on the server.

Parameters:

handle - Handle identifying file.

Returns:

The attributes of the given name.

Throws:

SSH2SFTP.SFTPException

setstat

public void setstat(java.lang.String name,
           SSH2SFTP.FileAttributes attrs)
             throws SSH2SFTP.SFTPException

Set attributes on a file.

Parameters:

name - Name of file to set attributes on.

attrs - Attributes to set.

Throws:

SSH2SFTP.SFTPException

fsetstat

public void fsetstat(SSH2SFTP.FileHandle handle,
            SSH2SFTP.FileAttributes attrs)
              throws SSH2SFTP.SFTPException

Set attributes on an open file.

Parameters:

handle - Handle identifying the file.

attrs - Attributes to set.

Throws:

SSH2SFTP.SFTPException

statvfs

public SSH2SFTP.FileSystemAttributes statvfs(java.lang.String name)
                                      throws SSH2SFTP.SFTPException

Get attributes of a filesystem on the server. This is an OpenSSH extension

Parameters:

name - Path into the filesystem to get data about

Returns:

The attributes of the given filesystem.

Throws:

SSH2SFTP.SFTPException

fstatvfs

public SSH2SFTP.FileSystemAttributes fstatvfs(SSH2SFTP.FileHandle handle)
                                       throws SSH2SFTP.SFTPException

Get attributes of a filesystem on the server. This is an OpenSSH extension

Parameters:

handle - Handle of a file in the filesystem

Returns:

The attributes of the given filesystem.

Throws:

SSH2SFTP.SFTPException

hardlink

public void hardlink(java.lang.String oldpath,
            java.lang.String newpath)
              throws SSH2SFTP.SFTPException

Create a hard link on the server. This is an OpenSSH extension

Parameters:

oldpath - Old path

newpath - New path

Throws:

SSH2SFTP.SFTPException

opendir

public SSH2SFTP.FileHandle opendir(java.lang.String path)
                            throws SSH2SFTP.SFTPException

Opens a directory on the server. This must be done before one can get a list of files contained in the directory.

Parameters:

path - name of directory to open

Returns:

A handle to the open directory.

Throws:

SSH2SFTP.SFTPException

readdir

public SSH2SFTP.FileAttributes[] readdir(SSH2SFTP.FileHandle handle)
                                  throws SSH2SFTP.SFTPException

Gets a list of files, and other objects, in an open directory. The handle used here must have been obtained with an earlier call to opendir.

Parameters:

handle - Handle identifying the remote directory.

Returns:

An array of attributes with one entry per contained file.

Throws:

SSH2SFTP.SFTPException

remove

public void remove(java.lang.String name)
            throws SSH2SFTP.SFTPException

Remove a file from the server.

Parameters:

name - Name of file to remove.

Throws:

SSH2SFTP.SFTPException

rename

public void rename(java.lang.String oldName,
          java.lang.String newName)
            throws SSH2SFTP.SFTPException

Rename a file on the server.

Parameters:

oldName - current name of file to rename.

newName - desired new name of file.

Throws:

SSH2SFTP.SFTPException

posixRename

public void posixRename(java.lang.String oldName,
               java.lang.String newName)
                 throws SSH2SFTP.SFTPException

Rename a file on the server with Posix semantics. This is an OpenSSH extension

Parameters:

oldName - current name of file to rename.

newName - desired new name of file.

Throws:

SSH2SFTP.SFTPException

mkdir

public void mkdir(java.lang.String name,
         SSH2SFTP.FileAttributes attrs)
           throws SSH2SFTP.SFTPException

Create a new directory on the server.

Parameters:

name - name of directory to create.

attrs - Attributes to apply to the new directory.

Throws:

SSH2SFTP.SFTPException

rmdir

public void rmdir(java.lang.String name)
           throws SSH2SFTP.SFTPException

Removes a directory from the server

Parameters:

name - Name of directory to remove.

Throws:

SSH2SFTP.SFTPException

readlink

public java.lang.String readlink(java.lang.String path)
                          throws SSH2SFTP.SFTPException

Read target of a symbolic link

Parameters:

path - name of link to read

Throws:

SSH2SFTP.SFTPException

symlink

public void symlink(java.lang.String linkpath,
           java.lang.String targetpath)
             throws SSH2SFTP.SFTPException

Create a symbolic link on the server.

Parameters:

linkpath - name of link to create

targetpath - target of link

Throws:

SSH2SFTP.SFTPException

realpath

public SSH2SFTP.FileAttributes realpath(java.lang.String nameIn)
                                 throws SSH2SFTP.SFTPException

Canonalize a given path. The canonalized path will start from the root and will not contain and '..'.

Parameters:

nameIn - Path to canonalize.

Returns:

A FileAttributes object with the name filled in.

Throws:

SSH2SFTP.SFTPException

packetReceived

public void packetReceived(SSH2SFTP.SFTPPacket pkt)

Specified by:

packetReceived in interface SSH2SFTP.Callback

readFailed

public void readFailed(SSH2SFTP.SFTPException e)

Specified by:

readFailed in interface SSH2SFTP.Callback