This class implements an alternate means of configuring the
FTPClient
object and
also subordinate objects which it uses. Any class implementing the
Configurable
interface can be configured by this object.
In particular this class was designed primarily to support configuration
of FTP servers which express file timestamps in formats and languages
other than those for the US locale, which although it is the most common
is not universal. Unfortunately, nothing in the FTP spec allows this to
be determined in an automated way, so manual configuration such as this
is necessary.
This functionality was designed to allow existing clients to work exactly
as before without requiring use of this component. This component should
only need to be explicitly invoked by the user of this package for problem
cases that previous implementations could not solve.
Examples of use of FTPClientConfig
Use cases:
You are trying to access a server that
- lists files with timestamps that use month names in languages other
than English
- lists files with timestamps that use date formats other
than the American English "standard"
MM dd yyyy
- is in different timezone and you need accurate timestamps for
dependency checking as in Ant
Unpaged (whole list) access on a UNIX server that uses French month names
but uses the "standard"
MMM d yyyy
date formatting
FTPClient f=FTPClient();
FTPClientConfig conf = new FTPClientConfig(FTPClientConfig.SYST_UNIX);
conf.setServerLanguageCode("fr");
f.configure(conf);
f.connect(server);
f.login(username, password);
FTPFile[] files = listFiles(directory);
Paged access on a UNIX server that uses Danish month names
and "European" date formatting in Denmark's time zone, when you
are in some other time zone.
FTPClient f=FTPClient();
FTPClientConfig conf = new FTPClientConfig(FTPClientConfig.SYST_UNIX);
conf.setServerLanguageCode("da");
conf.setDefaultDateFormat("d MMM yyyy");
conf.setRecentDateFormat("d MMM HH:mm");
conf.setTimeZoneId("Europe/Copenhagen");
f.configure(conf);
f.connect(server);
f.login(username, password);
FTPListParseEngine engine =
f.initiateListParsing("com.whatever.YourOwnParser", directory);
while (engine.hasNext()) {
FTPFile[] files = engine.getNext(25); // "page size" you want
//do whatever you want with these files, display them, etc.
//expensive FTPFile objects not created until needed.
}
Unpaged (whole list) access on a VMS server that uses month names
in a language not
supported
by the system.
but uses the "standard"
MMM d yyyy
date formatting
FTPClient f=FTPClient();
FTPClientConfig conf = new FTPClientConfig(FTPClientConfig.SYST_VMS);
conf.setShortMonthNames(
"jan|feb|mar|apr|ma\u00ED|j\u00FAn|j\u00FAl|\u00e1g\u00FA|sep|okt|n\u00F3v|des");
f.configure(conf);
f.connect(server);
f.login(username, password);
FTPFile[] files = listFiles(directory);
Unpaged (whole list) access on a Windows-NT server in a different time zone.
(Note, since the NT Format uses numeric date formatting, language issues
are irrelevant here).
FTPClient f=FTPClient();
FTPClientConfig conf = new FTPClientConfig(FTPClientConfig.SYST_NT);
conf.setTimeZoneId("America/Denver");
f.configure(conf);
f.connect(server);
f.login(username, password);
FTPFile[] files = listFiles(directory);
Unpaged (whole list) access on a Windows-NT server in a different time zone
but which has been configured to use a unix-style listing format.
FTPClient f=FTPClient();
FTPClientConfig conf = new FTPClientConfig(FTPClientConfig.SYST_UNIX);
conf.setTimeZoneId("America/Denver");
f.configure(conf);
f.connect(server);
f.login(username, password);
FTPFile[] files = listFiles(directory);
getDateFormatSymbols
public static DateFormatSymbols getDateFormatSymbols(String shortmonths)
Returns a DateFormatSymbols object configured with short month names
as in the supplied string
- a DateFormatSymbols object configured with short month names
as in the supplied string
getDefaultDateFormatStr
public String getDefaultDateFormatStr()
- Returns the defaultDateFormatStr property.
getRecentDateFormatStr
public String getRecentDateFormatStr()
- Returns the recentDateFormatStr property.
getServerLanguageCode
public String getServerLanguageCode()
getter for the
serverLanguageCode
property.
* @return Returns the serverLanguageCode property.
getServerSystemKey
public String getServerSystemKey()
Getter for the serverSystemKey property. This property
specifies the general type of server to which the client connects.
Should be either one of the FTPClientConfig.SYST_*
codes
or else the fully qualified class name of a parser implementing both
the FTPFileEntryParser
and Configurable
interfaces.
- Returns the serverSystemKey property.
getServerTimeZoneId
public String getServerTimeZoneId()
- Returns the serverTimeZoneId property.
getShortMonthNames
public String getShortMonthNames()
- Returns the shortMonthNames.
getSupportedLanguageCodes
public static Collection getSupportedLanguageCodes()
Returns a Collection of all the language codes currently supported
by this class. See
serverLanguageCode
for a functional descrption of language codes within this system.
- a Collection of all the language codes currently supported
by this class
lookupDateFormatSymbols
public static DateFormatSymbols lookupDateFormatSymbols(String languageCode)
Looks up the supplied language code in the internally maintained table of
language codes. Returns a DateFormatSymbols object configured with
short month names corresponding to the code. If there is no corresponding
entry in the table, the object returned will be that for
Locale.US
- a DateFormatSymbols object configured with short month names
corresponding to the supplied code, or with month names for
Locale.US
if there is no corresponding entry in the internal
table.
setDefaultDateFormatStr
public void setDefaultDateFormatStr(String defaultDateFormatStr)
setter for the defaultDateFormatStr property. This property
specifies the main date format that will be used by a parser configured
by this configuration to parse file timestamps. If this is not
specified, such a parser will use as a default value, the most commonly
used format which will be in as used in
en_US
locales.
This should be in the format described for
java.text.SimpleDateFormat
.
property.
defaultDateFormatStr
- The defaultDateFormatStr to set.
setRecentDateFormatStr
public void setRecentDateFormatStr(String recentDateFormatStr)
setter for the recentDateFormatStr property. This property
specifies a secondary date format that will be used by a parser
configured by this configuration to parse file timestamps, typically
those less than a year old. If this is not specified, such a parser
will not attempt to parse using an alternate format.
This is used primarily in unix-based systems.
This should be in the format described for
java.text.SimpleDateFormat
.
recentDateFormatStr
- The recentDateFormatStr to set.
setServerLanguageCode
public void setServerLanguageCode(String serverLanguageCode)
setter for the serverLanguageCode property. This property allows
user to specify a
two-letter ISO-639 language code that will be used to
configure the set of month names used by the file timestamp parser.
If neither this nor the
shortMonthNames
is specified, parsing will assume English month names, which may or
may not be significant, depending on whether the date format(s)
specified via
defaultDateFormatStr
and/or
recentDateFormatStr
are using
numeric or alphabetic month names.
If the code supplied is not supported here,
en_US
month names will be used. We are supporting here those language
codes which, when a
java.util.Locale
is constucted
using it, and a
java.text.SimpleDateFormat
is
constructed using that Locale, the array returned by the
SimpleDateFormat's
getShortMonths()
method consists
solely of three 8-bit ASCII character strings. Additionally,
languages which do not meet this requirement are included if a
common alternative set of short month names is known to be used.
This means that users who can tell us of additional such encodings
may get them added to the list of supported languages by contacting
the jakarta-commons-net team.
Please note that this attribute will NOT be used to determine a
locale-based date format for the language.
Experience has shown that many if not most FTP servers outside the
United States employ the standard
en_US
date format
orderings of
MMM d yyyy
and
MMM d HH:mm
and attempting to deduce this automatically here would cause more
problems than it would solve. The date format must be changed
via the
defaultDateFormatStr
and/or
recentDateFormatStr
parameters.
serverLanguageCode
- The value to set to the serverLanguageCode property.
setServerTimeZoneId
public void setServerTimeZoneId(String serverTimeZoneId)
setter for the serverTimeZoneId property. This property
allows a time zone to be specified corresponding to that known to be
used by an FTP server in file listings. This might be particularly
useful to clients such as Ant that try to use these timestamps for
dependency checking.
This should be one of the identifiers used by
java.util.TimeZone
to refer to time zones, for example,
America/Chicago
or
Asia/Rangoon
.
serverTimeZoneId
- The serverTimeZoneId to set.
setShortMonthNames
public void setShortMonthNames(String shortMonthNames)
setter for the shortMonthNames property.
This property allows the user to specify a set of month names
used by the server that is different from those that may be
specified using the
serverLanguageCode
property.
This should be a string containing twelve strings each composed of
three characters, delimited by pipe (|) characters. Currently,
only 8-bit ASCII characters are known to be supported. For example,
a set of month names used by a hypothetical Icelandic FTP server might
conceivably be specified as
"jan|feb|mar|apr|maí|jún|júl|ágú|sep|okt|nóv|des"
.
shortMonthNames
- The value to set to the shortMonthNames property.