org.apache.commons.net.ftp

## Class FTPClientConfig

- java.lang.Object
- - org.apache.commons.net.ftp.FTPClientConfig

-     public class FTPClientConfig
      extends Object

  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 time zone 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(user, 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(user, 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í|jún|júl|ágú|sep|okt|nóv|des");
       f.configure(conf);
       f.connect(server);
       f.login(user, 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(user, 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(user, password);
       FTPFile[] files = listFiles(directory);

  See Also:
    `Configurable`, `FTPClient`, `FTPTimestampParserImpl.configure(FTPClientConfig)`, `ConfigurableFTPFileEntryParserImpl`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SYST_AS400` Identifier by which an AS/400-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_L8` Some servers return an "UNKNOWN Type: L8" message in response to the SYST command.
    `static String` | `SYST_MACOS_PETER` Identifier by which a Mac pre OS-X -based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_MVS` Identifier by which an MVS-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_NETWARE` Identifier by which a Netware-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_NT` Identifier by which a WindowsNT-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_OS2` Identifier by which an OS/2-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_OS400` Identifier by which an OS/400-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_UNIX` Identifier by which a Unix-based ftp server is known throughout the commons-net ftp system.
    `static String` | `SYST_UNIX_TRIM_LEADING` Identifier for alternate Unix parser; same as `SYST_UNIX` but leading spaces are trimmed from file names.
    `static String` | `SYST_VMS` Identifier by which a vms-based ftp server is known throughout the commons-net ftp system.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FTPClientConfig()` Convenience constructor mainly for use in testing.
    `FTPClientConfig(FTPClientConfig config)` Copy constructor
    `FTPClientConfig(String systemKey)` The main constructor for an FTPClientConfig object
    `FTPClientConfig(String systemKey, FTPClientConfig config)`
    `FTPClientConfig(String systemKey, String defaultDateFormatStr, String recentDateFormatStr)` Constructor which allows setting of the format string member fields
    `FTPClientConfig(String systemKey, String defaultDateFormatStr, String recentDateFormatStr, String serverLanguageCode, String shortMonthNames, String serverTimeZoneId)` Constructor which allows setting of most member fields
    `FTPClientConfig(String systemKey, String defaultDateFormatStr, String recentDateFormatStr, String serverLanguageCode, String shortMonthNames, String serverTimeZoneId, boolean lenientFutureDates, boolean saveUnparseableEntries)` Constructor which allows setting of all member fields

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static DateFormatSymbols` | `getDateFormatSymbols(String shortmonths)` Gets a DateFormatSymbols object configured with short month names as in the supplied string
    `String` | `getDefaultDateFormatStr()` Gets the `defaultDateFormatStr` property.
    `String` | `getRecentDateFormatStr()` Gets the `recentDateFormatStr` property.
    `String` | `getServerLanguageCode()` Gets the `serverLanguageCode` property.
    `String` | `getServerSystemKey()` Gets the serverSystemKey property.
    `String` | `getServerTimeZoneId()` Gets the `serverTimeZoneId` property.
    `String` | `getShortMonthNames()` Gets the `shortMonthNames` property.
    `static Collection<String>` | `getSupportedLanguageCodes()` Gets a Collection of all the language codes currently supported by this class.
    `boolean` | `getUnparseableEntries()` Gets whether parsing a list should return FTPFile entries even for unparseable response lines
    `boolean` | `isLenientFutureDates()` Tests whether the `lenientFutureDates` property.
    `static DateFormatSymbols` | `lookupDateFormatSymbols(String languageCode)` Looks up the supplied language code in the internally maintained table of language codes.
    `void` | `setDefaultDateFormatStr(String defaultDateFormatStr)` Sets the defaultDateFormatStr property.
    `void` | `setLenientFutureDates(boolean lenientFutureDates)` Sets the lenientFutureDates property.
    `void` | `setRecentDateFormatStr(String recentDateFormatStr)` Sets the recentDateFormatStr property.
    `void` | `setServerLanguageCode(String serverLanguageCode)` Sets the serverLanguageCode property.
    `void` | `setServerTimeZoneId(String serverTimeZoneId)` Sets the serverTimeZoneId property.
    `void` | `setShortMonthNames(String shortMonthNames)` Sets the shortMonthNames property.
    `void` | `setUnparseableEntries(boolean saveUnparseableEntries)` Sets list parsing methods to create basic FTPFile entries if parsing fails.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SYST_AS400

          public static final String SYST_AS400

      Identifier by which an AS/400-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_L8

          public static final String SYST_L8

      Some servers return an "UNKNOWN Type: L8" message in response to the SYST command. We set these to be a Unix-type system. This may happen if the ftpd in question was compiled without system information. NET-230 - Updated to be UPPERCASE so that the check done in createFileEntryParser will succeed.
      See Also:
        Constant Field Values

    - #### SYST_MACOS_PETER

          public static final String SYST_MACOS_PETER

      Identifier by which a Mac pre OS-X -based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_MVS

          public static final String SYST_MVS

      Identifier by which an MVS-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_NETWARE

          public static final String SYST_NETWARE

      Identifier by which a Netware-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_NT

          public static final String SYST_NT

      Identifier by which a WindowsNT-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_OS2

          public static final String SYST_OS2

      Identifier by which an OS/2-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_OS400

          public static final String SYST_OS400

      Identifier by which an OS/400-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_UNIX

          public static final String SYST_UNIX

      Identifier by which a Unix-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

    - #### SYST_UNIX_TRIM_LEADING

          public static final String SYST_UNIX_TRIM_LEADING

      Identifier for alternate Unix parser; same as `SYST_UNIX` but leading spaces are trimmed from file names. This is to maintain backwards compatibility with the original behavior of the parser which ignored multiple spaces between the date and the start of the file name.
      See Also:
        Constant Field Values

    - #### SYST_VMS

          public static final String SYST_VMS

      Identifier by which a vms-based ftp server is known throughout the commons-net ftp system.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FTPClientConfig

          public FTPClientConfig()

      Convenience constructor mainly for use in testing. Constructs a Unix configuration.

    - #### FTPClientConfig

          public FTPClientConfig(FTPClientConfig config)

      Copy constructor
      Parameters:
        `config` - source

    - #### FTPClientConfig

          public FTPClientConfig(String systemKey)

      The main constructor for an FTPClientConfig object
      Parameters:
        `systemKey` - key representing system type of the server being connected to. See `serverSystemKey` If set to the empty string, then FTPClient uses the system type returned by the server. However, this is not recommended for general use; the correct system type should be set if it is known.

    - #### FTPClientConfig

          FTPClientConfig(String systemKey,
                          FTPClientConfig config)

    - #### FTPClientConfig

          public FTPClientConfig(String systemKey,
                                 String defaultDateFormatStr,
                                 String recentDateFormatStr)

      Constructor which allows setting of the format string member fields
      Parameters:
        `systemKey` - key representing system type of the server being connected to. See `serverSystemKey`
        `defaultDateFormatStr` - See `defaultDateFormatStr`
        `recentDateFormatStr` - See `recentDateFormatStr`

    - #### FTPClientConfig

          public FTPClientConfig(String systemKey,
                                 String defaultDateFormatStr,
                                 String recentDateFormatStr,
                                 String serverLanguageCode,
                                 String shortMonthNames,
                                 String serverTimeZoneId)

      Constructor which allows setting of most member fields
      Parameters:
        `systemKey` - key representing system type of the server being connected to. See `serverSystemKey`
        `defaultDateFormatStr` - See `defaultDateFormatStr`
        `recentDateFormatStr` - See `recentDateFormatStr`
        `serverLanguageCode` - See `serverLanguageCode`
        `shortMonthNames` - See `shortMonthNames`
        `serverTimeZoneId` - See `serverTimeZoneId`

    - #### FTPClientConfig

          public FTPClientConfig(String systemKey,
                                 String defaultDateFormatStr,
                                 String recentDateFormatStr,
                                 String serverLanguageCode,
                                 String shortMonthNames,
                                 String serverTimeZoneId,
                                 boolean lenientFutureDates,
                                 boolean saveUnparseableEntries)

      Constructor which allows setting of all member fields
      Parameters:
        `systemKey` - key representing system type of the server being connected to. See `serverSystemKey`
        `defaultDateFormatStr` - See `defaultDateFormatStr`
        `recentDateFormatStr` - See `recentDateFormatStr`
        `serverLanguageCode` - See `serverLanguageCode`
        `shortMonthNames` - See `shortMonthNames`
        `serverTimeZoneId` - See `serverTimeZoneId`
        `lenientFutureDates` - See `lenientFutureDates`
        `saveUnparseableEntries` - See `saveUnparseableEntries`

  - ### Method Detail

    - #### getDateFormatSymbols

          public static DateFormatSymbols getDateFormatSymbols(String shortmonths)

      Gets a DateFormatSymbols object configured with short month names as in the supplied string
      Parameters:
        `shortmonths` - This should be as described in `shortMonthNames`
      Returns:
        a DateFormatSymbols object configured with short month names as in the supplied string

    - #### getDefaultDateFormatStr

          public String getDefaultDateFormatStr()

      Gets the `defaultDateFormatStr` property.
      Returns:
        the defaultDateFormatStr property.

    - #### getRecentDateFormatStr

          public String getRecentDateFormatStr()

      Gets the `recentDateFormatStr` property.
      Returns:
        the recentDateFormatStr property.

    - #### getServerLanguageCode

          public String getServerLanguageCode()

      Gets the `serverLanguageCode` property.
      Returns:
        the serverLanguageCode property.

    - #### getServerSystemKey

          public String getServerSystemKey()

      Gets 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()

      Gets the `serverTimeZoneId` property.
      Returns:
        the serverTimeZoneId property.

    - #### getShortMonthNames

          public String getShortMonthNames()

      Gets the `shortMonthNames` property.
      Returns:
        the shortMonthNames.

    - #### getSupportedLanguageCodes

          public static Collection<String> getSupportedLanguageCodes()

      Gets a Collection of all the language codes currently supported by this class. See `serverLanguageCode` for a functional description of language codes within this system.
      Returns:
        a Collection of all the language codes currently supported by this class

    - #### getUnparseableEntries

          public boolean getUnparseableEntries()

      Gets whether parsing a list should return FTPFile entries even for unparseable response lines

      If true, the FTPFile for any unparseable entries will contain only the unparsed entry `FTPFile.getRawListing()` and `FTPFile.isValid()` will return `false`

      Returns:
        true if list parsing should return FTPFile entries even for unparseable response lines

    - #### isLenientFutureDates

          public boolean isLenientFutureDates()

      Tests whether the `lenientFutureDates` property.
      Returns:
        the lenientFutureDates (default true).

    - #### 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`
      Parameters:
        `languageCode` - See `serverLanguageCode`
      Returns:
        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)

      Sets 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.

      Parameters:
        `defaultDateFormatStr` - The defaultDateFormatStr to set.

    - #### setLenientFutureDates

          public void setLenientFutureDates(boolean lenientFutureDates)

      Sets the lenientFutureDates property. This boolean property (default: true) only has meaning when a `recentDateFormatStr` property has been set. In that case, if this property is set true, then the parser, when it encounters a listing parseable with the recent date format, will only consider a date to belong to the previous year if it is more than one day in the future. This will allow all out-of-synch situations (whether based on "slop" - i.e. servers simply out of synch with one another or because of time zone differences - but in the latter case it is highly recommended to use the `serverTimeZoneId` property instead) to resolve correctly.

      This is used primarily in unix-based systems.

      Parameters:
        `lenientFutureDates` - set true to compensate for out-of-synch conditions.

    - #### setRecentDateFormatStr

          public void setRecentDateFormatStr(String recentDateFormatStr)

      Sets 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`.

      Parameters:
        `recentDateFormatStr` - The recentDateFormatStr to set.

    - #### setServerLanguageCode

          public void setServerLanguageCode(String serverLanguageCode)

      Sets 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 constructed 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 Apache 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.

      Parameters:
        `serverLanguageCode` - The value to set to the serverLanguageCode property.

    - #### setServerTimeZoneId

          public void setServerTimeZoneId(String serverTimeZoneId)

      Sets 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`.

      Parameters:
        `serverTimeZoneId` - The serverTimeZoneId to set.

    - #### setShortMonthNames

          public void setShortMonthNames(String shortMonthNames)

      Sets 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&#xED;|j&#xFA;n|j&#xFA;l|&#xE1;g&#xFA;|sep|okt|n&#xF3;v|des"`.

      Parameters:
        `shortMonthNames` - The value to set to the shortMonthNames property.

    - #### setUnparseableEntries

          public void setUnparseableEntries(boolean saveUnparseableEntries)

      Sets list parsing methods to create basic FTPFile entries if parsing fails.

      In this case, the FTPFile will contain only the unparsed entry `FTPFile.getRawListing()` and `FTPFile.isValid()` will return `false`

      Parameters:
        `saveUnparseableEntries` - if true, then create FTPFile entries if parsing fails