com.github.robtimus.filesystems.sftp

Class SFTPEnvironment

java.lang.Object

com.github.robtimus.filesystems.sftp.SFTPEnvironment

All Implemented Interfaces:

Map<String,Object>

public class SFTPEnvironment
extends Object
implements Map<String,Object>

A utility class to set up environments that can be used in the FileSystemProvider.newFileSystem(URI, Map) and FileSystemProvider.newFileSystem(Path, Map) methods of SFTPFileSystemProvider.

Author:

Rob Spoor

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SFTPEnvironment.QueryParam Indicates which query parameters can be used to define environment values.
static interface	SFTPEnvironment.QueryParams A container for SFTPEnvironment.QueryParam annotations.

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
SFTPEnvironment() Creates a new SFTP environment.
SFTPEnvironment(Map<String,Object> map) Creates a new SFTP environment.

Method Summary

Modifier and Type	Method and Description
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
static SFTPEnvironment	copy(Map<String,?> env) Copies a map to create a new SFTPEnvironment instance.
Set<Map.Entry<String,Object>>	entrySet()
boolean	equals(Object o)
Object	get(Object key)
int	hashCode()
boolean	isEmpty()
Set<String>	keySet()
Object	put(String key, Object value)
void	putAll(Map<? extends String,? extends Object> m)
Object	remove(Object key)
static void	setDefault(SFTPEnvironment defaultEnvironment) Sets the default SFTP environment.
int	size()
String	toString()
Collection<Object>	values()
SFTPEnvironment	withAgentForwarding(boolean agentForwarding) Stores whether or not agent forwarding should be enabled.
SFTPEnvironment	withAppendedConfig(String key, String value) Stores a configuration option to use.
SFTPEnvironment	withAppendedConfig(String key, String value, BinaryOperator<String> appender) Stores a configuration option to use.
SFTPEnvironment	withClientVersion(String version) Stores the client version to use.
SFTPEnvironment	withConfig(Properties config) Stores configuration options to use.
SFTPEnvironment	withConfig(String key, String value) Stores a configuration option to use.
SFTPEnvironment	withConfigRepository(ConfigRepository repository) Stores the config repository to use.
SFTPEnvironment	withConnectTimeout(int timeout) Stores the connection timeout to use.
SFTPEnvironment	withDefaultDirectory(String pathname) Stores the default directory to use.
SFTPEnvironment	withFilenameEncoding(Charset encoding) Stores the filename encoding to use.
SFTPEnvironment	withFileSystemExceptionFactory(FileSystemExceptionFactory factory) Stores the file system exception factory to use.
SFTPEnvironment	withHostKeyAlias(String alias) Stores the host key alias to use.
SFTPEnvironment	withHostKeyRepository(HostKeyRepository repository) Stores the host key repository to use.
SFTPEnvironment	withIdentities(Collection<Identity> identities) Stores several identity to use.
SFTPEnvironment	withIdentities(Identity... identities) Stores several identity to use.
SFTPEnvironment	withIdentity(Identity identity) Stores an identity to use.
SFTPEnvironment	withIdentityRepository(IdentityRepository repository) Stores the identity repository to use.
SFTPEnvironment	withKnownHosts(File knownHosts) Stores the known hosts file to use.
SFTPEnvironment	withPassword(char[] password) Stores the password to use.
SFTPEnvironment	withPoolConfig(SFTPPoolConfig poolConfig) Stores the pool config to use.
SFTPEnvironment	withProxy(Proxy proxy) Stores the proxy to use.
SFTPEnvironment	withServerAliveCountMax(int count) Stores the maximum number of server alive messages that can be sent without any reply before disconnecting.
SFTPEnvironment	withServerAliveInterval(int interval) Stores the server alive interval to use.
SFTPEnvironment	withSocketFactory(SocketFactory factory) Stores the socket factory to use.
SFTPEnvironment	withTimeout(int timeout) Stores the timeout.
SFTPEnvironment	withUserInfo(UserInfo userInfo) Stores the user info to use.
SFTPEnvironment	withUsername(String username) Stores the username to use.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

SFTPEnvironment

public SFTPEnvironment()

Creates a new SFTP environment.

SFTPEnvironment

public SFTPEnvironment(Map<String,Object> map)

Creates a new SFTP environment.

Parameters:

map - The map to wrap.

Method Detail

withUsername

public SFTPEnvironment withUsername(String username)

Stores the username to use.

Parameters:

username - The username to use.

Returns:

This object.

withConnectTimeout

@SFTPEnvironment.QueryParam(value="connectTimeout")
public SFTPEnvironment withConnectTimeout(int timeout)

Stores the connection timeout to use.

Parameters:

timeout - The connection timeout in milliseconds.

Returns:

This object.

withProxy

public SFTPEnvironment withProxy(Proxy proxy)

Stores the proxy to use.

Parameters:

proxy - The proxy to use.

Returns:

This object.

withUserInfo

public SFTPEnvironment withUserInfo(UserInfo userInfo)

Stores the user info to use.

Parameters:

userInfo - The user info to use.

Returns:

This object.

withPassword

public SFTPEnvironment withPassword(char[] password)

Stores the password to use.

Parameters:

password - The password to use.

Returns:

This object.

Since:

1.1

withConfig

public SFTPEnvironment withConfig(Properties config)

Stores configuration options to use. This method will add not clear any previously set options, but only add new ones.

Parameters:

config - The configuration options to use.

Returns:

This object.

Throws:

NullPointerException - if the given properties object is null.

See Also:

withConfig(String, String)

withConfig

@SFTPEnvironment.QueryParam(value="config.<key>")
public SFTPEnvironment withConfig(String key,
                                                                                    String value)

Stores a configuration option to use. This method will add not clear any previously set options, but only add new ones.

Parameters:

key - The configuration key.

value - The configuration value.

Returns:

This object.

Throws:

NullPointerException - if the given key or value is null.

See Also:

withConfig(Properties)

withAppendedConfig

@SFTPEnvironment.QueryParam(value="appendedConfig.<key>")
public SFTPEnvironment withAppendedConfig(String key,
                                                                                                    String value)

Stores a configuration option to use. Unlike withConfig(String, String), configuration options set using this method will be appended to existing configuration options instead of overwriting them. For instance, this method can be used to add support for ssh-rsa keys as follows:

 // JSch way:
 // session.setConfig("server_host_key", session.getConfig("server_host_key") + ",ssh-rsa");
 // session.setConfig("PubkeyAcceptedAlgorithms", session.getConfig("PubkeyAcceptedAlgorithms") + ",ssh-rsa");

 // sftp-fs way:
 SFTPEnvironment env = new SFTPEnvironment()
         ...
         .withAppendedConfig("server_host_key", "ssh-rsa")
         .withAppendedConfig("PubkeyAcceptedAlgorithms", "ssh-rsa");
 

This method will use a comma to append configuration options. If this does not fit your needs, use withAppendedConfig(String, String, BinaryOperator) with a custom appender.

Parameters:

key - The configuration key.

value - The configuration value.

Returns:

This object.

Throws:

NullPointerException - If the given key or value is null.

Since:

3.2

withAppendedConfig

public SFTPEnvironment withAppendedConfig(String key,
                                          String value,
                                          BinaryOperator<String> appender)

Stores a configuration option to use. This is a more generalized version of withAppendedConfig(String, String) that allows non-default combining of existing and new configuration options.

Parameters:

key - The configuration key.

value - The configuration value.

appender - A function that takes the previously configured option and the new option and returns a combined configuration option.

Returns:

This object.

Throws:

NullPointerException - If the given key, value or appender function is null.

Since:

3.2

withSocketFactory

public SFTPEnvironment withSocketFactory(SocketFactory factory)

Stores the socket factory to use.

Parameters:

factory - The socket factory to use.

Returns:

This object.

withTimeout

@SFTPEnvironment.QueryParam(value="timeout")
public SFTPEnvironment withTimeout(int timeout)

Stores the timeout.

Parameters:

timeout - The timeout in milliseconds.

Returns:

This object.

See Also:

Socket.setSoTimeout(int)

withClientVersion

@SFTPEnvironment.QueryParam(value="clientVersion")
public SFTPEnvironment withClientVersion(String version)

Stores the client version to use.

Parameters:

version - The client version.

Returns:

This object.

withHostKeyAlias

@SFTPEnvironment.QueryParam(value="hostKeyAlias")
public SFTPEnvironment withHostKeyAlias(String alias)

Stores the host key alias to use.

Parameters:

alias - The host key alias.

Returns:

This object.

withServerAliveInterval

@SFTPEnvironment.QueryParam(value="serverAliveInterval")
public SFTPEnvironment withServerAliveInterval(int interval)

Stores the server alive interval to use.

Parameters:

interval - The server alive interval in milliseconds.

Returns:

This object.

withServerAliveCountMax

@SFTPEnvironment.QueryParam(value="serverAliveCountMax")
public SFTPEnvironment withServerAliveCountMax(int count)

Stores the maximum number of server alive messages that can be sent without any reply before disconnecting.

Parameters:

count - The maximum number of server alive messages.

Returns:

This object.

withIdentityRepository

public SFTPEnvironment withIdentityRepository(IdentityRepository repository)

Stores the identity repository to use.

Parameters:

repository - The identity repository to use.

Returns:

This object.

withIdentity

public SFTPEnvironment withIdentity(Identity identity)

Stores an identity to use. This method will add not clear any previously set identities, but only add new ones.

Parameters:

identity - The identity to use.

Returns:

This object.

Throws:

NullPointerException - If the given identity is null.

Since:

1.2

See Also:

withIdentities(Identity...), withIdentities(Collection)

withIdentities

public SFTPEnvironment withIdentities(Identity... identities)

Stores several identity to use. This method will add not clear any previously set identities, but only add new ones.

Parameters:

identities - The identities to use.

Returns:

This object.

Throws:

NullPointerException - If any of the given identity is null.

Since:

1.2

See Also:

withIdentity(Identity), withIdentities(Collection)

withIdentities

public SFTPEnvironment withIdentities(Collection<Identity> identities)

Stores several identity to use. This method will add not clear any previously set identities, but only add new ones.

Parameters:

identities - The identities to use.

Returns:

This object.

Throws:

NullPointerException - If any of the given identity is null.

Since:

1.2

See Also:

withIdentity(Identity), withIdentities(Identity...)

withHostKeyRepository

public SFTPEnvironment withHostKeyRepository(HostKeyRepository repository)

Stores the host key repository to use.

Parameters:

repository - The host key repository to use.

Returns:

This object.

withKnownHosts

public SFTPEnvironment withKnownHosts(File knownHosts)

Stores the known hosts file to use. Note that the known hosts file is ignored if a HostKeyRepository is set with a non-null value.

Parameters:

knownHosts - The known hosts file to use.

Returns:

This object.

Throws:

NullPointerException - If the given file is null.

Since:

1.2

See Also:

withHostKeyRepository(HostKeyRepository)

withConfigRepository

public SFTPEnvironment withConfigRepository(ConfigRepository repository)

Stores the config repository to use.

Parameters:

repository - The config repository to use.

Returns:

This object.

Since:

3.1

withAgentForwarding

@SFTPEnvironment.QueryParam(value="agentForwarding")
public SFTPEnvironment withAgentForwarding(boolean agentForwarding)

Stores whether or not agent forwarding should be enabled.

Parameters:

agentForwarding - true to enable strict agent forwarding, or false to disable it.

Returns:

This object.

withFilenameEncoding

@SFTPEnvironment.QueryParam(value="filenameEncoding")
public SFTPEnvironment withFilenameEncoding(Charset encoding)

Stores the filename encoding to use.

Parameters:

encoding - The filename encoding to use.

Returns:

This object.

withDefaultDirectory

@SFTPEnvironment.QueryParam(value="defaultDir")
public SFTPEnvironment withDefaultDirectory(String pathname)

Stores the default directory to use. If it exists, this will be the directory that relative paths are resolved to.

Parameters:

pathname - The default directory to use.

Returns:

This object.

withPoolConfig

@SFTPEnvironment.QueryParam(value="poolConfig.maxWaitTime") @SFTPEnvironment.QueryParam(value="poolConfig.maxIdleTime") @SFTPEnvironment.QueryParam(value="poolConfig.initialSize") @SFTPEnvironment.QueryParam(value="poolConfig.maxSize")
public SFTPEnvironment withPoolConfig(SFTPPoolConfig poolConfig)

Stores the pool config to use.

The maximum pool size influences the number of concurrent threads that can access an SFTP file system.
If the maximum wait time is negative, SFTP file systems wait indefinitely until a client connection is available. This is the default setting if no pool config is defined.

Parameters:

poolConfig - The pool config to use.

Returns:

This object.

Since:

3.0

withFileSystemExceptionFactory

public SFTPEnvironment withFileSystemExceptionFactory(FileSystemExceptionFactory factory)

Stores the file system exception factory to use.

Parameters:

factory - The file system exception factory to use.

Returns:

This object.

size

public int size()

Specified by:

size in interface Map<String,Object>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<String,Object>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<String,Object>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<String,Object>

get

public Object get(Object key)

Specified by:

get in interface Map<String,Object>

put

public Object put(String key,
                  Object value)

Specified by:

put in interface Map<String,Object>

remove

public Object remove(Object key)

Specified by:

remove in interface Map<String,Object>

putAll

public void putAll(Map<? extends String,? extends Object> m)

Specified by:

putAll in interface Map<String,Object>

clear

public void clear()

Specified by:

clear in interface Map<String,Object>

keySet

public Set<String> keySet()

Specified by:

keySet in interface Map<String,Object>

values

public Collection<Object> values()

Specified by:

values in interface Map<String,Object>

entrySet

public Set<Map.Entry<String,Object>> entrySet()

Specified by:

entrySet in interface Map<String,Object>

equals

public boolean equals(Object o)

Specified by:

equals in interface Map<String,Object>

Overrides:

equals in class Object

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<String,Object>

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

copy

public static SFTPEnvironment copy(Map<String,?> env)

Copies a map to create a new SFTPEnvironment instance.

Parameters:

env - The map to copy. It can be an SFTPEnvironment instance, but does not have to be.

Returns:

A new SFTPEnvironment instance that is a copy of the given map.

Since:

3.0

setDefault

public static void setDefault(SFTPEnvironment defaultEnvironment)

Sets the default SFTP environment. This is used in SFTPFileSystemProvider.getPath(URI) when a file system needs to be created, since no environment can be passed. This way, certain settings like pool configuration can still be applied.

Parameters:

defaultEnvironment - The default SFTP environment. Use null to reset it to an empty environment.

Since:

3.3