001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    package org.apache.commons.net.ftp;
019    
020    import java.io.BufferedReader;
021    import java.io.IOException;
022    import java.io.InputStream;
023    import java.io.InputStreamReader;
024    import java.util.Iterator;
025    import java.util.LinkedList;
026    import java.util.List;
027    import java.util.ListIterator;
028    
029    
030    /**
031     * This class handles the entire process of parsing a listing of
032     * file entries from the server.
033     * <p>
034     * This object defines a two-part parsing mechanism.
035     * <p>
036     * The first part is comprised of reading the raw input into an internal
037     * list of strings.  Every item in this list corresponds to an actual
038     * file.  All extraneous matter emitted by the server will have been
039     * removed by the end of this phase.  This is accomplished in conjunction
040     * with the FTPFileEntryParser associated with this engine, by calling
041     * its methods <code>readNextEntry()</code> - which handles the issue of
042     * what delimits one entry from another, usually but not always a line
043     * feed and <code>preParse()</code> - which handles removal of
044     * extraneous matter such as the preliminary lines of a listing, removal
045     * of duplicates on versioning systems, etc.
046     * <p>
047     * The second part is composed of the actual parsing, again in conjunction
048     * with the particular parser used by this engine.  This is controlled
049     * by an iterator over the internal list of strings.  This may be done
050     * either in block mode, by calling the <code>getNext()</code> and
051     * <code>getPrevious()</code> methods to provide "paged" output of less
052     * than the whole list at one time, or by calling the
053     * <code>getFiles()</code> method to return the entire list.
054     * <p>
055     * Examples:
056     * <p>
057     * Paged access:
058     * <pre>
059     *    FTPClient f=FTPClient();
060     *    f.connect(server);
061     *    f.login(username, password);
062     *    FTPListParseEngine engine = f.initiateListParsing(directory);
063     *
064     *    while (engine.hasNext()) {
065     *       FTPFile[] files = engine.getNext(25);  // "page size" you want
066     *       //do whatever you want with these files, display them, etc.
067     *       //expensive FTPFile objects not created until needed.
068     *    }
069     * </pre>
070     * <p>
071     * For unpaged access, simply use FTPClient.listFiles().  That method
072     * uses this class transparently.
073     * @version $Id: FTPListParseEngine.java 658518 2008-05-21 01:04:30Z sebb $
074     */
075    public class FTPListParseEngine {
076        private List<String> entries = new LinkedList<String>();
077        private ListIterator<String> _internalIterator = entries.listIterator();
078    
079        FTPFileEntryParser parser = null;
080    
081        public FTPListParseEngine(FTPFileEntryParser parser) {
082            this.parser = parser;
083        }
084    
085        /**
086         * handle the iniitial reading and preparsing of the list returned by
087         * the server.  After this method has completed, this object will contain
088         * a list of unparsed entries (Strings) each referring to a unique file
089         * on the server.
090         *
091         * @param stream input stream provided by the server socket.
092         *
093         * @exception IOException
094         *                   thrown on any failure to read from the sever.
095         */
096        public void readServerList(InputStream stream, String encoding)
097        throws IOException
098        {
099            this.entries = new LinkedList<String>();
100            readStream(stream, encoding);
101            this.parser.preParse(this.entries);
102            resetIterator();
103        }
104        
105        /**
106         * handle the iniitial reading and preparsing of the list returned by
107         * the server.  After this method has completed, this object will contain
108         * a list of unparsed entries (Strings) each referring to a unique file
109         * on the server.
110         *
111         * @param stream input stream provided by the server socket.
112         *
113         * @exception IOException
114         *                   thrown on any failure to read from the sever.
115         *
116         * @deprecated The version of this method which takes an encoding should be used.
117        */
118        public void readServerList(InputStream stream)
119        throws IOException
120        {
121            readServerList(stream, null);
122        }
123        
124    
125    
126        /**
127         * Internal method for reading the input into the <code>entries</code> list.
128         * After this method has completed, <code>entries</code> will contain a
129         * collection of entries (as defined by
130         * <code>FTPFileEntryParser.readNextEntry()</code>), but this may contain
131         * various non-entry preliminary lines from the server output, duplicates,
132         * and other data that will not be part of the final listing.
133         *
134         * @param stream The socket stream on which the input will be read.
135         * @param encoding The encoding to use.
136         *
137         * @exception IOException
138         *                   thrown on any failure to read the stream
139         */
140        private void readStream(InputStream stream, String encoding) throws IOException
141        {
142            BufferedReader reader;
143            if (encoding == null)
144            {
145                reader = new BufferedReader(new InputStreamReader(stream));
146            }
147            else
148            {
149                reader = new BufferedReader(new InputStreamReader(stream, encoding));
150            }
151            
152            String line = this.parser.readNextEntry(reader);
153    
154            while (line != null)
155            {
156                this.entries.add(line);
157                line = this.parser.readNextEntry(reader);
158            }
159            reader.close();
160        }
161    
162        /**
163         * Returns an array of at most <code>quantityRequested</code> FTPFile
164         * objects starting at this object's internal iterator's current position.
165         * If fewer than <code>quantityRequested</code> such
166         * elements are available, the returned array will have a length equal
167         * to the number of entries at and after after the current position.
168         * If no such entries are found, this array will have a length of 0.
169         *
170         * After this method is called this object's internal iterator is advanced
171         * by a number of positions equal to the size of the array returned.
172         *
173         * @param quantityRequested
174         * the maximum number of entries we want to get.
175         *
176         * @return an array of at most <code>quantityRequested</code> FTPFile
177         * objects starting at the current position of this iterator within its
178         * list and at least the number of elements which  exist in the list at
179         * and after its current position.
180         * <p><b> 
181         * NOTE:</b> This array may contain null members if any of the 
182         * individual file listings failed to parse.  The caller should 
183         * check each entry for null before referencing it.
184         */
185        public FTPFile[] getNext(int quantityRequested) {
186            List<FTPFile> tmpResults = new LinkedList<FTPFile>();
187            int count = quantityRequested;
188            while (count > 0 && this._internalIterator.hasNext()) {
189                String entry = this._internalIterator.next();
190                FTPFile temp = this.parser.parseFTPEntry(entry);
191                tmpResults.add(temp);
192                count--;
193            }
194            return tmpResults.toArray(new FTPFile[0]);
195    
196        }
197    
198        /**
199         * Returns an array of at most <code>quantityRequested</code> FTPFile
200         * objects starting at this object's internal iterator's current position,
201         * and working back toward the beginning.
202         *
203         * If fewer than <code>quantityRequested</code> such
204         * elements are available, the returned array will have a length equal
205         * to the number of entries at and after after the current position.
206         * If no such entries are found, this array will have a length of 0.
207         *
208         * After this method is called this object's internal iterator is moved
209         * back by a number of positions equal to the size of the array returned.
210         *
211         * @param quantityRequested
212         * the maximum number of entries we want to get.
213         *
214         * @return an array of at most <code>quantityRequested</code> FTPFile
215         * objects starting at the current position of this iterator within its
216         * list and at least the number of elements which  exist in the list at
217         * and after its current position.  This array will be in the same order
218         * as the underlying list (not reversed).
219         * <p><b> 
220         * NOTE:</b> This array may contain null members if any of the 
221         * individual file listings failed to parse.  The caller should 
222         * check each entry for null before referencing it.
223         */
224        public FTPFile[] getPrevious(int quantityRequested) {
225            List<FTPFile> tmpResults = new LinkedList<FTPFile>();
226            int count = quantityRequested;
227            while (count > 0 && this._internalIterator.hasPrevious()) {
228                String entry = this._internalIterator.previous();
229                FTPFile temp = this.parser.parseFTPEntry(entry);
230                tmpResults.add(0,temp);
231                count--;
232            }
233            return tmpResults.toArray(new FTPFile[0]);
234        }
235    
236        /**
237         * Returns an array of FTPFile objects containing the whole list of
238         * files returned by the server as read by this object's parser.
239         *
240         * @return an array of FTPFile objects containing the whole list of
241         *         files returned by the server as read by this object's parser.
242         * <p><b> 
243         * NOTE:</b> This array may contain null members if any of the 
244         * individual file listings failed to parse.  The caller should 
245         * check each entry for null before referencing it.
246         * @exception IOException
247         */
248        public FTPFile[] getFiles()
249        throws IOException
250        {
251            List<FTPFile> tmpResults = new LinkedList<FTPFile>();
252            Iterator<String> iter = this.entries.iterator();
253            while (iter.hasNext()) {
254                String entry = iter.next();
255                FTPFile temp = this.parser.parseFTPEntry(entry);
256                tmpResults.add(temp);
257            }
258            return tmpResults.toArray(new FTPFile[0]);
259    
260        }
261    
262        /**
263         * convenience method to allow clients to know whether this object's
264         * internal iterator's current position is at the end of the list.
265         *
266         * @return true if internal iterator is not at end of list, false
267         * otherwise.
268         */
269        public boolean hasNext() {
270            return _internalIterator.hasNext();
271        }
272    
273        /**
274         * convenience method to allow clients to know whether this object's
275         * internal iterator's current position is at the beginning of the list.
276         *
277         * @return true if internal iterator is not at beginning of list, false
278         * otherwise.
279         */
280        public boolean hasPrevious() {
281            return _internalIterator.hasPrevious();
282        }
283    
284        /**
285         * resets this object's internal iterator to the beginning of the list.
286         */
287        public void resetIterator() {
288            this._internalIterator = this.entries.listIterator();
289        }
290    }