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 is comprised 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(username, 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.
getFiles
public FTPFile[] getFiles()
throws IOException
Returns an array of FTPFile objects containing the whole list of
files returned by the server as read by this object's parser.
- 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.
getNext
public FTPFile[] getNext(int quantityRequested)
Returns 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 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.
quantityRequested
- the maximum number of entries we want to get.
- 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)
Returns 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 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.
quantityRequested
- the maximum number of entries we want to get.
- 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.
- 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.
- true if internal iterator is not at beginning of list, false
otherwise.
readServerList
public void readServerList(InputStream stream)
throws IOException
The version of this method which takes an encoding should be used.
handle the iniitial 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.
stream
- input stream provided by the server socket.
readServerList
public void readServerList(InputStream stream,
String encoding)
throws IOException
handle the iniitial 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.
stream
- input stream provided by the server socket.
resetIterator
public void resetIterator()
resets this object's internal iterator to the beginning of the list.