Package com.sshtools.client.sftp

Class SftpHandle

java.lang.Object

com.sshtools.client.sftp.SftpHandle

All Implemented Interfaces:

Closeable, AutoCloseable

public final class SftpHandle
extends Object
implements Closeable

Method Summary

Modifier and Type	Method	Description
void	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	equals(Object obj)
SftpFileAttributes	getAttributes()	Get the attributes of a file.
SftpFile	getFile()	Get the file associated with this handle.
byte[]	getHandle()	Get the open file handle
int	hashCode()
boolean	isOpen()	Determine whether the file is open.
int	listChildren(List<SftpFile> children)	List the children of a directory.
Closeable	lock()	Lock this file.
Closeable	lock(int lockFlags)	Lock this file.
Closeable	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(SftpFileAttributes attrs)	Sets the attributes of a file.
void	write(long offset, byte[] input, int inputOffset, int len)	Write bytes directly to this file.

Methods inherited from class java.lang.Object

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

Method Details

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

getFile

public SftpFile getFile()

Get the file associated with this handle.

Returns:

file

lock

public Closeable lock()
               throws SftpStatusException,
SshException

Lock this file. Requires version 6 SFTP support.

Returns:

closeable to release lock

Throws:

SshException

SftpStatusException

lock

public Closeable lock(int lockFlags)
               throws SftpStatusException,
SshException

Lock this file. Requires version 6 SFTP support. lockFlags may be a mask of SftpChannel.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:

SshException

SftpStatusException

lock

public Closeable lock(long offset,
 long length,
 int lockflags)
               throws SftpStatusException,
SshException

Lock this file or a region of it. Requires version 6 SFTP support. lockFlags may be a mask of SftpChannel.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:

SshException

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 SftpStatusException,
SshException,
IOException

Throws:

SftpStatusException

SshException

IOException

read

public int read(long offset,
 byte[] output,
 int outputOffset,
 int len)
         throws SftpStatusException,
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 from

output - output buffer to place read bytes in

outputOffset - offset in output buffer to write bytes to

len - number of bytes to read

Returns:

int number of bytes read

Throws:

SftpStatusException

SshException

write

public void write(long offset,
 byte[] input,
 int inputOffset,
 int len)
           throws SftpStatusException,
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 to

input - input buffer to retrieve bytes from to write

inputOffset - offset in output buffer to write bytes to

len - number of bytes to write

Throws:

SftpStatusException

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

public void close()
           throws IOException

Close the handle.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

SshException

SftpStatusException

IOException

listChildren

public int listChildren(List<SftpFile> children)
                 throws SftpStatusException,
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:

SftpStatusException - , SshException

SshException

setAttributes

public void setAttributes(SftpFileAttributes attrs)
                   throws SftpStatusException,
SshException

Sets the attributes of a file.

Parameters:

handle - the file object.

attrs - the new attributes.

Throws:

SshException

SftpStatusException

getAttributes

public SftpFileAttributes getAttributes()
                                 throws SftpStatusException,
SshException

Get the attributes of a file.

Parameters:

handle -

Returns:

SftpFileAttributes

Throws:

SftpStatusException - , SshException

SshException

performOptimizedWrite

public void performOptimizedWrite(String filename,
 int blocksize,
 int maxAsyncRequests,
 InputStream in,
 int buffersize,
 FileTransferProgress progress,
 long position)
                           throws SftpStatusException,
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 65536

outstandingRequests - the maximum number of requests that can be outstanding at any one time

in - the InputStream to read from

buffersize - 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:

SshException

SftpStatusException

TransferCancelledException

readFile

public int readFile(com.sshtools.common.util.UnsignedInteger64 offset,
 byte[] output,
 int off,
 int len)
             throws SftpStatusException,
SshException

Read a block of data from an open file.

Parameters:

handle - the open file handle

offset - the offset to start reading in the file

output - a buffer to write the returned data to

off - the starting offset in the output buffer

len - the length of data to read

Returns:

int

Throws:

SshException

SftpStatusException

postReadRequest

public com.sshtools.common.util.UnsignedInteger32 postReadRequest(long offset,
 int len)
                                                           throws SftpStatusException,
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:

SshException

SftpStatusException

performOptimizedRead

public void performOptimizedRead(long length,
 int blocksize,
 OutputStream out,
 int outstandingRequests,
 FileTransferProgress progress,
 long position)
                          throws SftpStatusException,
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 handle

length - the amount of the file file to be read, equal to the file length when reading the whole file

blocksize - the blocksize to read

out - an OutputStream to output the file into

outstandingRequests - the maximum number of read requests to

progress -

position - the postition from which to start reading the file

Throws:

SshException

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 SftpStatusException,
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 handle

length - the amount of the file file to be read, equal to the file length when reading the whole file

blocksize - the blocksize to read

out - an OutputStream to output the file into

outstandingRequests - the maximum number of read requests to

progress -

position - the postition from which to start reading the file

Throws:

SshException

SftpStatusException

TransferCancelledException

See Also:

• performOptimizedRead(long, int, OutputStream, int, FileTransferProgress, long)

performSynchronousRead

public void performSynchronousRead(int blocksize,
 OutputStream out,
 FileTransferProgress progress,
 long position)
                            throws SftpStatusException,
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:

SftpStatusException

SshException

TransferCancelledException

postWriteRequest

public com.sshtools.common.util.UnsignedInteger32 postWriteRequest(long position,
 byte[] data,
 int off,
 int len)
                                                            throws SftpStatusException,
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:

SshException

SftpStatusException