Package org.apache.commons.net.ftp

# Class FTPListParseEngine

java.lang.Object
org.apache.commons.net.ftp.FTPListParseEngine

public class FTPListParseEngine extends Object
This class handles the entire process of parsing a listing of file entries from the server.

This object defines a two-part parsing mechanism.

The first part consists of reading the raw input into an internal list of strings. Every item in this list corresponds to an actual file. All extraneous matter emitted by the server will have been removed by the end of this phase. This is accomplished in conjunction with the FTPFileEntryParser associated with this engine, by calling its methods `readNextEntry()` - which handles the issue of what delimits one entry from another, usually but not always a line feed and `preParse()` - which handles removal of extraneous matter such as the preliminary lines of a listing, removal of duplicates on versioning systems, etc.

The second part is composed of the actual parsing, again in conjunction with the particular parser used by this engine. This is controlled by an iterator over the internal list of strings. This may be done either in block mode, by calling the `getNext()` and `getPrevious()` methods to provide "paged" output of less than the whole list at one time, or by calling the `getFiles()` method to return the entire list.

Examples:

Paged access:

     FTPClient f = FTPClient();
     f.connect(server);
     f.login(user, password);
     FTPListParseEngine engine = f.initiateListParsing(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.
     }

For unpaged access, simply use FTPClient.listFiles(). That method uses this class transparently.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FTPListParseEngine(FTPFileEntryParser parser)`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<FTPFile>`
  `getFileList(FTPFileFilter filter)`
  Gets a list of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.
  `FTPFile[]`
  `getFiles()`
  Gets an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.
  `FTPFile[]`
  `getFiles(FTPFileFilter filter)`
  Gets an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.
  `FTPFile[]`
  `getNext(int quantityRequested)`
  Gets an array of at most `quantityRequested` FTPFile objects starting at this object's internal iterator's current position.
  `FTPFile[]`
  `getPrevious(int quantityRequested)`
  Gets an array of at most `quantityRequested` FTPFile objects starting at this object's internal iterator's current position, and working back toward the beginning.
  `boolean`
  `hasNext()`
  convenience method to allow clients to know whether this object's internal iterator's current position is at the end of the list.
  `boolean`
  `hasPrevious()`
  convenience method to allow clients to know whether this object's internal iterator's current position is at the beginning of the list.
  `void`
  `readServerList(InputStream inputStream)`
  Deprecated.
  use `readServerList(InputStream, String)` instead
  `void`
  `readServerList(InputStream inputStream, String charsetName)`
  Reads (and closes) the initial reading and preparsing of the list returned by the server.
  `void`
  `resetIterator()`
  resets this object's internal iterator to the beginning of the list.

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

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

- ## Constructor Details

  - ### FTPListParseEngine

    public FTPListParseEngine(FTPFileEntryParser parser)
    Constructs a new instance.
    Parameters:
      `parser` - How to parse file entries.

- ## Method Details

  - ### getFileList

    public List<FTPFile> getFileList(FTPFileFilter filter)
    Gets a list of FTPFile objects containing the whole list of files returned by the server as read by this object's parser. The files are filtered before being added to the array.
    Parameters:
      `filter` - FTPFileFilter, must not be `null`.
    Returns:
      a list of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.

      NOTE: This array may contain null members if any of the individual file listings failed to parse. The caller should check each entry for null before referencing it, or use a filter such as `FTPFileFilters.NON_NULL` which does not allow null entries.

    Since:
      3.9.0

  - ### getFiles

    public FTPFile[] getFiles() throws IOException
    Gets an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.
    Returns:
      an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser. None of the entries will be null
    Throws:
      `IOException` - - not ever thrown, may be removed in a later release

  - ### getFiles

    public FTPFile[] getFiles(FTPFileFilter filter) throws IOException
    Gets an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser. The files are filtered before being added to the array.
    Parameters:
      `filter` - FTPFileFilter, must not be `null`.
    Returns:
      an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.

      NOTE: This array may contain null members if any of the individual file listings failed to parse. The caller should check each entry for null before referencing it, or use a filter such as `FTPFileFilters.NON_NULL` which does not allow null entries.

    Throws:
      `IOException` - - not ever thrown, may be removed in a later release
    Since:
      2.2

  - ### getNext

    public FTPFile[] getNext(int quantityRequested)
    Gets an array of at most `quantityRequested` FTPFile objects starting at this object's internal iterator's current position. If fewer than `quantityRequested` such elements are available, the returned array will have a length equal to the number of entries at and after the current position. If no such entries are found, this array will have a length of 0. After this method is called this object's internal iterator is advanced by a number of positions equal to the size of the array returned.
    Parameters:
      `quantityRequested` - the maximum number of entries we want to get.
    Returns:
      an array of at most `quantityRequested` FTPFile objects starting at the current position of this iterator within its list and at least the number of elements which exist in the list at and after its current position.

      NOTE: This array may contain null members if any of the individual file listings failed to parse. The caller should check each entry for null before referencing it.

  - ### getPrevious

    public FTPFile[] getPrevious(int quantityRequested)
    Gets an array of at most `quantityRequested` FTPFile objects starting at this object's internal iterator's current position, and working back toward the beginning. If fewer than `quantityRequested` such elements are available, the returned array will have a length equal to the number of entries at and after the current position. If no such entries are found, this array will have a length of 0. After this method is called this object's internal iterator is moved back by a number of positions equal to the size of the array returned.
    Parameters:
      `quantityRequested` - the maximum number of entries we want to get.
    Returns:
      an array of at most `quantityRequested` FTPFile objects starting at the current position of this iterator within its list and at least the number of elements which exist in the list at and after its current position. This array will be in the same order as the underlying list (not reversed).

      NOTE: This array may contain null members if any of the individual file listings failed to parse. The caller should check each entry for null before referencing it.

  - ### hasNext

    public boolean hasNext()
    convenience method to allow clients to know whether this object's internal iterator's current position is at the end of the list.
    Returns:
      true if internal iterator is not at end of list, false otherwise.

  - ### hasPrevious

    public boolean hasPrevious()
    convenience method to allow clients to know whether this object's internal iterator's current position is at the beginning of the list.
    Returns:
      true if internal iterator is not at beginning of list, false otherwise.

  - ### readServerList

    @Deprecated public void readServerList(InputStream inputStream) throws IOException
    Deprecated.
    use `readServerList(InputStream, String)` instead
    Do not use.
    Parameters:
      `inputStream` - the stream from which to read
    Throws:
      `IOException` - on error

  - ### readServerList

    public void readServerList(InputStream inputStream, String charsetName) throws IOException
    Reads (and closes) the initial reading and preparsing of the list returned by the server. After this method has completed, this object will contain a list of unparsed entries (Strings) each referring to a unique file on the server.
    Parameters:
      `inputStream` - input stream provided by the server socket.
      `charsetName` - the encoding to be used for reading the stream
    Throws:
      `IOException` - thrown on any failure to read from the sever.

  - ### resetIterator

    public void resetIterator()
    resets this object's internal iterator to the beginning of the list.