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
018package org.apache.commons.net.ftp;
019
020import java.io.BufferedReader;
021import java.io.IOException;
022import java.io.InputStream;
023import java.io.InputStreamReader;
024import java.util.ArrayList;
025import java.util.Iterator;
026import java.util.LinkedList;
027import java.util.List;
028import java.util.ListIterator;
029
030import org.apache.commons.net.util.Charsets;
031
032
033/**
034 * This class handles the entire process of parsing a listing of
035 * file entries from the server.
036 * <p>
037 * This object defines a two-part parsing mechanism.
038 * <p>
039 * The first part is comprised of reading the raw input into an internal
040 * list of strings.  Every item in this list corresponds to an actual
041 * file.  All extraneous matter emitted by the server will have been
042 * removed by the end of this phase.  This is accomplished in conjunction
043 * with the FTPFileEntryParser associated with this engine, by calling
044 * its methods <code>readNextEntry()</code> - which handles the issue of
045 * what delimits one entry from another, usually but not always a line
046 * feed and <code>preParse()</code> - which handles removal of
047 * extraneous matter such as the preliminary lines of a listing, removal
048 * of duplicates on versioning systems, etc.
049 * <p>
050 * The second part is composed of the actual parsing, again in conjunction
051 * with the particular parser used by this engine.  This is controlled
052 * by an iterator over the internal list of strings.  This may be done
053 * either in block mode, by calling the <code>getNext()</code> and
054 * <code>getPrevious()</code> methods to provide "paged" output of less
055 * than the whole list at one time, or by calling the
056 * <code>getFiles()</code> method to return the entire list.
057 * <p>
058 * Examples:
059 * <p>
060 * Paged access:
061 * <pre>
062 *    FTPClient f=FTPClient();
063 *    f.connect(server);
064 *    f.login(username, password);
065 *    FTPListParseEngine engine = f.initiateListParsing(directory);
066 *
067 *    while (engine.hasNext()) {
068 *       FTPFile[] files = engine.getNext(25);  // "page size" you want
069 *       //do whatever you want with these files, display them, etc.
070 *       //expensive FTPFile objects not created until needed.
071 *    }
072 * </pre>
073 * <p>
074 * For unpaged access, simply use FTPClient.listFiles().  That method
075 * uses this class transparently.
076 */
077public class FTPListParseEngine {
078    private List<String> entries = new LinkedList<String>();
079    private ListIterator<String> _internalIterator = entries.listIterator();
080
081    private final FTPFileEntryParser parser;
082    // Should invalid files (parse failures) be allowed?
083    private final boolean saveUnparseableEntries;
084
085    public FTPListParseEngine(FTPFileEntryParser parser) {
086        this(parser, null);
087    }
088
089    /**
090     * Intended for use by FTPClient only
091     * @since 3.4
092     */
093    FTPListParseEngine(FTPFileEntryParser parser, FTPClientConfig configuration) {
094        this.parser = parser;
095        if (configuration != null) {
096            this.saveUnparseableEntries = configuration.getUnparseableEntries();
097        } else {
098            this.saveUnparseableEntries = false;
099        }
100    }
101
102    /**
103     * handle the initial reading and preparsing of the list returned by
104     * the server.  After this method has completed, this object will contain
105     * a list of unparsed entries (Strings) each referring to a unique file
106     * on the server.
107     *
108     * @param stream input stream provided by the server socket.
109     * @param encoding the encoding to be used for reading the stream
110     *
111     * @throws IOException
112     *                   thrown on any failure to read from the sever.
113     */
114    public void readServerList(InputStream stream, String encoding)
115    throws IOException
116    {
117        this.entries = new LinkedList<String>();
118        readStream(stream, encoding);
119        this.parser.preParse(this.entries);
120        resetIterator();
121    }
122
123    /**
124     * Internal method for reading the input into the <code>entries</code> list.
125     * After this method has completed, <code>entries</code> will contain a
126     * collection of entries (as defined by
127     * <code>FTPFileEntryParser.readNextEntry()</code>), but this may contain
128     * various non-entry preliminary lines from the server output, duplicates,
129     * and other data that will not be part of the final listing.
130     *
131     * @param stream The socket stream on which the input will be read.
132     * @param encoding The encoding to use.
133     *
134     * @throws IOException
135     *                   thrown on any failure to read the stream
136     */
137    private void readStream(InputStream stream, String encoding) throws IOException
138    {
139        BufferedReader reader = new BufferedReader(
140                new InputStreamReader(stream, Charsets.toCharset(encoding)));
141
142        String line = this.parser.readNextEntry(reader);
143
144        while (line != null)
145        {
146            this.entries.add(line);
147            line = this.parser.readNextEntry(reader);
148        }
149        reader.close();
150    }
151
152    /**
153     * Returns an array of at most <code>quantityRequested</code> FTPFile
154     * objects starting at this object's internal iterator's current position.
155     * If fewer than <code>quantityRequested</code> such
156     * elements are available, the returned array will have a length equal
157     * to the number of entries at and after after the current position.
158     * If no such entries are found, this array will have a length of 0.
159     *
160     * After this method is called this object's internal iterator is advanced
161     * by a number of positions equal to the size of the array returned.
162     *
163     * @param quantityRequested
164     * the maximum number of entries we want to get.
165     *
166     * @return an array of at most <code>quantityRequested</code> FTPFile
167     * objects starting at the current position of this iterator within its
168     * list and at least the number of elements which  exist in the list at
169     * and after its current position.
170     * <p><b>
171     * NOTE:</b> This array may contain null members if any of the
172     * individual file listings failed to parse.  The caller should
173     * check each entry for null before referencing it.
174     */
175    public FTPFile[] getNext(int quantityRequested) {
176        List<FTPFile> tmpResults = new LinkedList<FTPFile>();
177        int count = quantityRequested;
178        while (count > 0 && this._internalIterator.hasNext()) {
179            String entry = this._internalIterator.next();
180            FTPFile temp = this.parser.parseFTPEntry(entry);
181            if (temp == null && saveUnparseableEntries) {
182                temp = new FTPFile(entry);
183            }
184            tmpResults.add(temp);
185            count--;
186        }
187        return tmpResults.toArray(new FTPFile[tmpResults.size()]);
188
189    }
190
191    /**
192     * Returns an array of at most <code>quantityRequested</code> FTPFile
193     * objects starting at this object's internal iterator's current position,
194     * and working back toward the beginning.
195     *
196     * If fewer than <code>quantityRequested</code> such
197     * elements are available, the returned array will have a length equal
198     * to the number of entries at and after after the current position.
199     * If no such entries are found, this array will have a length of 0.
200     *
201     * After this method is called this object's internal iterator is moved
202     * back by a number of positions equal to the size of the array returned.
203     *
204     * @param quantityRequested
205     * the maximum number of entries we want to get.
206     *
207     * @return an array of at most <code>quantityRequested</code> FTPFile
208     * objects starting at the current position of this iterator within its
209     * list and at least the number of elements which  exist in the list at
210     * and after its current position.  This array will be in the same order
211     * as the underlying list (not reversed).
212     * <p><b>
213     * NOTE:</b> This array may contain null members if any of the
214     * individual file listings failed to parse.  The caller should
215     * check each entry for null before referencing it.
216     */
217    public FTPFile[] getPrevious(int quantityRequested) {
218        List<FTPFile> tmpResults = new LinkedList<FTPFile>();
219        int count = quantityRequested;
220        while (count > 0 && this._internalIterator.hasPrevious()) {
221            String entry = this._internalIterator.previous();
222            FTPFile temp = this.parser.parseFTPEntry(entry);
223            if (temp == null && saveUnparseableEntries) {
224                temp = new FTPFile(entry);
225            }
226            tmpResults.add(0,temp);
227            count--;
228        }
229        return tmpResults.toArray(new FTPFile[tmpResults.size()]);
230    }
231
232    /**
233     * Returns an array of FTPFile objects containing the whole list of
234     * files returned by the server as read by this object's parser.
235     *
236     * @return an array of FTPFile objects containing the whole list of
237     *         files returned by the server as read by this object's parser.
238     * None of the entries will be null
239     * @throws IOException - not ever thrown, may be removed in a later release
240     */
241    public FTPFile[] getFiles()
242    throws IOException // TODO remove; not actually thrown
243    {
244        return getFiles(FTPFileFilters.NON_NULL);
245    }
246
247    /**
248     * Returns an array of FTPFile objects containing the whole list of
249     * files returned by the server as read by this object's parser.
250     * The files are filtered before being added to the array.
251     *
252     * @param filter FTPFileFilter, must not be <code>null</code>.
253     *
254     * @return an array of FTPFile objects containing the whole list of
255     *         files returned by the server as read by this object's parser.
256     * <p><b>
257     * NOTE:</b> This array may contain null members if any of the
258     * individual file listings failed to parse.  The caller should
259     * check each entry for null before referencing it, or use the
260     * a filter such as {@link FTPFileFilters#NON_NULL} which does not
261     * allow null entries.
262     * @since 2.2
263     * @throws IOException - not ever thrown, may be removed in a later release
264     */
265    public FTPFile[] getFiles(FTPFileFilter filter)
266    throws IOException // TODO remove; not actually thrown
267    {
268        List<FTPFile> tmpResults = new ArrayList<FTPFile>();
269        Iterator<String> iter = this.entries.iterator();
270        while (iter.hasNext()) {
271            String entry = iter.next();
272            FTPFile temp = this.parser.parseFTPEntry(entry);
273            if (temp == null && saveUnparseableEntries) {
274                temp = new FTPFile(entry);
275            }
276            if (filter.accept(temp)){
277                tmpResults.add(temp);
278            }
279        }
280        return tmpResults.toArray(new FTPFile[tmpResults.size()]);
281
282    }
283
284    /**
285     * convenience method to allow clients to know whether this object's
286     * internal iterator's current position is at the end of the list.
287     *
288     * @return true if internal iterator is not at end of list, false
289     * otherwise.
290     */
291    public boolean hasNext() {
292        return _internalIterator.hasNext();
293    }
294
295    /**
296     * convenience method to allow clients to know whether this object's
297     * internal iterator's current position is at the beginning of the list.
298     *
299     * @return true if internal iterator is not at beginning of list, false
300     * otherwise.
301     */
302    public boolean hasPrevious() {
303        return _internalIterator.hasPrevious();
304    }
305
306    /**
307     * resets this object's internal iterator to the beginning of the list.
308     */
309    public void resetIterator() {
310        this._internalIterator = this.entries.listIterator();
311    }
312
313    // DEPRECATED METHODS - for API compatibility only - DO NOT USE
314
315    /**
316     * Do not use.
317     * @param stream the stream from which to read
318     * @throws IOException on error
319     * @deprecated use {@link #readServerList(InputStream, String)} instead
320    */
321    @Deprecated
322    public void readServerList(InputStream stream)
323    throws IOException
324    {
325        readServerList(stream, null);
326    }
327
328}