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 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.
    Get the file associated with this handle.
    byte[]
    Get the open file handle
    int
     
    boolean
    Determine whether the file is open.
    int
    List the children of a directory.
    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.

    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 com.sshtools.common.sftp.SftpStatusException, com.sshtools.common.ssh.SshException
      Lock 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
      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
      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 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:
      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 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:
      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

      public void close() throws IOException
      Close the handle.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      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 - , SshException
      com.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.SshException
      Get the attributes of a file.
      Parameters:
      handle -
      Returns:
      SftpFileAttributes
      Throws:
      com.sshtools.common.sftp.SftpStatusException - , SshException
      com.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 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:
      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 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:
      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 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:
      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 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:
      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