Class SFTPv3Client

java.lang.Object
com.trilead.ssh2.SFTPv3Client
Direct Known Subclasses:
SFTPClient

public class SFTPv3Client extends Object
A SFTPv3Client represents a SFTP (protocol version 3) client connection tunnelled over a SSH-2 connection. This is a very simple (synchronous) implementation.

Basically, most methods in this class map directly to one of the packet types described in draft-ietf-secsh-filexfer-02.txt.

Note: this is experimental code.

Error handling: the methods of this class throw IOExceptions. However, unless there is catastrophic failure, exceptions of the type SFTPv3Client will be thrown (a subclass of IOException). Therefore, you can implement more verbose behavior by checking if a thrown exception if of this type. If yes, then you can cast the exception and access detailed information about the failure.

Notes about file names, directory names and paths, copy-pasted from the specs:

  • SFTP v3 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).
  • Servers SHOULD interpret a path name component ".." as referring to the parent directory, and "." as referring to the current directory. If the server 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).

If you are still not tired then please go on and read the comment for setCharset(String).

Version:
$Id: SFTPv3Client.java,v 1.3 2008/04/01 12:38:09 cplattne Exp $
  • Field Details

  • Constructor Details

    • SFTPv3Client

      public SFTPv3Client(Connection conn, PrintStream debug) throws IOException
      Deprecated.
      this constructor (debug version) will disappear in the future, use SFTPv3Client(Connection) instead.
      Create a SFTP v3 client.
      Parameters:
      conn - The underlying SSH-2 connection to be used.
      debug - debug
      Throws:
      IOException - the io exception
    • SFTPv3Client

      public SFTPv3Client(Connection conn) throws IOException
      Create a SFTP v3 client.
      Parameters:
      conn - The underlying SSH-2 connection to be used.
      Throws:
      IOException - the io exception
  • Method Details

    • setCharset

      public void setCharset(String charset) throws IOException
      Set the charset used to convert between Java Unicode Strings and byte encodings used by the server for paths and file names. Unfortunately, the SFTP v3 draft says NOTHING about such conversions (well, with the exception of error messages which have to be in UTF-8). Newer drafts specify to use UTF-8 for file names (if I remember correctly). However, a quick test using OpenSSH serving a EXT-3 filesystem has shown that UTF-8 seems to be a bad choice for SFTP v3 (tested with filenames containing german umlauts). "windows-1252" seems to work better for Europe. Luckily, "windows-1252" is the platform default in my case =).

      If you don't set anything, then the platform default will be used (this is the default behavior).

      Parameters:
      charset - the name of the charset to be used or null to use the platform's default encoding.
      Throws:
      IOException - the io exception
      See Also:
    • getCharset

      public String getCharset()
      The currently used charset for filename encoding/decoding.
      Returns:
      The name of the charset (null if the platform's default charset is being used)
      See Also:
    • checkHandleValidAndOpen

      private final void checkHandleValidAndOpen(SFTPv3FileHandle handle) throws IOException
      Throws:
      IOException
    • sendMessage

      private final void sendMessage(int type, int requestId, byte[] msg, int off, int len) throws IOException
      Throws:
      IOException
    • sendMessage

      private final void sendMessage(int type, int requestId, byte[] msg) throws IOException
      Throws:
      IOException
    • readBytes

      private final void readBytes(byte[] buff, int pos, int len) throws IOException
      Throws:
      IOException
    • receiveMessage

      private final byte[] receiveMessage(int maxlen) throws IOException
      Read a message and guarantee that the contents is not larger than maxlen bytes.

      Note: receiveMessage(34000) actually means that the message may be up to 34004 bytes (the length attribute preceeding the contents is 4 bytes).

      Parameters:
      maxlen -
      Returns:
      the message contents
      Throws:
      IOException - the io exception
    • generateNextRequestID

      private final int generateNextRequestID()
    • closeHandle

      private final void closeHandle(byte[] handle) throws IOException
      Throws:
      IOException
    • readAttrs

      private SFTPv3FileAttributes readAttrs(TypesReader tr) throws IOException
      Throws:
      IOException
    • fstat

      public SFTPv3FileAttributes fstat(SFTPv3FileHandle handle) throws IOException
      Retrieve the file attributes of an open file.
      Parameters:
      handle - a SFTPv3FileHandle handle.
      Returns:
      a SFTPv3FileAttributes object.
      Throws:
      IOException - the io exception
    • statBoth

      private SFTPv3FileAttributes statBoth(String path, int statMethod) throws IOException
      Throws:
      IOException
    • stat

      public SFTPv3FileAttributes stat(String path) throws IOException
      Retrieve the file attributes of a file. This method follows symbolic links on the server.
      Parameters:
      path - See the comment for the class for more details.
      Returns:
      a SFTPv3FileAttributes object.
      Throws:
      IOException - the io exception
      See Also:
    • lstat

      public SFTPv3FileAttributes lstat(String path) throws IOException
      Retrieve the file attributes of a file. This method does NOT follow symbolic links on the server.
      Parameters:
      path - See the comment for the class for more details.
      Returns:
      a SFTPv3FileAttributes object.
      Throws:
      IOException - the io exception
      See Also:
    • readLink

      public String readLink(String path) throws IOException
      Read the target of a symbolic link.
      Parameters:
      path - See the comment for the class for more details.
      Returns:
      The target of the link.
      Throws:
      IOException - the io exception
    • expectStatusOKMessage

      private void expectStatusOKMessage(int id) throws IOException
      Throws:
      IOException
    • setstat

      public void setstat(String path, SFTPv3FileAttributes attr) throws IOException
      Modify the attributes of a file. Used for operations such as changing the ownership, permissions or access times, as well as for truncating a file.
      Parameters:
      path - See the comment for the class for more details.
      attr - A SFTPv3FileAttributes object. Specifies the modifications to be made to the attributes of the file. Empty fields will be ignored.
      Throws:
      IOException - the io exception
    • fsetstat

      public void fsetstat(SFTPv3FileHandle handle, SFTPv3FileAttributes attr) throws IOException
      Modify the attributes of a file. Used for operations such as changing the ownership, permissions or access times, as well as for truncating a file.
      Parameters:
      handle - a SFTPv3FileHandle handle
      attr - A SFTPv3FileAttributes object. Specifies the modifications to be made to the attributes of the file. Empty fields will be ignored.
      Throws:
      IOException - the io exception
    • createSymlink

      public void createSymlink(String src, String target) throws IOException
      Create a symbolic link on the server. Creates a link "src" that points to "target".
      Parameters:
      src - See the comment for the class for more details.
      target - See the comment for the class for more details.
      Throws:
      IOException - the io exception
    • canonicalPath

      public String canonicalPath(String path) throws IOException
      Have the server canonicalize any given path name to an absolute path. This is useful for converting path names containing ".." components or relative pathnames without a leading slash into absolute paths.
      Parameters:
      path - See the comment for the class for more details.
      Returns:
      An absolute path.
      Throws:
      IOException - the io exception
    • scanDirectory

      private final Vector scanDirectory(byte[] handle) throws IOException
      Throws:
      IOException
    • openDirectory

      private final byte[] openDirectory(String path) throws IOException
      Throws:
      IOException
    • expandString

      private final String expandString(byte[] b, int off, int len)
    • init

      private void init() throws IOException
      Throws:
      IOException
    • getProtocolVersion

      public int getProtocolVersion()
      Returns the negotiated SFTP protocol version between the client and the server.
      Returns:
      SFTP protocol version, i.e., "3".
    • close

      public void close()
      Close this SFTP session. NEVER forget to call this method to free up resources - even if you got an exception from one of the other methods. Sometimes these other methods may throw an exception, saying that the underlying channel is closed (this can happen, e.g., if the other server sent a close message.) However, as long as you have not called the close() method, you are likely wasting resources.
    • ls

      public Vector ls(String dirName) throws IOException
      List the contents of a directory.
      Parameters:
      dirName - See the comment for the class for more details.
      Returns:
      A Vector containing SFTPv3DirectoryEntry objects.
      Throws:
      IOException - the io exception
    • mkdir

      public void mkdir(String dirName, int posixPermissions) throws IOException
      Create a new directory.
      Parameters:
      dirName - See the comment for the class for more details.
      posixPermissions - the permissions for this directory, e.g., "0700" (remember that this is octal noation). The server will likely apply a umask.
      Throws:
      IOException - the io exception
    • rm

      public void rm(String fileName) throws IOException
      Remove a file.
      Parameters:
      fileName - See the comment for the class for more details.
      Throws:
      IOException - the io exception
    • rmdir

      public void rmdir(String dirName) throws IOException
      Remove an empty directory.
      Parameters:
      dirName - See the comment for the class for more details.
      Throws:
      IOException - the io exception
    • mv

      public void mv(String oldPath, String newPath) throws IOException
      Move a file or directory.
      Parameters:
      oldPath - See the comment for the class for more details.
      newPath - See the comment for the class for more details.
      Throws:
      IOException - the io exception
    • openFileRO

      public SFTPv3FileHandle openFileRO(String fileName) throws IOException
      Open a file for reading.
      Parameters:
      fileName - See the comment for the class for more details.
      Returns:
      a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • openFileRW

      public SFTPv3FileHandle openFileRW(String fileName) throws IOException
      Open a file for reading and writing.
      Parameters:
      fileName - See the comment for the class for more details.
      Returns:
      a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • createFile

      public SFTPv3FileHandle createFile(String fileName) throws IOException
      Create a file and open it for reading and writing. Same as createFile(fileName, null).
      Parameters:
      fileName - See the comment for the class for more details.
      Returns:
      a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • createFile

      public SFTPv3FileHandle createFile(String fileName, SFTPv3FileAttributes attr) throws IOException
      Create a file and open it for reading and writing. You can specify the default attributes of the file (the server may or may not respect your wishes).
      Parameters:
      fileName - See the comment for the class for more details.
      attr - may be null to use server defaults. Probably only the uid, gid and permissions (remember the server may apply a umask) entries of the SFTPv3FileHandle structure make sense. You need only to set those fields where you want to override the server's defaults.
      Returns:
      a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • createFileTruncate

      public SFTPv3FileHandle createFileTruncate(String fileName) throws IOException
      Create a file (truncate it if it already exists) and open it for reading and writing. Same as createFileTruncate(fileName, null).
      Parameters:
      fileName - See the comment for the class for more details.
      Returns:
      a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • createFileTruncate

      public SFTPv3FileHandle createFileTruncate(String fileName, SFTPv3FileAttributes attr) throws IOException
      reate a file (truncate it if it already exists) and open it for reading and writing. You can specify the default attributes of the file (the server may or may not respect your wishes).
      Parameters:
      fileName - See the comment for the class for more details.
      attr - may be null to use server defaults. Probably only the uid, gid and permissions (remember the server may apply a umask) entries of the SFTPv3FileHandle structure make sense. You need only to set those fields where you want to override the server's defaults.
      Returns:
      a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • createAttrs

      private byte[] createAttrs(SFTPv3FileAttributes attr)
    • openFile

      private SFTPv3FileHandle openFile(String fileName, int flags, SFTPv3FileAttributes attr) throws IOException
      Throws:
      IOException
    • read

      public int read(SFTPv3FileHandle handle, long fileOffset, byte[] dst, int dstoff, int len) throws IOException
      Read bytes from a file. No more than 32768 bytes may be read at once. Be aware that the semantics of read() are different than for Java streams.
      • The server will read as many bytes as it can from the file (up to len), and return them.
      • If EOF is encountered before reading any data, -1 is returned.
      • If an error occurs, an exception is thrown
      • For normal disk files, it is guaranteed that the server will return the specified number of bytes, or up to end of file. For, e.g., device files this may return fewer bytes than requested.
      Parameters:
      handle - a SFTPv3FileHandle handle
      fileOffset - offset (in bytes) in the file
      dst - the destination byte array
      dstoff - offset in the destination byte array
      len - how many bytes to read, 0 < len <= 32768 bytes
      Returns:
      the number of bytes that could be read, may be less than requested if the end of the file is reached, -1 is returned in case of EOF
      Throws:
      IOException - the io exception
    • write

      public void write(SFTPv3FileHandle handle, long fileOffset, byte[] src, int srcoff, int len) throws IOException
      Write bytes to a file. If len > 32768, then the write operation will be split into multiple writes.
      Parameters:
      handle - a SFTPv3FileHandle handle.
      fileOffset - offset (in bytes) in the file.
      src - the source byte array.
      srcoff - offset in the source byte array.
      len - how many bytes to write.
      Throws:
      IOException - the io exception
    • closeFile

      public void closeFile(SFTPv3FileHandle handle) throws IOException
      Close a file.
      Parameters:
      handle - a SFTPv3FileHandle handle
      Throws:
      IOException - the io exception
    • exists

      public boolean exists(String path) throws IOException
      Checks if the given path exists.
      Parameters:
      path - the path
      Returns:
      the boolean
      Throws:
      IOException - the io exception
    • _stat

      public SFTPv3FileAttributes _stat(String path) throws IOException
      Graceful stat(String) that returns null if the path doesn't exist.
      Parameters:
      path - the path
      Returns:
      the sft pv 3 file attributes
      Throws:
      IOException - the io exception
    • mkdirs

      public void mkdirs(String path, int posixPermission) throws IOException
      Makes sure that the directory exists, by creating it if necessary.
      Parameters:
      path - the path
      posixPermission - the posix permission
      Throws:
      IOException - the io exception
    • writeToFile

      public OutputStream writeToFile(String path) throws IOException
      Creates a new file and writes to it.
      Parameters:
      path - the path
      Returns:
      the output stream
      Throws:
      IOException - the io exception
    • read

      public InputStream read(String file) throws IOException
      Read input stream.
      Parameters:
      file - the file
      Returns:
      the input stream
      Throws:
      IOException - the io exception
    • chmod

      public void chmod(String path, int permissions) throws IOException
      Chmod.
      Parameters:
      path - the path
      permissions - the permissions
      Throws:
      IOException - the io exception