[NET] "Proposal" section added to main stem

[Steve Cohen <SC...@sportvision.com>]

I have checked in code implementing the new FTPFileEntryParser system, that has been knocking around for close to a year.  This code basically allows an iterable list of ftp entries to created from which more expensive FTPFile objects are not created until they are needed.  It also checks in a number of regular-expression based parsers that implement this system.  This code, in a slightly different form, used to be found in 

//jakarta-commons/net/ftp/ftp2

and then later in

//jakarta-commons/net/proposal/ftp2

but now it is moved to 

//jakarta-commons/net/ftp.

This version is totally backward-compatible with the older system as were the earlier versions.   It is also well-integrated with the older system, which earlier versions were not.  That is to say that both are supported.  

In the old system, after calls to log into the server

f=FTPClient();
f.connect(server)
f.login(username, password);

a list of files might be obtained by calling
f.listFiles(directory);

This will produce an array of FTPFile objects for the entire contents of directory which might get to be prohibitively large when scanning a large directory.

In the new system, it works like this:

f=FTPClient();
f.connect(server)
f.login(username, password);
FTPFileList list = createFTPFileList(directory, parser);
FTPFileIterator iter = list.iterator();

while (iter.hasNext()) {
    FTPFile[] files = iter.getNext(25);  // or whatever "page size" you want

    //do whatever you want with these files, display them, etc.
}

Unresolved issue:
There has been an issue raised with this system that it doesn't work on systems such as OpenVMS which sometimes send FTP entries that span line feeds.  This has not yet been fixed, but a means for fixing it has been implemented in this set of changes.  The FTPFileEntryParser interface now has this method:

    public String readNextEntry(BufferedReader reader) throws IOException;

This method is now called instead of BufferedReader.readLine() to get individual entries.  The default implementation simply delegates this call to BufferedReader.readLine().  Overriding this method in the VMSFTPEntryParser class to do the correct thing will solve this problem.

Steve Cohen
scohen@apache.org