FileDocCategorySizeDatePackage
FTPListParseEngine.javaAPI DocApache Commons NET 1.4.1 API10989Sat Dec 03 10:05:48 GMT 2005org.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 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.

version
$Id: FTPListParseEngine.java 155429 2005-02-26 13:13:04Z dirkv $

Fields Summary
private List
entries
private ListIterator
_internalIterator
FTPFileEntryParser
parser
Constructors Summary
public FTPListParseEngine(FTPFileEntryParser parser)


       
        this.parser = parser;
    
Methods Summary
public FTPFile[]getFiles()
Returns an array of FTPFile objects containing the whole list of files returned by the server as read by this object's parser.

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

exception
IOException

        List tmpResults = new LinkedList();
        Iterator iter = this.entries.iterator();
        while (iter.hasNext()) {
            String entry = (String) iter.next();
            FTPFile temp = this.parser.parseFTPEntry(entry);
            tmpResults.add(temp);
        }
        return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);

    
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.

param
quantityRequested the maximum number of entries we want to get.
return
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.

        List tmpResults = new LinkedList();
        int count = quantityRequested;
        while (count > 0 && this._internalIterator.hasNext()) {
            String entry = (String) this._internalIterator.next();
            FTPFile temp = this.parser.parseFTPEntry(entry);
            tmpResults.add(temp);
            count--;
        }
        return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);

    
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.

param
quantityRequested the maximum number of entries we want to get.
return
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.

        List tmpResults = new LinkedList();
        int count = quantityRequested;
        while (count > 0 && this._internalIterator.hasPrevious()) {
            String entry = (String) this._internalIterator.previous();
            FTPFile temp = this.parser.parseFTPEntry(entry);
            tmpResults.add(0,temp);
            count--;
        }
        return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
    
public booleanhasNext()
convenience method to allow clients to know whether this object's internal iterator's current position is at the end of the list.

return
true if internal iterator is not at end of list, false otherwise.

        return _internalIterator.hasNext();
    
public booleanhasPrevious()
convenience method to allow clients to know whether this object's internal iterator's current position is at the beginning of the list.

return
true if internal iterator is not at beginning of list, false otherwise.

        return _internalIterator.hasPrevious();
    
public voidreadServerList(java.io.InputStream stream, java.lang.String encoding)
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.

param
stream input stream provided by the server socket.
exception
IOException thrown on any failure to read from the sever.

        this.entries = new LinkedList();
        readStream(stream, encoding);
        this.parser.preParse(this.entries);
        resetIterator();
    
public voidreadServerList(java.io.InputStream stream)
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.

param
stream input stream provided by the server socket.
exception
IOException thrown on any failure to read from the sever.
deprecated
The version of this method which takes an encoding should be used.

		readServerList(stream, null);
	
private voidreadStream(java.io.InputStream stream, java.lang.String encoding)
Internal method for reading the input into the entries list. After this method has completed, entries will contain a collection of entries (as defined by FTPFileEntryParser.readNextEntry()), but this may contain various non-entry preliminary lines from the server output, duplicates, and other data that will not be part of the final listing.

param
stream The socket stream on which the input will be read.
param
encoding The encoding to use.
exception
IOException thrown on any failure to read the stream

    	BufferedReader reader;
    	if (encoding == null)
    	{
    		reader = new BufferedReader(new InputStreamReader(stream));
    	}
    	else
    	{
    		reader = new BufferedReader(new InputStreamReader(stream, encoding));
    	}
    	
        String line = this.parser.readNextEntry(reader);

        while (line != null)
        {
            this.entries.add(line);
            line = this.parser.readNextEntry(reader);
        }
        reader.close();
    
public voidresetIterator()
resets this object's internal iterator to the beginning of the list.

        this._internalIterator = this.entries.listIterator();