Package org.apache.sshd.scp.common

Interface ScpFileOpener

All Known Implementing Classes:

DefaultScpFileOpener

public interface ScpFileOpener

Plug-in mechanism for users to intervene in the SCP process - e.g., apply some kind of traffic shaping mechanism, display upload/download progress, etc...

Author:

Apache MINA SSHD Project

Method Summary

Modifier and Type	Method	Description
default void	closeRead(Session session, Path file, long size, Set<PosixFilePermission> permissions, InputStream stream)	Called when the stream obtained from openRead is no longer required since data has been successfully copied.
default void	closeWrite(Session session, Path file, long size, Set<PosixFilePermission> permissions, OutputStream os)	Called when output stream obtained from openWrite is no longer needed since data copying has been successfully completed.
ScpSourceStreamResolver	createScpSourceStreamResolver(Session session, Path path)
ScpTargetStreamResolver	createScpTargetStreamResolver(Session session, Path path)
default BasicFileAttributes	getLocalBasicFileAttributes(Session session, Path path, LinkOption... options)
default Set<PosixFilePermission>	getLocalFilePermissions(Session session, Path path, LinkOption... options)
default DirectoryStream<Path>	getLocalFolderChildren(Session session, Path path)	Invoked when required to send all children of a local directory
default Iterable<Path>	getMatchingFilesToSend(Session session, Path basedir, String pattern)	Invoked when required to send a pattern of files
InputStream	openRead(Session session, Path file, long size, Set<PosixFilePermission> permissions, OpenOption... options)	Create an input stream to read from a file
OutputStream	openWrite(Session session, Path file, long size, Set<PosixFilePermission> permissions, OpenOption... options)	Create an output stream to write to a file
default Path	resolveIncomingFilePath(Session session, Path localPath, String name, boolean preserve, Set<PosixFilePermission> permissions, ScpTimestampCommandDetails time)	Invoked when receiving a new file to via a directory command
default Path	resolveIncomingReceiveLocation(Session session, Path path, boolean recursive, boolean shouldBeDir, boolean preserve)	Invoked when a request to receive something is processed
default Path	resolveLocalPath(Session session, FileSystem fileSystem, String commandPath)
default Path	resolveOutgoingFilePath(Session session, Path localPath, LinkOption... options)	Called when there is a candidate file/folder for sending
default boolean	sendAsDirectory(Session session, Path path, LinkOption... options)	Invoked on a local path in order to decide whether it should be sent as a file or as a directory
default boolean	sendAsRegularFile(Session session, Path path, LinkOption... options)	Invoked on a local path in order to decide whether it should be sent as a file or as a directory
static void	updateFileProperties(Path file, Set<PosixFilePermission> perms, ScpTimestampCommandDetails time)

Method Detail

resolveIncomingFilePath

default Path resolveIncomingFilePath(Session session,
                                     Path localPath,
                                     String name,
                                     boolean preserve,
                                     Set<PosixFilePermission> permissions,
                                     ScpTimestampCommandDetails time)
                              throws IOException

Invoked when receiving a new file to via a directory command

Parameters:

session - The client/server Session through which the transfer is being executed

localPath - The target local path

name - The target file name

preserve - Whether requested to preserve the permissions and timestamp

permissions - The requested file permissions

time - The requested ScpTimestampCommandDetails - may be null if nothing to update

Returns:

The actual target file path for the incoming file/directory

Throws:

IOException - If failed to resolve the file path

See Also:

updateFileProperties

getMatchingFilesToSend

default Iterable<Path> getMatchingFilesToSend(Session session,
                                              Path basedir,
                                              String pattern)
                                       throws IOException

Invoked when required to send a pattern of files

Parameters:

session - The client/server Session through which the transfer is being executed

basedir - The base directory - may be null/empty to indicate CWD

pattern - The required pattern - ignored if null/empty - returns empty result

Returns:

The matching relative paths of the children to send

Throws:

IOException - If failed to scan the directory

sendAsRegularFile

default boolean sendAsRegularFile(Session session,
                                  Path path,
                                  LinkOption... options)
                           throws IOException

Invoked on a local path in order to decide whether it should be sent as a file or as a directory

Parameters:

session - The client/server Session through which the transfer is being executed

path - The local Path

options - The LinkOption-s

Returns:

Whether to send the file as a regular one - Note: if false then the sendAsDirectory(Session, Path, LinkOption...) is consulted.

Throws:

IOException - If failed to decide

sendAsDirectory

default boolean sendAsDirectory(Session session,
                                Path path,
                                LinkOption... options)
                         throws IOException

Invoked on a local path in order to decide whether it should be sent as a file or as a directory

Parameters:

session - The client/server Session through which the transfer is being executed

path - The local Path

options - The LinkOption-s

Returns:

Whether to send the file as a directory - Note: if true then getLocalFolderChildren(Session, Path) is consulted

Throws:

IOException - If failed to decide

getLocalFolderChildren

default DirectoryStream<Path> getLocalFolderChildren(Session session,
                                                     Path path)
                                              throws IOException

Invoked when required to send all children of a local directory

Parameters:

session - The client/server Session through which the transfer is being executed

path - The local folder Path

Returns:

The DirectoryStream of children to send - Note: for each child the decision whether to send it as a file or a directory will be reached by consulting the respective sendAsRegularFile and sendAsDirectory methods

Throws:

IOException - If failed to provide the children stream

See Also:

sendAsDirectory

getLocalBasicFileAttributes

default BasicFileAttributes getLocalBasicFileAttributes(Session session,
                                                        Path path,
                                                        LinkOption... options)
                                                 throws IOException

Throws:

IOException

getLocalFilePermissions

default Set<PosixFilePermission> getLocalFilePermissions(Session session,
                                                         Path path,
                                                         LinkOption... options)
                                                  throws IOException

Throws:

IOException

resolveLocalPath

default Path resolveLocalPath(Session session,
                              FileSystem fileSystem,
                              String commandPath)
                       throws IOException,
                              InvalidPathException

Parameters:

session - The client/server Session through which the transfer is being executed

fileSystem - The local FileSystem on which local file should reside

commandPath - The command path using the local file separator

Returns:

The resolved absolute and normalized local Path

Throws:

IOException - If failed to resolve the path

InvalidPathException - If invalid local path value

resolveIncomingReceiveLocation

default Path resolveIncomingReceiveLocation(Session session,
                                            Path path,
                                            boolean recursive,
                                            boolean shouldBeDir,
                                            boolean preserve)
                                     throws IOException

Invoked when a request to receive something is processed

Parameters:

session - The client/server Session through which the transfer is being executed

path - The local target Path of the request

recursive - Whether the request is recursive

shouldBeDir - Whether target path is expected to be a directory

preserve - Whether target path is expected to preserve attributes (permissions, times)

Returns:

The effective target path - default=same as input

Throws:

IOException - If failed to resolve target location

resolveOutgoingFilePath

default Path resolveOutgoingFilePath(Session session,
                                     Path localPath,
                                     LinkOption... options)
                              throws IOException

Called when there is a candidate file/folder for sending

Parameters:

session - The client/server Session through which the transfer is being executed

localPath - The original file/folder Path for sending

options - The LinkOption-s to use for validation

Returns:

The effective outgoing file path (default=same as input)

Throws:

IOException - If failed to resolve

openRead

InputStream openRead(Session session,
                     Path file,
                     long size,
                     Set<PosixFilePermission> permissions,
                     OpenOption... options)
              throws IOException

Create an input stream to read from a file

Parameters:

session - The Session requesting the access

file - The requested local file Path

size - The expected transfer bytes count

permissions - The requested file permissions

options - The OpenOptions - may be null/empty

Returns:

The open InputStream never null

Throws:

IOException - If failed to open the file

closeRead

default void closeRead(Session session,
                       Path file,
                       long size,
                       Set<PosixFilePermission> permissions,
                       InputStream stream)
                throws IOException

Called when the stream obtained from openRead is no longer required since data has been successfully copied.

Parameters:

session - The Session requesting the access

file - The requested local file Path

size - The expected transfer bytes count

permissions - The requested file permissions

stream - The InputStream to close

Throws:

IOException - If failed to close the stream - Note: stream will be closed regardless of whether this method throws an exception or not.

createScpSourceStreamResolver

ScpSourceStreamResolver createScpSourceStreamResolver(Session session,
                                                      Path path)
                                               throws IOException

Throws:

IOException

openWrite

OutputStream openWrite(Session session,
                       Path file,
                       long size,
                       Set<PosixFilePermission> permissions,
                       OpenOption... options)
                throws IOException

Create an output stream to write to a file

Parameters:

session - The Session requesting the access

file - The requested local file Path

size - The expected transfer byte count

permissions - The requested file permissions

options - The OpenOptions - may be null/empty

Returns:

The open OutputStream never null

Throws:

IOException - If failed to open the file

closeWrite

default void closeWrite(Session session,
                        Path file,
                        long size,
                        Set<PosixFilePermission> permissions,
                        OutputStream os)
                 throws IOException

Called when output stream obtained from openWrite is no longer needed since data copying has been successfully completed.

Parameters:

session - The Session requesting the access

file - The requested local file Path

size - The expected transfer byte count

permissions - The requested file permissions

os - The opened OutputStream

Throws:

IOException - If failed to close the stream - Note: stream will be closed regardless of whether this method throws an exception or not.

createScpTargetStreamResolver

ScpTargetStreamResolver createScpTargetStreamResolver(Session session,
                                                      Path path)
                                               throws IOException

Throws:

IOException

updateFileProperties

static void updateFileProperties(Path file,
                                 Set<PosixFilePermission> perms,
                                 ScpTimestampCommandDetails time)
                          throws IOException

Throws:

IOException