org.apache.commons.net.ftp
Class FTPFileIterator

java.lang.Object
  |
  +--org.apache.commons.net.ftp.FTPFileIterator

public class FTPFileIterator
extends java.lang.Object

FTPFileIterator.java This class implements a bidirectional iterator over an FTPFileList. Elements may be retrieved one at at time using the hasNext() - next() syntax familiar from Java 2 collections. Alternatively, entries may be receieved as an array of any requested number of entries or all of them.

Version:
$Id: FTPFileIterator.java,v 1.4 2003/03/06 12:38:42 scohen Exp $
Author:
Steve Cohen
See Also:
FTPFileList, FTPFileEntryParser

Field Summary
private static int DIREMPTY
          constant shorthand for the situation where the raw listing has been scanned and found to have no valid entry.
private static FTPFile[] EMPTY
          shorthand for an empty return value.
private  int firstGoodEntry
          number within rawlines of the first valid file entry.
private  int itemptr
          this iterator's current position within rawlines.
private  FTPFileEntryParser parser
          the parser to which this iterator delegates its parsing duties
private  java.util.Vector rawlines
          a vector of strings, each representing a possibly valid ftp file entry
private static int UNINIT
          constant shorthand for the situation where the raw listing has not yet been scanned
 
Constructor Summary
(package private) FTPFileIterator(FTPFileList rawlist)
          "Package-private" constructor.
(package private) FTPFileIterator(FTPFileList rawlist, FTPFileEntryParser parser)
          "Package-private" constructor.
 
Method Summary
 FTPFile[] getFiles()
          Returns a list of FTPFile objects for ALL files listed in the server's LIST output.
private  int getFirstGoodEntry()
          Skips over any introductory lines and stuff in the listing that does not represent files, returning the line number of the first entry that does represent a file.
 FTPFile[] getNext(int quantityRequested)
          Returns an array of at most quantityRequested FTPFile objects starting at this iterator's current position within its associated list.
 FTPFile[] getPrevious(int quantityRequested)
          Returns an array of at most quantityRequested FTPFile objects starting at the position preceding this iterator's current position within its associated list.
 boolean hasNext()
          Method for determining whether getNext() will successfully return a non-null value.
 boolean hasPrevious()
          Method for determining whether getPrevious() will successfully return a non-null value.
private  void init()
          resets iterator to the beginning of the list.
 FTPFile next()
          Returns a single parsed FTPFile object corresponding to the raw input line at this iterator's current position.
private  FTPFile parseFTPEntry(java.lang.String entry)
          Delegates to this object's parser member the job of parsing an entry.
 FTPFile previous()
          Returns a single parsed FTPFile object corresponding to the raw input line at the position preceding that of the internal iterator over the list of raw lines maintained by this object After this method is called the internal iterator is retreated by one element (unless it is already at beginning of list).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

rawlines

private java.util.Vector rawlines
a vector of strings, each representing a possibly valid ftp file entry


parser

private FTPFileEntryParser parser
the parser to which this iterator delegates its parsing duties


UNINIT

private static final int UNINIT
constant shorthand for the situation where the raw listing has not yet been scanned

See Also:
Constant Field Values

DIREMPTY

private static final int DIREMPTY
constant shorthand for the situation where the raw listing has been scanned and found to have no valid entry.

See Also:
Constant Field Values

itemptr

private int itemptr
this iterator's current position within rawlines.


firstGoodEntry

private int firstGoodEntry
number within rawlines of the first valid file entry.


EMPTY

private static final FTPFile[] EMPTY
shorthand for an empty return value.

Constructor Detail

FTPFileIterator

FTPFileIterator(FTPFileList rawlist)
"Package-private" constructor. Only the FTPFileList can create an iterator, using it's iterator() method. The list will be iterated with the list's default parser.

Parameters:
rawlist - the FTPFileList to be iterated

FTPFileIterator

FTPFileIterator(FTPFileList rawlist,
                FTPFileEntryParser parser)
"Package-private" constructor. Only the FTPFileList can create an iterator, using it's iterator() method. The list will be iterated with a supplied parser

Parameters:
rawlist - the FTPFileList to be iterated
parser - the system specific parser for raw FTP entries.
Method Detail

parseFTPEntry

private FTPFile parseFTPEntry(java.lang.String entry)
Delegates to this object's parser member the job of parsing an entry.

Parameters:
entry - A string containing one entry, as determined by the parser's getNextEntry() method.
Returns:
an FTPFile object representing this entry or null if it can't be parsed as a file

getFirstGoodEntry

private int getFirstGoodEntry()
Skips over any introductory lines and stuff in the listing that does not represent files, returning the line number of the first entry that does represent a file.

Returns:
the line number within rawlines of the first good entry in the array or DIREMPTY if there are no good entries.

init

private void init()
resets iterator to the beginning of the list.


getFiles

public FTPFile[] getFiles()
Returns a list of FTPFile objects for ALL files listed in the server's LIST output.

Returns:
a list of FTPFile objects for ALL files listed in the server's LIST output.

getNext

public FTPFile[] getNext(int quantityRequested)
Returns an array of at most quantityRequested FTPFile objects starting at this iterator's current position within its associated list. If fewer than quantityRequested such elements are available, the returned array will have a length equal to the number of entries at and after after the current position. If no such entries are found, this array will have a length of 0. After this method is called the current position is advanced by either quantityRequested or the number of entries available after the iterator, whichever is fewer.

Parameters:
quantityRequested - the maximum number of entries we want to get. A 0 passed here is a signal to get ALL the entries.
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.

hasNext

public boolean hasNext()
Method for determining whether getNext() will successfully return a non-null value.

Returns:
true if there exist any files after the one currently pointed to by the internal iterator, false otherwise.

next

public FTPFile next()
Returns a single parsed FTPFile object corresponding to the raw input line at this iterator's current position. After this method is called the internal iterator is advanced by one element (unless already at end of list).

Returns:
a single FTPFile object corresponding to the raw input line at the position of the internal iterator over the list of raw input lines maintained by this object or null if no such object exists.

getPrevious

public FTPFile[] getPrevious(int quantityRequested)
Returns an array of at most quantityRequested FTPFile objects starting at the position preceding this iterator's current position within its associated list. If fewer than quantityRequested such elements are available, the returned array will have a length equal to the number of entries after the iterator. If no such entries are found, this array will have a length of 0. The entries will be ordered in the same order as the list, not reversed. After this method is called the current position is moved back by either quantityRequested or the number of entries available before the current position, whichever is fewer.

Parameters:
quantityRequested - the maximum number of entries we want to get. A 0 passed here is a signal to get ALL the entries.
Returns:
an array of at most quantityRequested FTPFile objects starting at the position preceding the current position of this iterator within its list and at least the number of elements which exist in the list prior to its current position.

hasPrevious

public boolean hasPrevious()
Method for determining whether getPrevious() will successfully return a non-null value.

Returns:
true if there exist any files before the one currently pointed to by the internal iterator, false otherwise.

previous

public FTPFile previous()
Returns a single parsed FTPFile object corresponding to the raw input line at the position preceding that of the internal iterator over the list of raw lines maintained by this object After this method is called the internal iterator is retreated by one element (unless it is already at beginning of list).

Returns:
a single FTPFile object corresponding to the raw input line at the position immediately preceding that of the internal iterator over the list of raw input lines maintained by this object.