Package com.sshtools.client.sftp
Class SftpHandle
java.lang.Object
com.sshtools.client.sftp.SftpHandle
- All Implemented Interfaces:
Closeable
,AutoCloseable
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Close the handle.void
copyTo
(SftpHandle destinationHandle, com.sshtools.common.util.UnsignedInteger64 fromOffset, com.sshtools.common.util.UnsignedInteger64 length, com.sshtools.common.util.UnsignedInteger64 toOffset) boolean
com.sshtools.common.sftp.SftpFileAttributes
Get the attributes of a file.getFile()
Get the file associated with this handle.byte[]
Get the open file handleint
hashCode()
boolean
isOpen()
Determine whether the file is open.int
listChildren
(List<SftpFile> children) List the children of a directory.lock()
Lock this file.lock
(int lockFlags) Lock this file.lock
(long offset, long length, int lockflags) Lock this file or a region of it.void
performOptimizedRead
(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
performOptimizedRead
(String filename, long length, int blocksize, OutputStream out, int outstandingRequests, FileTransferProgress progress, long position) Deprecated, for removal: This API element is subject to removal in a future version.void
performOptimizedWrite
(String filename, int blocksize, int maxAsyncRequests, 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
(int blocksize, OutputStream out, FileTransferProgress progress, long position) Perform a synchronous read of a file from the remote file system.com.sshtools.common.util.UnsignedInteger32
postReadRequest
(long offset, int len) Post a read request to the server and return the request id; this is used to optimize file downloads.com.sshtools.common.util.UnsignedInteger32
postWriteRequest
(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
read
(long offset, byte[] output, int outputOffset, int len) Read bytes directly from this file.int
readFile
(com.sshtools.common.util.UnsignedInteger64 offset, byte[] output, int off, int len) Read a block of data from an open file.void
setAttributes
(com.sshtools.common.sftp.SftpFileAttributes attrs) Sets the attributes of a file.void
write
(long offset, byte[] input, int inputOffset, int len) Write bytes directly to this file.
-
Method Details
-
hashCode
public int hashCode() -
equals
-
getFile
Get the file associated with this handle.- Returns:
- file
-
lock
public Closeable lock() throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshExceptionLock this file. Requires version 6 SFTP support.- Returns:
- closeable to release lock
- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-
lock
public Closeable lock(int lockFlags) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException Lock this file. Requires version 6 SFTP support.lockFlags
may be a mask ofSftpChannel.SSH_FXF_ACCESS_BLOCK_READ
,SftpChannel.SSH_FXF_ACCESS_BLOCK_WRITE
,SftpChannel.SSH_FXF_ACCESS_BLOCK_DELETE
,SftpChannel.SSH_FXF_ACCESS_BLOCK_ADVISORY
.- Parameters:
lockFlags
-- Returns:
- closeable to release lock
- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-
lock
public Closeable lock(long offset, long length, int lockflags) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException Lock this file or a region of it. Requires version 6 SFTP support.lockFlags
may be a mask ofSftpChannel.SSH_FXF_ACCESS_BLOCK_READ
,SftpChannel.SSH_FXF_ACCESS_BLOCK_WRITE
,SftpChannel.SSH_FXF_ACCESS_BLOCK_DELETE
,SftpChannel.SSH_FXF_ACCESS_BLOCK_ADVISORY
.- Parameters:
length
-offset
-lockflags
-- Returns:
- closeable to release lock
- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-
copyTo
public void copyTo(SftpHandle destinationHandle, com.sshtools.common.util.UnsignedInteger64 fromOffset, com.sshtools.common.util.UnsignedInteger64 length, com.sshtools.common.util.UnsignedInteger64 toOffset) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException, IOException - Throws:
com.sshtools.common.sftp.SftpStatusException
com.sshtools.common.ssh.SshException
IOException
-
read
public int read(long offset, byte[] output, int outputOffset, int len) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException Read bytes directly from this file. This is a low-level operation, you may only need to use
SftpClientTask.get(String)
methods instead if you just want to download files.- Parameters:
offset
- offset in remote file to read fromoutput
- output buffer to place read bytes inoutputOffset
- offset in output buffer to write bytes tolen
- number of bytes to read- Returns:
- int number of bytes read
- Throws:
com.sshtools.common.sftp.SftpStatusException
com.sshtools.common.ssh.SshException
-
write
public void write(long offset, byte[] input, int inputOffset, int len) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException Write bytes directly to this file. This is a low-level operation, you may only need to use
SftpClientTask.put(String)
methods instead if you just want to upload files.- Parameters:
offset
- offset in remote file to write toinput
- input buffer to retrieve bytes from to writeinputOffset
- offset in output buffer to write bytes tolen
- number of bytes to write- Throws:
com.sshtools.common.sftp.SftpStatusException
com.sshtools.common.ssh.SshException
-
isOpen
public boolean isOpen()Determine whether the file is open.- Returns:
- boolean
-
getHandle
public byte[] getHandle()Get the open file handle- Returns:
- byte[]
-
close
Close the handle.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
IOException
-
listChildren
public int listChildren(List<SftpFile> children) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.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:
handle
-children
-- Returns:
- int
- Throws:
com.sshtools.common.sftp.SftpStatusException
- , SshExceptioncom.sshtools.common.ssh.SshException
-
setAttributes
public void setAttributes(com.sshtools.common.sftp.SftpFileAttributes attrs) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException Sets the attributes of a file.- Parameters:
handle
- the file object.attrs
- the new attributes.- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-
getAttributes
public com.sshtools.common.sftp.SftpFileAttributes getAttributes() throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshExceptionGet the attributes of a file.- Parameters:
handle
-- Returns:
- SftpFileAttributes
- Throws:
com.sshtools.common.sftp.SftpStatusException
- , SshExceptioncom.sshtools.common.ssh.SshException
-
performOptimizedWrite
public void performOptimizedWrite(String filename, int blocksize, int maxAsyncRequests, InputStream in, int buffersize, FileTransferProgress progress, long position) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException, TransferCancelledException Performs an optimized write of a file through asynchronous messaging and through buffering the local file into memory.- Parameters:
blocksize
- the block size to send data, should be between 4096 and 65536outstandingRequests
- the maximum number of requests that can be outstanding at any one timein
- the InputStream to read frombuffersize
- 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:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
TransferCancelledException
-
readFile
public int readFile(com.sshtools.common.util.UnsignedInteger64 offset, byte[] output, int off, int len) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException Read a block of data from an open file.- Parameters:
handle
- the open file handleoffset
- the offset to start reading in the fileoutput
- a buffer to write the returned data tooff
- the starting offset in the output bufferlen
- the length of data to read- Returns:
- int
- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-
postReadRequest
public com.sshtools.common.util.UnsignedInteger32 postReadRequest(long offset, int len) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.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:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-
performOptimizedRead
public void performOptimizedRead(long length, int blocksize, OutputStream out, int outstandingRequests, FileTransferProgress progress, long position) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.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 handlelength
- the amount of the file file to be read, equal to the file length when reading the whole fileblocksize
- the blocksize to readout
- an OutputStream to output the file intooutstandingRequests
- the maximum number of read requests toprogress
-position
- the postition from which to start reading the file- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
TransferCancelledException
-
performOptimizedRead
@Deprecated(since="3.1.0", forRemoval=true) public void performOptimizedRead(String filename, long length, int blocksize, OutputStream out, int outstandingRequests, FileTransferProgress progress, long position) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException, TransferCancelledException Deprecated, for removal: This API element is subject to removal in a future version.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.Deprecated. Filename argument irrelevant.
- Parameters:
handle
- the open files handlelength
- the amount of the file file to be read, equal to the file length when reading the whole fileblocksize
- the blocksize to readout
- an OutputStream to output the file intooutstandingRequests
- the maximum number of read requests toprogress
-position
- the postition from which to start reading the file- Throws:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
TransferCancelledException
- See Also:
-
performSynchronousRead
public void performSynchronousRead(int blocksize, OutputStream out, FileTransferProgress progress, long position) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.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:
com.sshtools.common.sftp.SftpStatusException
com.sshtools.common.ssh.SshException
TransferCancelledException
-
postWriteRequest
public com.sshtools.common.util.UnsignedInteger32 postWriteRequest(long position, byte[] data, int off, int len) throws com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.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:
com.sshtools.common.ssh.SshException
com.sshtools.common.sftp.SftpStatusException
-