| java.lang.Object
 ch.ethz.ssh2.SFTPv3Client
| SFTPv3Client | | public class SFTPv3Client (Code) | | 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
SFTPv3Client.setCharset(String) .
author:
Christian Plattner, plattner@inf.ethz.ch
version:
$Id: SFTPv3Client.java,v 1.9 2006/09/20 12:51:37 cplattne Exp $ |
| Method Summary | |
| public String | canonicalPath(String path)
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 SFTPv3Client comment for the class for more details. | | public void | close()
Close this SFTP session. | | public void | closeFile(SFTPv3FileHandle handle)
Close a file. | | public SFTPv3FileHandle | createFile(String fileName)
Create a file and open it for reading and writing.
Same as
SFTPv3Client.createFile(String,SFTPv3FileAttributes) createFile(fileName, null) .
Parameters:
fileName - See the SFTPv3Client comment for the class for more details. | | public SFTPv3FileHandle | createFile(String fileName, SFTPv3FileAttributes attr)
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 SFTPv3Client comment for the class for more details.
Parameters:
attr - may be null to use server defaults. | | public SFTPv3FileHandle | createFileTruncate(String fileName)
Create a file (truncate it if it already exists) and open it for reading and writing.
Same as
SFTPv3Client.createFileTruncate(String,SFTPv3FileAttributes) createFileTruncate(fileName, null) .
Parameters:
fileName - See the SFTPv3Client comment for the class for more details. | | public SFTPv3FileHandle | createFileTruncate(String fileName, SFTPv3FileAttributes attr)
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 SFTPv3Client comment for the class for more details.
Parameters:
attr - may be null to use server defaults. | | public void | createSymlink(String src, String target)
Create a symbolic link on the server. | | public void | fsetstat(SFTPv3FileHandle handle, SFTPv3FileAttributes attr)
Modify the attributes of a file. | | public SFTPv3FileAttributes | fstat(SFTPv3FileHandle handle)
Retrieve the file attributes of an open file.
Parameters:
handle - a SFTPv3FileHandle handle. | | public String | getCharset()
The currently used charset for filename encoding/decoding. | | public int | getProtocolVersion()
Returns the negotiated SFTP protocol version between the client and the server. | | public Vector | ls(String dirName)
List the contents of a directory.
Parameters:
dirName - See the SFTPv3Client comment for the class for more details. | | public SFTPv3FileAttributes | lstat(String path)
Retrieve the file attributes of a file. | | public void | mkdir(String dirName, int posixPermissions)
Create a new directory.
Parameters:
dirName - See the SFTPv3Client comment for the class for more details.
Parameters:
posixPermissions - the permissions for this directory, e.g., "0700". | | public void | mv(String oldPath, String newPath)
Move a file or directory. | | public SFTPv3FileHandle | openFileRO(String fileName)
Open a file for reading.
Parameters:
fileName - See the SFTPv3Client comment for the class for more details. | | public SFTPv3FileHandle | openFileRW(String fileName)
Open a file for reading and writing.
Parameters:
fileName - See the SFTPv3Client comment for the class for more details. | | public int | read(SFTPv3FileHandle handle, long fileOffset, byte[] dst, int dstoff, int len)
Read bytes from a file. | | public String | readLink(String path)
Read the target of a symbolic link.
Parameters:
path - See the SFTPv3Client comment for the class for more details. | | public void | rm(String fileName)
Remove a file. | | public void | rmdir(String dirName)
Remove an empty directory. | | public void | setCharset(String charset)
Set the charset used to convert between Java Unicode Strings and byte encodings
used by the server for paths and file names. | | public void | setstat(String path, SFTPv3FileAttributes attr)
Modify the attributes of a file. | | public SFTPv3FileAttributes | stat(String path)
Retrieve the file attributes of a file. | | public void | write(SFTPv3FileHandle handle, long fileOffset, byte[] src, int srcoff, int len)
Write bytes to a file. |
| flag_closed | | boolean flag_closed(Code) | | |
| next_request_id | | int next_request_id(Code) | | |
| protocol_version | | int protocol_version(Code) | | |
| canonicalPath | | public String canonicalPath(String path) throws IOException(Code) | | 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 SFTPv3Client comment for the class for more details. An absolute path.
throws:
IOException - |
| close | | public void close()(Code) | | 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.
|
| createFile | | public SFTPv3FileHandle createFile(String fileName, SFTPv3FileAttributes attr) throws IOException(Code) | | 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 SFTPv3Client comment for the class for more details.
Parameters:
attr - may be null to use server defaults. Probably onlythe uid, gid and permissions(remember the server may apply a umask) entries of the SFTPv3FileHandlestructure make sense. You need only to set those fields where you wantto override the server's defaults. a SFTPv3FileHandle handle
throws:
IOException - |
| createFileTruncate | | public SFTPv3FileHandle createFileTruncate(String fileName, SFTPv3FileAttributes attr) throws IOException(Code) | | 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 SFTPv3Client comment for the class for more details.
Parameters:
attr - may be null to use server defaults. Probably onlythe uid, gid and permissions(remember the server may apply a umask) entries of the SFTPv3FileHandlestructure make sense. You need only to set those fields where you wantto override the server's defaults. a SFTPv3FileHandle handle
throws:
IOException - |
| createSymlink | | public void createSymlink(String src, String target) throws IOException(Code) | | Create a symbolic link on the server. Creates a link "src" that points
to "target".
Parameters:
src - See the SFTPv3Client comment for the class for more details.
Parameters:
target - See the SFTPv3Client comment for the class for more details.
throws:
IOException - |
| fsetstat | | public void fsetstat(SFTPv3FileHandle handle, SFTPv3FileAttributes attr) throws IOException(Code) | | 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
Parameters:
attr - A SFTPv3FileAttributes object. Specifies the modifications to bemade to the attributes of the file. Empty fields will be ignored.
throws:
IOException - |
| getCharset | | public String getCharset()(Code) | | The currently used charset for filename encoding/decoding.
See Also: SFTPv3Client.setCharset(String) The name of the charset (null if the platform's default charset is being used) |
| getProtocolVersion | | public int getProtocolVersion()(Code) | | Returns the negotiated SFTP protocol version between the client and the server.
SFTP protocol version, i.e., "3". |
| mkdir | | public void mkdir(String dirName, int posixPermissions) throws IOException(Code) | | Create a new directory.
Parameters:
dirName - See the SFTPv3Client comment for the class for more details.
Parameters:
posixPermissions - the permissions for this directory, e.g., "0700". The serverwill likely apply a umask.
throws:
IOException - |
| read | | public int read(SFTPv3FileHandle handle, long fileOffset, byte[] dst, int dstoff, int len) throws IOException(Code) | | 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
Parameters:
fileOffset - offset (in bytes) in the file
Parameters:
dst - the destination byte array
Parameters:
dstoff - offset in the destination byte array
Parameters:
len - how many bytes to read, 0 < len <= 32768 bytes the number of bytes that could be read, may be less than requested ifthe end of the file is reached, -1 is returned in case of EOF
throws:
IOException - |
| setCharset | | public void setCharset(String charset) throws IOException(Code) | | 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).
See Also: SFTPv3Client.getCharset()
Parameters:
charset - the name of the charset to be used or null to use the platform'sdefault encoding.
throws:
IOException - |
| setstat | | public void setstat(String path, SFTPv3FileAttributes attr) throws IOException(Code) | | 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 SFTPv3Client comment for the class for more details.
Parameters:
attr - A SFTPv3FileAttributes object. Specifies the modifications to bemade to the attributes of the file. Empty fields will be ignored.
throws:
IOException - |
| write | | public void write(SFTPv3FileHandle handle, long fileOffset, byte[] src, int srcoff, int len) throws IOException(Code) | | Write bytes to a file. If len > 32768, then the write operation will
be split into multiple writes.
Parameters:
handle - a SFTPv3FileHandle handle.
Parameters:
fileOffset - offset (in bytes) in the file.
Parameters:
src - the source byte array.
Parameters:
srcoff - offset in the source byte array.
Parameters:
len - how many bytes to write.
throws:
IOException - |
|
|