Package org.apache.sshd.sftp.client

Interface SftpClient

All Superinterfaces:

AutoCloseable, Channel, org.apache.sshd.common.channel.ChannelHolder, org.apache.sshd.client.channel.ClientChannelHolder, org.apache.sshd.client.session.ClientSessionHolder, Closeable, org.apache.sshd.common.NamedResource, org.apache.sshd.common.session.SessionContextHolder, org.apache.sshd.common.session.SessionHolder<org.apache.sshd.client.session.ClientSession>, org.apache.sshd.client.subsystem.SubsystemClient

All Known Subinterfaces:

FullAccessSftpClient

All Known Implementing Classes:

AbstractSftpClient, DefaultSftpClient

public interface SftpClient
extends org.apache.sshd.client.subsystem.SubsystemClient

Author:

Apache MINA Project

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	SftpClient.Attribute
static class	SftpClient.Attributes
static class	SftpClient.CloseableHandle
static enum	SftpClient.CopyMode
static class	SftpClient.DirEntry
static class	SftpClient.Handle
static enum	SftpClient.OpenMode

Field Summary

Fields

Modifier and Type	Field	Description
static final Set<SftpClient.OpenMode>	DEFAULT_CHANNEL_MODES	Default modes for opening a channel if no specific modes specified
static final SftpClient.DirEntry[]	EMPTY_DIR_ENTRIES
static final int	IO_BUFFER_SIZE
static final int	MIN_BUFFER_SIZE
static final int	MIN_READ_BUFFER_SIZE
static final int	MIN_WRITE_BUFFER_SIZE

Fields inherited from interface org.apache.sshd.common.NamedResource

BY_NAME_COMPARATOR, NAME_EXTRACTOR

Method Summary

Modifier and Type	Method	Description
String	canonicalPath(String path)	The effective "normalized" remote path
void	close(SftpClient.Handle handle)	Close the handle obtained from one of the open methods
default <E extends SftpClientExtension> E	getExtension(Class<? extends E> extensionType)
default SftpClientExtension	getExtension(String extensionName)
SftpClientExtension	getExtension(SftpClientExtensionFactory factory)
default String	getName()
Charset	getNameDecodingCharset()
NavigableMap<String,byte[]>	getServerExtensions()
int	getVersion()
boolean	isClosing()
void	link(String linkPath, String targetPath, boolean symbolic)	Create a link
Iterable<SftpClient.DirEntry>	listDir(SftpClient.Handle handle)
void	lock(SftpClient.Handle handle, long offset, long length, int mask)
SftpClient.Attributes	lstat(String path)	Retrieve remote path meta-data - do not follow symbolic links
void	mkdir(String path)	Create remote directory
default SftpClient.CloseableHandle	open(String path)	Opens a remote file for read
SftpClient.CloseableHandle	open(String path, Collection<SftpClient.OpenMode> options)	Opens a remote file with the specified mode(s)
default SftpClient.CloseableHandle	open(String path, SftpClient.OpenMode... options)	Opens a remote file with the specified mode(s)
SftpClient.CloseableHandle	openDir(String path)	Obtain a handle for a directory
FileChannel	openRemoteFileChannel(String path, Collection<SftpClient.OpenMode> modes)	Opens an FileChannel on the specified remote path
default FileChannel	openRemoteFileChannel(String path, SftpClient.OpenMode... modes)
default FileChannel	openRemotePathChannel(String path, OpenOption... options)
default FileChannel	openRemotePathChannel(String path, Collection<? extends OpenOption> options)
default void	put(InputStream stream, int bufferSize, String path)
void	put(InputStream stream, int bufferSize, String path, Collection<SftpClient.OpenMode> modes)	Write data from an InputStream to a remote file.
default void	put(InputStream stream, int bufferSize, String path, SftpClient.OpenMode... modes)
default void	put(InputStream stream, String path)
default void	put(InputStream stream, String path, Collection<SftpClient.OpenMode> modes)
default void	put(InputStream stream, String path, SftpClient.OpenMode... modes)
default void	put(Path localFile, int bufferSize, String path)
default void	put(Path localFile, int bufferSize, String path, Collection<SftpClient.OpenMode> modes)	Uploads a local file to a remote file.
default void	put(Path localFile, int bufferSize, String path, SftpClient.OpenMode... modes)
default void	put(Path localFile, String path)
default void	put(Path localFile, String path, Collection<SftpClient.OpenMode> modes)
default void	put(Path localFile, String path, SftpClient.OpenMode... modes)
default InputStream	read(String path)
default InputStream	read(String path, int bufferSize)
InputStream	read(String path, int bufferSize, Collection<SftpClient.OpenMode> mode)	Read a remote file's data via an input stream
default InputStream	read(String path, int bufferSize, SftpClient.OpenMode... mode)
default InputStream	read(String path, Collection<SftpClient.OpenMode> mode)
default InputStream	read(String path, SftpClient.OpenMode... mode)
default int	read(SftpClient.Handle handle, long fileOffset, byte[] dst)	Reads data from the open (file) handle
default int	read(SftpClient.Handle handle, long fileOffset, byte[] dst, int dstOffset, int len)
int	read(SftpClient.Handle handle, long fileOffset, byte[] dst, int dstOffset, int len, AtomicReference<Boolean> eofSignalled)	Reads data from the open (file) handle
default int	read(SftpClient.Handle handle, long fileOffset, byte[] dst, AtomicReference<Boolean> eofSignalled)	Reads data from the open (file) handle
Iterable<SftpClient.DirEntry>	readDir(String path)
default List<SftpClient.DirEntry>	readDir(SftpClient.Handle handle)
List<SftpClient.DirEntry>	readDir(SftpClient.Handle handle, AtomicReference<Boolean> eolIndicator)
default Collection<SftpClient.DirEntry>	readEntries(String path)	Reads all entries available for a directory
String	readLink(String path)	Retrieve target of a link
void	remove(String path)
default void	rename(String oldPath, String newPath)
void	rename(String oldPath, String newPath, Collection<SftpClient.CopyMode> options)
default void	rename(String oldPath, String newPath, SftpClient.CopyMode... options)
void	rmdir(String path)	Remove remote directory
void	setNameDecodingCharset(Charset cs)
void	setStat(String path, SftpClient.Attributes attributes)	Update remote node meta-data
void	setStat(SftpClient.Handle handle, SftpClient.Attributes attributes)	Update remote node meta-data
default SftpClient	singleSessionInstance()	Creates an SftpClient instance that also closes the underlying client session when the client instance is closed.
SftpClient.Attributes	stat(String path)	Retrieve remote path meta-data - follow symbolic links if encountered
SftpClient.Attributes	stat(SftpClient.Handle handle)	Retrieve file/directory handle meta-data
default void	symLink(String linkPath, String targetPath)	Create symbolic link
void	unlock(SftpClient.Handle handle, long offset, long length)
default OutputStream	write(String path)
default OutputStream	write(String path, int bufferSize)
OutputStream	write(String path, int bufferSize, Collection<SftpClient.OpenMode> mode)	Write to a remote file via an output stream
default OutputStream	write(String path, int bufferSize, SftpClient.OpenMode... mode)
default OutputStream	write(String path, Collection<SftpClient.OpenMode> mode)
default OutputStream	write(String path, SftpClient.OpenMode... mode)
default void	write(SftpClient.Handle handle, long fileOffset, byte[] src)
void	write(SftpClient.Handle handle, long fileOffset, byte[] src, int srcOffset, int len)	Write data to (open) file handle

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Methods inherited from interface org.apache.sshd.client.channel.ClientChannelHolder

getChannel, getClientChannel

Methods inherited from interface org.apache.sshd.client.session.ClientSessionHolder

getClientSession

Methods inherited from interface org.apache.sshd.common.session.SessionHolder

getSessionContext

Methods inherited from interface org.apache.sshd.client.subsystem.SubsystemClient

getSession

Field Details

EMPTY_DIR_ENTRIES

static final SftpClient.DirEntry[] EMPTY_DIR_ENTRIES

MIN_BUFFER_SIZE

static final int MIN_BUFFER_SIZE

See Also:

• Constant Field Values

MIN_READ_BUFFER_SIZE

static final int MIN_READ_BUFFER_SIZE

See Also:

• Constant Field Values

MIN_WRITE_BUFFER_SIZE

static final int MIN_WRITE_BUFFER_SIZE

See Also:

• Constant Field Values

IO_BUFFER_SIZE

static final int IO_BUFFER_SIZE

See Also:

• Constant Field Values

DEFAULT_CHANNEL_MODES

static final Set<SftpClient.OpenMode> DEFAULT_CHANNEL_MODES

Default modes for opening a channel if no specific modes specified

Method Details

getVersion

int getVersion()

Returns:

The negotiated SFTP protocol version

getName

default String getName()

Specified by:

getName in interface org.apache.sshd.common.NamedResource

getNameDecodingCharset

Charset getNameDecodingCharset()

Returns:

The (never null) Charset used to decode referenced files/folders names

See Also:

• SftpModuleProperties.NAME_DECODING_CHARSET

setNameDecodingCharset

void setNameDecodingCharset(Charset cs)

getServerExtensions

NavigableMap<String,byte[]> getServerExtensions()

Returns:

An (unmodifiable) NavigableMap of the reported server extensions. where key=extension name (case insensitive)

isClosing

boolean isClosing()

open

default SftpClient.CloseableHandle open(String path)
                                 throws IOException

Opens a remote file for read

Parameters:

path - The remote path

Returns:

The file's SftpClient.CloseableHandle

Throws:

IOException - If failed to open the remote file

See Also:

• open(String, Collection)

open

default SftpClient.CloseableHandle open(String path,
 SftpClient.OpenMode... options)
                                 throws IOException

Opens a remote file with the specified mode(s)

Parameters:

path - The remote path

options - The desired mode - if none specified then SftpClient.OpenMode.Read is assumed

Returns:

The file's SftpClient.CloseableHandle

Throws:

IOException - If failed to open the remote file

See Also:

• open(String, Collection)

open

SftpClient.CloseableHandle open(String path,
 Collection<SftpClient.OpenMode> options)
                         throws IOException

Opens a remote file with the specified mode(s)

Parameters:

path - The remote path

options - The desired mode - if none specified then SftpClient.OpenMode.Read is assumed

Returns:

The file's SftpClient.CloseableHandle

Throws:

IOException - If failed to open the remote file

close

void close(SftpClient.Handle handle)
    throws IOException

Close the handle obtained from one of the open methods

Parameters:

handle - The Handle to close

Throws:

IOException - If failed to execute

remove

void remove(String path)
     throws IOException

Parameters:

path - The remote path to remove

Throws:

IOException - If failed to execute

rename

default void rename(String oldPath,
 String newPath)
             throws IOException

Throws:

IOException

rename

default void rename(String oldPath,
 String newPath,
 SftpClient.CopyMode... options)
             throws IOException

Throws:

IOException

rename

void rename(String oldPath,
 String newPath,
 Collection<SftpClient.CopyMode> options)
     throws IOException

Throws:

IOException

read

default int read(SftpClient.Handle handle,
 long fileOffset,
 byte[] dst)
          throws IOException

Reads data from the open (file) handle

Parameters:

handle - The file SftpClient.Handle to read from

fileOffset - The file offset to read from

dst - The destination buffer

Returns:

Number of read bytes - -1 if EOF reached

Throws:

IOException - If failed to read the data

See Also:

• read(Handle, long, byte[], int, int)

read

default int read(SftpClient.Handle handle,
 long fileOffset,
 byte[] dst,
 AtomicReference<Boolean> eofSignalled)
          throws IOException

Reads data from the open (file) handle

Parameters:

handle - The file SftpClient.Handle to read from

fileOffset - The file offset to read from

dst - The destination buffer

eofSignalled - If not null then upon return holds a value indicating whether EOF was reached due to the read. If null indicator value then this indication is not available

Returns:

Number of read bytes - -1 if EOF reached

Throws:

IOException - If failed to read the data

See Also:

• read(Handle, long, byte[], int, int, AtomicReference)
• SFTP v6 - section 9.3

read

default int read(SftpClient.Handle handle,
 long fileOffset,
 byte[] dst,
 int dstOffset,
 int len)
          throws IOException

Throws:

IOException

read

int read(SftpClient.Handle handle,
 long fileOffset,
 byte[] dst,
 int dstOffset,
 int len,
 AtomicReference<Boolean> eofSignalled)
  throws IOException

Reads data from the open (file) handle

Parameters:

handle - The file SftpClient.Handle to read from

fileOffset - The file offset to read from

dst - The destination buffer

dstOffset - Offset in destination buffer to place the read data

len - Available destination buffer size to read

eofSignalled - If not null then upon return holds a value indicating whether EOF was reached due to the read. If null indicator value then this indication is not available

Returns:

Number of read bytes - -1 if EOF reached

Throws:

IOException - If failed to read the data

See Also:

• SFTP v6 - section 9.3

write

default void write(SftpClient.Handle handle,
 long fileOffset,
 byte[] src)
            throws IOException

Throws:

IOException

write

void write(SftpClient.Handle handle,
 long fileOffset,
 byte[] src,
 int srcOffset,
 int len)
    throws IOException

Write data to (open) file handle

Parameters:

handle - The file SftpClient.Handle

fileOffset - Zero-based offset to write in file

src - Data buffer

srcOffset - Offset of valid data in buffer

len - Number of bytes to write

Throws:

IOException - If failed to write the data

mkdir

void mkdir(String path)
    throws IOException

Create remote directory

Parameters:

path - Remote directory path

Throws:

IOException - If failed to execute

rmdir

void rmdir(String path)
    throws IOException

Remove remote directory

Parameters:

path - Remote directory path

Throws:

IOException - If failed to execute

openDir

SftpClient.CloseableHandle openDir(String path)
                            throws IOException

Obtain a handle for a directory

Parameters:

path - Remote directory path

Returns:

The associated directory SftpClient.Handle

Throws:

IOException - If failed to execute

readDir

default List<SftpClient.DirEntry> readDir(SftpClient.Handle handle)
                                   throws IOException

Parameters:

handle - Directory SftpClient.Handle to read from

Returns:

A List of entries - null to indicate no more entries Note: the list may be incomplete since the client and server have some internal imposed limit on the number of entries they can process. Therefore several calls to this method may be required (until null). In order to iterate over all the entries use readDir(String)

Throws:

IOException - If failed to access the remote site

readDir

List<SftpClient.DirEntry> readDir(SftpClient.Handle handle,
 AtomicReference<Boolean> eolIndicator)
                           throws IOException

Parameters:

handle - Directory SftpClient.Handle to read from

eolIndicator - An indicator that can be used to get information whether end of list has been reached - ignored if null. Upon return, set value indicates whether all entries have been exhausted - a null value means that this information cannot be provided and another call to readDir is necessary in order to verify that no more entries are pending

Returns:

A List of entries - null to indicate no more entries

Throws:

IOException - If failed to access the remote site

See Also:

• SFTP v6 - section 9.4

listDir

Iterable<SftpClient.DirEntry> listDir(SftpClient.Handle handle)
                               throws IOException

Parameters:

handle - A directory SftpClient.Handle

Returns:

An Iterable that can be used to iterate over all the directory entries (like readDir(String)). Note: the iterable instance is not re-usable - i.e., files can be iterated only once

Throws:

IOException - If failed to access the directory

canonicalPath

String canonicalPath(String path)
              throws IOException

The effective "normalized" remote path

Parameters:

path - The requested path - may be relative, and/or contain dots - e.g., ".", "..", "./foo", "../bar"

Returns:

The effective "normalized" remote path

Throws:

IOException - If failed to execute

stat

SftpClient.Attributes stat(String path)
                    throws IOException

Retrieve remote path meta-data - follow symbolic links if encountered

Parameters:

path - The remote path

Returns:

The associated SftpClient.Attributes

Throws:

IOException - If failed to execute

lstat

SftpClient.Attributes lstat(String path)
                     throws IOException

Retrieve remote path meta-data - do not follow symbolic links

Parameters:

path - The remote path

Returns:

The associated SftpClient.Attributes

Throws:

IOException - If failed to execute

stat

SftpClient.Attributes stat(SftpClient.Handle handle)
                    throws IOException

Retrieve file/directory handle meta-data

Parameters:

handle - The SftpClient.Handle obtained via one of the open calls

Returns:

The associated SftpClient.Attributes

Throws:

IOException - If failed to execute

setStat

void setStat(String path,
 SftpClient.Attributes attributes)
      throws IOException

Update remote node meta-data

Parameters:

path - The remote path

attributes - The SftpClient.Attributes to update

Throws:

IOException - If failed to execute

setStat

void setStat(SftpClient.Handle handle,
 SftpClient.Attributes attributes)
      throws IOException

Update remote node meta-data

Parameters:

handle - The SftpClient.Handle obtained via one of the open calls

attributes - The SftpClient.Attributes to update

Throws:

IOException - If failed to execute

readLink

String readLink(String path)
         throws IOException

Retrieve target of a link

Parameters:

path - Remote path that represents a link

Returns:

The link target

Throws:

IOException - If failed to execute

symLink

default void symLink(String linkPath,
 String targetPath)
              throws IOException

Create symbolic link

Parameters:

linkPath - The link location

targetPath - The referenced target by the link

Throws:

IOException - If failed to execute

See Also:

• link(String, String, boolean)

link

void link(String linkPath,
 String targetPath,
 boolean symbolic)
   throws IOException

Create a link

Parameters:

linkPath - The link location

targetPath - The referenced target by the link

symbolic - If true then make this a symbolic link, otherwise a hard one

Throws:

IOException - If failed to execute

lock

void lock(SftpClient.Handle handle,
 long offset,
 long length,
 int mask)
   throws IOException

Throws:

IOException

unlock

void unlock(SftpClient.Handle handle,
 long offset,
 long length)
     throws IOException

Throws:

IOException

openRemotePathChannel

default FileChannel openRemotePathChannel(String path,
 OpenOption... options)
                                   throws IOException

Throws:

IOException

openRemotePathChannel

default FileChannel openRemotePathChannel(String path,
 Collection<? extends OpenOption> options)
                                   throws IOException

Throws:

IOException

openRemoteFileChannel

default FileChannel openRemoteFileChannel(String path,
 SftpClient.OpenMode... modes)
                                   throws IOException

Throws:

IOException

openRemoteFileChannel

FileChannel openRemoteFileChannel(String path,
 Collection<SftpClient.OpenMode> modes)
                           throws IOException

Opens an FileChannel on the specified remote path

Parameters:

path - The remote path

modes - The access mode(s) - if null/empty then the DEFAULT_CHANNEL_MODES are used

Returns:

The open FileChannel - Note: do not close this owner client instance until the channel is no longer needed since it uses the client for providing the channel's functionality.

Throws:

IOException - If failed to open the channel

See Also:

• Channels.newInputStream(java.nio.channels.ReadableByteChannel)
• Channels.newOutputStream(java.nio.channels.WritableByteChannel)

readDir

Iterable<SftpClient.DirEntry> readDir(String path)
                               throws IOException

Parameters:

path - The remote directory path

Returns:

An Iterable that can be used to iterate over all the directory entries (unlike readDir(Handle))

Throws:

IOException - If failed to access the remote site

See Also:

• readDir(Handle)

readEntries

default Collection<SftpClient.DirEntry> readEntries(String path)
                                             throws IOException

Reads all entries available for a directory

Parameters:

path - Remote directory path

Returns:

A Collection of all the entries in the remote directory

Throws:

IOException - If failed to retrieve the entries

See Also:

• readDir(String)

read

default InputStream read(String path)
                  throws IOException

Throws:

IOException

read

default InputStream read(String path,
 int bufferSize)
                  throws IOException

Throws:

IOException

read

default InputStream read(String path,
 SftpClient.OpenMode... mode)
                  throws IOException

Throws:

IOException

read

default InputStream read(String path,
 int bufferSize,
 SftpClient.OpenMode... mode)
                  throws IOException

Throws:

IOException

read

default InputStream read(String path,
 Collection<SftpClient.OpenMode> mode)
                  throws IOException

Throws:

IOException

read

InputStream read(String path,
 int bufferSize,
 Collection<SftpClient.OpenMode> mode)
          throws IOException

Read a remote file's data via an input stream

Parameters:

path - The remote file path

bufferSize - The internal read buffer size

mode - The remote file SftpClient.OpenModes

Returns:

An InputStream for reading the remote file data

Throws:

IOException - If failed to execute

write

default OutputStream write(String path)
                    throws IOException

Throws:

IOException

write

default OutputStream write(String path,
 int bufferSize)
                    throws IOException

Throws:

IOException

write

default OutputStream write(String path,
 SftpClient.OpenMode... mode)
                    throws IOException

Throws:

IOException

write

default OutputStream write(String path,
 int bufferSize,
 SftpClient.OpenMode... mode)
                    throws IOException

Throws:

IOException

write

default OutputStream write(String path,
 Collection<SftpClient.OpenMode> mode)
                    throws IOException

Throws:

IOException

write

OutputStream write(String path,
 int bufferSize,
 Collection<SftpClient.OpenMode> mode)
            throws IOException

Write to a remote file via an output stream

Parameters:

path - The remote file path

bufferSize - The internal write buffer size

mode - The remote file SftpClient.OpenModes

Returns:

An OutputStream for writing the data

Throws:

IOException - If failed to execute

put

default void put(Path localFile,
 String path)
          throws IOException

Throws:

IOException

put

default void put(InputStream stream,
 String path)
          throws IOException

Throws:

IOException

put

default void put(Path localFile,
 int bufferSize,
 String path)
          throws IOException

Throws:

IOException

put

default void put(InputStream stream,
 int bufferSize,
 String path)
          throws IOException

Throws:

IOException

put

default void put(Path localFile,
 String path,
 SftpClient.OpenMode... modes)
          throws IOException

Throws:

IOException

put

default void put(InputStream stream,
 String path,
 SftpClient.OpenMode... modes)
          throws IOException

Throws:

IOException

put

default void put(Path localFile,
 int bufferSize,
 String path,
 SftpClient.OpenMode... modes)
          throws IOException

Throws:

IOException

put

default void put(InputStream stream,
 int bufferSize,
 String path,
 SftpClient.OpenMode... modes)
          throws IOException

Throws:

IOException

put

default void put(Path localFile,
 String path,
 Collection<SftpClient.OpenMode> modes)
          throws IOException

Throws:

IOException

put

default void put(InputStream stream,
 String path,
 Collection<SftpClient.OpenMode> modes)
          throws IOException

Throws:

IOException

put

default void put(Path localFile,
 int bufferSize,
 String path,
 Collection<SftpClient.OpenMode> modes)
          throws IOException

Uploads a local file to a remote file.

Parameters:

localFile - Path of the local file to upload

bufferSize - SFTP packet size; i.e., amount of data to send in a single SFTP request. Most servers have a limit of 256kB. If zero, a default buffer size is chosen depending on the peer's channel packet size; so typically about 32kB.

path - The remote file path

modes - The remote file SftpClient.OpenModes

Throws:

IOException - if data cannot be read, or cannot be written

put

void put(InputStream stream,
 int bufferSize,
 String path,
 Collection<SftpClient.OpenMode> modes)
  throws IOException

Write data from an InputStream to a remote file.

Parameters:

stream - InputStream to read from

bufferSize - SFTP packet size; i.e., amount of data to send in a single SFTP request. Most servers have a limit of 256kB. If zero, a default buffer size is chosen depending on the peer's channel packet size; so typically about 32kB.

path - The remote file path

modes - The remote file SftpClient.OpenModes

Throws:

IOException - if data cannot be read, or cannot be written

getExtension

default <E extends SftpClientExtension> E getExtension(Class<? extends E> extensionType)

Type Parameters:

E - The generic extension type

Parameters:

extensionType - The extension type

Returns:

The extension instance - Note: it is up to the caller to invoke OptionalFeature.isSupported() - null if this extension type is not implemented by the client

See Also:

• getServerExtensions()

getExtension

default SftpClientExtension getExtension(String extensionName)

Parameters:

extensionName - The extension name

Returns:

The extension instance - Note: it is up to the caller to invoke OptionalFeature.isSupported() - null if this extension type is not implemented by the client

See Also:

• getServerExtensions()

getExtension

SftpClientExtension getExtension(SftpClientExtensionFactory factory)

Parameters:

factory - The SftpClientExtensionFactory instance to use - ignored if null

Returns:

The extension instance - Note: it is up to the caller to invoke OptionalFeature.isSupported() - null if this extension type is not implemented by the client

singleSessionInstance

default SftpClient singleSessionInstance()

Creates an SftpClient instance that also closes the underlying client session when the client instance is closed.

Returns:

The wrapper instance