com.github.robtimus.filesystems.ftp

Class FTPEnvironment

java.lang.Object

com.github.robtimus.filesystems.ftp.FTPEnvironment

All Implemented Interfaces:

Map<String,Object>

Direct Known Subclasses:

FTPSEnvironment

public class FTPEnvironment
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 FTPFileSystemProvider.

Author:

Rob Spoor

Nested Class Summary

Nested Classes

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

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

Map.Entry<K,V>

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
static FTPEnvironment	copy(Map<String,?> env) Copies a map to create a new FTPEnvironment 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(FTPEnvironment defaultEnvironment) Sets the default FTP environment.
int	size()
String	toString()
Collection<Object>	values()
FTPEnvironment	withActiveExternalIPAddress(String ipAddress) Stores the external IP address in active mode.
FTPEnvironment	withActivePortRange(int minPort, int maxPort) Stores the client side port range in active mode.
FTPEnvironment	withAutodetectEncoding(boolean autodetect) Stores whether or not automatic server encoding detection should be enabled.
FTPEnvironment	withBufferSize(int bufferSize) Stores the buffer size to use.
FTPEnvironment	withCharset(Charset charset) Stores the charset to use.
FTPEnvironment	withClientConfig(FTPClientConfig clientConfig) Stores the FTP client config to use.
FTPEnvironment	withConnectionMode(ConnectionMode connectionMode) Stores the connection mode to use.
FTPEnvironment	withConnectTimeout(int timeout) Stores the connection timeout to use.
FTPEnvironment	withControlEncoding(String encoding) Stores the character encoding to be used by the FTP control connection.
FTPEnvironment	withControlKeepAliveReplyTimeout(Duration timeout) Stores how long to wait for control keep-alive message replies.
FTPEnvironment	withControlKeepAliveReplyTimeout(int timeout) Deprecated. Use withControlKeepAliveReplyTimeout(Duration) instead.
FTPEnvironment	withControlKeepAliveTimeout(Duration timeout) Stores the time to wait between sending control connection keep-alive messages when processing file upload or download.
FTPEnvironment	withControlKeepAliveTimeout(long timeout) Deprecated. Use withControlKeepAliveTimeout(Duration) instead.
FTPEnvironment	withCredentials(String username, char[] password) Stores the credentials to use.
FTPEnvironment	withCredentials(String username, char[] password, String account) Stores the credentials to use.
FTPEnvironment	withDataTimeout(Duration timeout) Stores the timeout to use when reading from data connections.
FTPEnvironment	withDataTimeout(int timeout) Deprecated. Use withDataTimeout(Duration) instead.
FTPEnvironment	withDefaultDirectory(String pathname) Stores the default directory to use.
FTPEnvironment	withFileSystemExceptionFactory(FileSystemExceptionFactory factory) Stores the file system exception factory to use.
FTPEnvironment	withFTPFileStrategyFactory(FTPFileStrategyFactory factory) Stores the FTP file strategy factory to use.
FTPEnvironment	withIpAddressFromPasvResponse(boolean usingIpAddressFromPasvResponse) Sets whether or not the IP address from the server's response should be used.
FTPEnvironment	withKeepAlive(boolean keepAlive) Stores whether or not SO_KEEPALIVE should be enabled.
FTPEnvironment	withListHiddenFiles(boolean listHiddenFiles) Stores whether or not to list hidden files.
FTPEnvironment	withLocalAddress(InetAddress localAddr, int localPort) Stores the local address to use.
FTPEnvironment	withParserFactory(FTPFileEntryParserFactory parserFactory) Stores the factory used for parser creation.
FTPEnvironment	withPassiveLocalIPAddress(String ipAddress) Stores the local IP address to use in passive mode.
FTPEnvironment	withPassiveNatWorkaroundStrategy(FTPClient.HostnameResolver resolver) Stores the workaround strategy to replace the PASV mode reply addresses.
FTPEnvironment	withPoolConfig(FTPPoolConfig poolConfig) Stores the pool config to use.
FTPEnvironment	withProxy(Proxy proxy) Stores the proxy to use.
FTPEnvironment	withReceiveBufferSize(int size) Stores the socket receive buffer size to use.
FTPEnvironment	withReceiveDataSocketBufferSize(int bufferSize) Stores the value to use for the data socket SO_RCVBUF option.
FTPEnvironment	withRemoteVerificationEnabled(boolean enabled) Stores whether or not verification that the remote host taking part of a data connection is the same as the host to which the control connection is attached should be enabled.
FTPEnvironment	withReportActiveExternalIPAddress(String ipAddress) Stores the external IP address to report in EPRT/PORT commands in active mode.
FTPEnvironment	withSendBufferSize(int size) Stores the socket send buffer size to use.
FTPEnvironment	withSendDataSocketBufferSize(int bufferSizr) Stores the value to use for the data socket SO_SNDBUF option.
FTPEnvironment	withServerSocketFactory(ServerSocketFactory factory) Stores the server socket factory to use.
FTPEnvironment	withSocketFactory(SocketFactory factory) Stores the socket factory to use.
FTPEnvironment	withSoLinger(boolean on, int linger) Stores whether or not SO_LINGER should be enabled, and if so, the linger time.
FTPEnvironment	withSoTimeout(int timeout) Stores the socket timeout.
FTPEnvironment	withStrictMultilineParsing(boolean strictMultilineParsing) Stores whether or not strict multiline parsing should be enabled, as per RFC 959, section 4.2.
FTPEnvironment	withTcpNoDelay(boolean on) Stores whether or not the Nagle's algorithm (TCP_NODELAY) should be enabled.
FTPEnvironment	withUseEPSVwithIPv4(boolean selected) Stores whether or not to use EPSV with IPv4.

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

FTPEnvironment

public FTPEnvironment()

Creates a new FTP environment.

FTPEnvironment

public FTPEnvironment(Map<String,Object> map)

Creates a new FTP environment.

Parameters:

map - The map to wrap.

Method Detail

withLocalAddress

@FTPEnvironment.QueryParam(value="localAddr") @FTPEnvironment.QueryParam(value="localPort")
public FTPEnvironment withLocalAddress(InetAddress localAddr,
                                                                                                                                   int localPort)

Stores the local address to use.

Parameters:

localAddr - The local address to use.

localPort - The local port to use.

Returns:

This object.

See Also:

Socket.bind(SocketAddress), InetSocketAddress(InetAddress, int)

withCredentials

public FTPEnvironment withCredentials(String username,
                                      char[] password)

Stores the credentials to use.

Parameters:

username - The username to use.

password - The password to use.

Returns:

This object.

withCredentials

@FTPEnvironment.QueryParam(value="account")
public FTPEnvironment withCredentials(String username,
                                                                                  char[] password,
                                                                                  String account)

Stores the credentials to use.

Parameters:

username - The username to use.

password - The password to use.

account - The account to use.

Returns:

This object.

withSoTimeout

@FTPEnvironment.QueryParam(value="soTimeout")
public FTPEnvironment withSoTimeout(int timeout)

Stores the socket timeout.

Parameters:

timeout - The socket timeout in milliseconds.

Returns:

This object.

See Also:

Socket.setSoTimeout(int)

withSendBufferSize

@FTPEnvironment.QueryParam(value="sendBufferSize")
public FTPEnvironment withSendBufferSize(int size)

Stores the socket send buffer size to use.

Parameters:

size - The size of the buffer in bytes.

Returns:

This object.

See Also:

Socket.setSendBufferSize(int)

withReceiveBufferSize

@FTPEnvironment.QueryParam(value="receiveBufferSize")
public FTPEnvironment withReceiveBufferSize(int size)

Stores the socket receive buffer size to use.

Parameters:

size - The size of the buffer in bytes.

Returns:

This object.

See Also:

Socket.setReceiveBufferSize(int)

withTcpNoDelay

@FTPEnvironment.QueryParam(value="tcpNoDelay")
public FTPEnvironment withTcpNoDelay(boolean on)

Stores whether or not the Nagle's algorithm (TCP_NODELAY) should be enabled.

Parameters:

on - true if Nagle's algorithm should be enabled, or false otherwise.

Returns:

This object.

See Also:

Socket.setTcpNoDelay(boolean)

withKeepAlive

@FTPEnvironment.QueryParam(value="keepAlive")
public FTPEnvironment withKeepAlive(boolean keepAlive)

Stores whether or not SO_KEEPALIVE should be enabled.

Parameters:

keepAlive - true if keep-alive should be enabled, or false otherwise.

Returns:

This object.

See Also:

Socket.setKeepAlive(boolean)

withSoLinger

@FTPEnvironment.QueryParam(value="soLinger.on") @FTPEnvironment.QueryParam(value="soLinger.val")
public FTPEnvironment withSoLinger(boolean on,
                                                                                                                                    int linger)

Stores whether or not SO_LINGER should be enabled, and if so, the linger time.

Parameters:

on - true if SO_LINGER should be enabled, or false otherwise.

linger - The linger time in seconds, if on is true.

Returns:

This object.

See Also:

Socket.setSoLinger(boolean, int)

withSocketFactory

public FTPEnvironment withSocketFactory(SocketFactory factory)

Stores the socket factory to use.

Parameters:

factory - The socket factory to use.

Returns:

This object.

withServerSocketFactory

public FTPEnvironment withServerSocketFactory(ServerSocketFactory factory)

Stores the server socket factory to use.

Parameters:

factory - The server socket factory to use.

Returns:

This object.

withConnectTimeout

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

Stores the connection timeout to use.

Parameters:

timeout - The connection timeout in milliseconds.

Returns:

This object.

See Also:

Socket.connect(SocketAddress, int)

withProxy

public FTPEnvironment withProxy(Proxy proxy)

Stores the proxy to use.

Parameters:

proxy - The proxy to use.

Returns:

This object.

withCharset

@FTPEnvironment.QueryParam(value="charset")
public FTPEnvironment withCharset(Charset charset)

Stores the charset to use.

Parameters:

charset - The charset to use.

Returns:

This object.

withControlEncoding

@FTPEnvironment.QueryParam(value="controlEncoding")
public FTPEnvironment withControlEncoding(String encoding)

Stores the character encoding to be used by the FTP control connection. Some FTP servers require that commands be issued in a non-ASCII encoding like UTF-8 so that filenames with multi-byte character representations (e.g, Big 8) can be specified.

Parameters:

encoding - The character encoding to use.

Returns:

This object.

withStrictMultilineParsing

@FTPEnvironment.QueryParam(value="strictMultilineParsing")
public FTPEnvironment withStrictMultilineParsing(boolean strictMultilineParsing)

Stores whether or not strict multiline parsing should be enabled, as per RFC 959, section 4.2.

Parameters:

strictMultilineParsing - true to enable strict multiline parsing, or false to disable it.

Returns:

This object.

Since:

2.1

withDataTimeout

@Deprecated
public FTPEnvironment withDataTimeout(int timeout)

Deprecated. Use withDataTimeout(Duration) instead.

Stores the timeout in milliseconds to use when reading from data connections.

Parameters:

timeout - The timeout in milliseconds that is used when opening data connection sockets.

Returns:

This object.

withDataTimeout

@FTPEnvironment.QueryParam(value="dataTimeout")
public FTPEnvironment withDataTimeout(Duration timeout)

Stores the timeout to use when reading from data connections.

Parameters:

timeout - The timeout in milliseconds that is used when opening data connection sockets.

Returns:

This object.

Since:

3.1

withParserFactory

public FTPEnvironment withParserFactory(FTPFileEntryParserFactory parserFactory)

Stores the factory used for parser creation.

Parameters:

parserFactory - The factory object used to create FTPFileEntryParsers

Returns:

This object.

withIpAddressFromPasvResponse

@FTPEnvironment.QueryParam(value="ipAddressFromPasvResponse")
public FTPEnvironment withIpAddressFromPasvResponse(boolean usingIpAddressFromPasvResponse)

Sets whether or not the IP address from the server's response should be used. Before version 3.1 (and version 3.9.0 of Apache Commons Net), this has always been the case. Beginning with version 3.1, that IP address will be silently ignored, and replaced with the remote IP address of the control connection, unless this configuration option is given, which restores the old behavior. To enable this by default, use the system property FTPClient.FTP_IP_ADDRESS_FROM_PASV_RESPONSE.

Parameters:

usingIpAddressFromPasvResponse - true if the IP address from the server's response should be used, or false to ignore that IP address.

Returns:

This object.

Since:

3.1

withRemoteVerificationEnabled

@FTPEnvironment.QueryParam(value="remoteVerificationEnabled")
public FTPEnvironment withRemoteVerificationEnabled(boolean enabled)

Stores whether or not verification that the remote host taking part of a data connection is the same as the host to which the control connection is attached should be enabled.

Parameters:

enabled - true to enable verification, or false to disable verification.

Returns:

This object.

withDefaultDirectory

@FTPEnvironment.QueryParam(value="defaultDir")
public FTPEnvironment 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.

withConnectionMode

@FTPEnvironment.QueryParam(value="connectionMode")
public FTPEnvironment withConnectionMode(ConnectionMode connectionMode)

Stores the connection mode to use. If the connection mode is not set, it will default to ConnectionMode.ACTIVE.

Parameters:

connectionMode - The connection mode to use.

Returns:

This object.

withActivePortRange

@FTPEnvironment.QueryParam(value="activePortRange.min") @FTPEnvironment.QueryParam(value="activePortRange.max")
public FTPEnvironment withActivePortRange(int minPort,
                                                                                                                                                          int maxPort)

Stores the client side port range in active mode.

Parameters:

minPort - The lowest available port (inclusive).

maxPort - The highest available port (inclusive).

Returns:

This object.

withActiveExternalIPAddress

@FTPEnvironment.QueryParam(value="activeExternalIPAddress")
public FTPEnvironment withActiveExternalIPAddress(String ipAddress)

Stores the external IP address in active mode. Useful when there are multiple network cards.

Parameters:

ipAddress - The external IP address of this machine.

Returns:

This object.

withPassiveLocalIPAddress

@FTPEnvironment.QueryParam(value="passiveLocalIPAddress")
public FTPEnvironment withPassiveLocalIPAddress(String ipAddress)

Stores the local IP address to use in passive mode. Useful when there are multiple network cards.

Parameters:

ipAddress - The local IP address of this machine.

Returns:

This object.

withReportActiveExternalIPAddress

@FTPEnvironment.QueryParam(value="reportActiveExternalIPAddress")
public FTPEnvironment withReportActiveExternalIPAddress(String ipAddress)

Stores the external IP address to report in EPRT/PORT commands in active mode. Useful when there are multiple network cards.

Parameters:

ipAddress - The external IP address of this machine.

Returns:

This object.

withBufferSize

@FTPEnvironment.QueryParam(value="bufferSize")
public FTPEnvironment withBufferSize(int bufferSize)

Stores the buffer size to use.

Parameters:

bufferSize - The buffer size to use.

Returns:

This object.

withSendDataSocketBufferSize

@FTPEnvironment.QueryParam(value="sendDataSocketBufferSize")
public FTPEnvironment withSendDataSocketBufferSize(int bufferSizr)

Stores the value to use for the data socket SO_SNDBUF option.

Parameters:

bufferSizr - The size of the buffer.

Returns:

This object.

withReceiveDataSocketBufferSize

@FTPEnvironment.QueryParam(value="receiveDataSocketBufferSize")
public FTPEnvironment withReceiveDataSocketBufferSize(int bufferSize)

Stores the value to use for the data socket SO_RCVBUF option.

Parameters:

bufferSize - The size of the buffer.

Returns:

This object.

withClientConfig

public FTPEnvironment withClientConfig(FTPClientConfig clientConfig)

Stores the FTP client config to use.

Parameters:

clientConfig - The client config to use.

Returns:

This object.

withUseEPSVwithIPv4

@FTPEnvironment.QueryParam(value="useEPSVwithIPv4")
public FTPEnvironment withUseEPSVwithIPv4(boolean selected)

Stores whether or not to use EPSV with IPv4. Might be worth enabling in some circumstances.

For example, when using IPv4 with NAT it may work with some rare configurations. E.g. if FTP server has a static PASV address (external network) and the client is coming from another internal network. In that case the data connection after PASV command would fail, while EPSV would make the client succeed by taking just the port.

Parameters:

selected - The flag to use.

Returns:

This object.

withControlKeepAliveTimeout

@Deprecated
public FTPEnvironment withControlKeepAliveTimeout(long timeout)

Deprecated. Use withControlKeepAliveTimeout(Duration) instead.

Stores the time to wait between sending control connection keep-alive messages when processing file upload or download.

Parameters:

timeout - The keep-alive timeout to use, in milliseconds.

Returns:

This object.

withControlKeepAliveTimeout

@FTPEnvironment.QueryParam(value="controlKeepAliveTimeout")
public FTPEnvironment withControlKeepAliveTimeout(Duration timeout)

Stores the time to wait between sending control connection keep-alive messages when processing file upload or download.

Parameters:

timeout - The keep-alive timeout to use.

Returns:

This object.

Since:

3.1

withControlKeepAliveReplyTimeout

@Deprecated
public FTPEnvironment withControlKeepAliveReplyTimeout(int timeout)

Deprecated. Use withControlKeepAliveReplyTimeout(Duration) instead.

Stores how long to wait for control keep-alive message replies.

Parameters:

timeout - The keep-alive reply timeout to use, in milliseconds.

Returns:

This object.

withControlKeepAliveReplyTimeout

@FTPEnvironment.QueryParam(value="controlKeepAliveReplyTimeout")
public FTPEnvironment withControlKeepAliveReplyTimeout(Duration timeout)

Stores how long to wait for control keep-alive message replies.

Parameters:

timeout - The keep-alive reply timeout to use.

Returns:

This object.

Since:

3.1

withPassiveNatWorkaroundStrategy

public FTPEnvironment withPassiveNatWorkaroundStrategy(FTPClient.HostnameResolver resolver)

Stores the workaround strategy to replace the PASV mode reply addresses. This gets around the problem that some NAT boxes may change the reply. The default implementation is FTPClient.NatServerResolverImpl, i.e. site-local replies are replaced.

Parameters:

resolver - The workaround strategy to replace internal IP's in passive mode, or null to disable the workaround (i.e. use PASV mode reply address.)

Returns:

This object.

Since:

1.1

withAutodetectEncoding

@FTPEnvironment.QueryParam(value="autodetectEncoding")
public FTPEnvironment withAutodetectEncoding(boolean autodetect)

Stores whether or not automatic server encoding detection should be enabled. Note that only UTF-8 is supported.

Parameters:

autodetect - true to enable automatic server encoding detection, or false to disable it.

Returns:

This object.

withListHiddenFiles

@FTPEnvironment.QueryParam(value="listHiddenFiles")
public FTPEnvironment withListHiddenFiles(boolean listHiddenFiles)

Stores whether or not to list hidden files. If this flag is not set, it will default to true.

Note that if this flag is set to false, the current directory will (most likely) not be returned when listing directories. That means that StandardFTPFileStrategyFactory.UNIX will not work correctly.

Ideally, only set this flag (to false) if the FTP server does not support the -a option for LIST commands.

Parameters:

listHiddenFiles - true to list hidden files, or false to omit them.

Returns:

This object.

Since:

2.0

withPoolConfig

@FTPEnvironment.QueryParam(value="poolConfig.maxWaitTime") @FTPEnvironment.QueryParam(value="poolConfig.maxIdleTime") @FTPEnvironment.QueryParam(value="poolConfig.initialSize") @FTPEnvironment.QueryParam(value="poolConfig.maxSize")
public FTPEnvironment withPoolConfig(FTPPoolConfig poolConfig)

Stores the pool config to use.

The maximum pool size influences the number of concurrent threads that can access an FTP file system.
If the maximum wait time is negative, FTP 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 FTPEnvironment withFileSystemExceptionFactory(FileSystemExceptionFactory factory)

Stores the file system exception factory to use.

Parameters:

factory - The file system exception factory to use.

Returns:

This object.

withFTPFileStrategyFactory

public FTPEnvironment withFTPFileStrategyFactory(FTPFileStrategyFactory factory)

Stores the FTP file strategy factory to use. If the FTP file strategy factory is not set, it will default to StandardFTPFileStrategyFactory.AUTO_DETECT.

Parameters:

factory - The FTP file strategy 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 FTPEnvironment copy(Map<String,?> env)

Copies a map to create a new FTPEnvironment instance. If the given map is an instance of FTPSEnvironment, this method will return a new FTPSEnvironment instance.

Parameters:

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

Returns:

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

Since:

3.0

setDefault

public static void setDefault(FTPEnvironment defaultEnvironment)

Sets the default FTP environment. This is used in FTPFileSystemProvider.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 FTP environment. Use null to reset it to an empty environment.

Since:

3.2