com.mindbright.ssh2
Class SSH2SFTPClient

java.lang.Object
  extended by com.mindbright.ssh2.SSH2SFTP
      extended by com.mindbright.ssh2.SSH2SFTPClient

public final class SSH2SFTPClient
extends SSH2SFTP

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.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_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
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
 void asyncWait(SSH2SFTP.FileHandle handle)
          Wait for all outstanding asynchoronous 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.
 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 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.
 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.


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 asynchoronous 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

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