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<>();
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    /**
086     * An empty immutable {@code FTPFile} array.
087     */
088    private static final FTPFile[] EMPTY_FTP_FILE_ARRAY = new FTPFile[0];
089
090    public FTPListParseEngine(final FTPFileEntryParser parser) {
091        this(parser, null);
092    }
093
094    /**
095     * Intended for use by FTPClient only
096     * @since 3.4
097     */
098    FTPListParseEngine(final FTPFileEntryParser parser, final FTPClientConfig configuration) {
099        this.parser = parser;
100        if (configuration != null) {
101            this.saveUnparseableEntries = configuration.getUnparseableEntries();
102        } else {
103            this.saveUnparseableEntries = false;
104        }
105    }
106
107    /**
108     * Reads (and closes) the initial reading and preparsing of the list returned by the server. After this method has
109     * completed, this object will contain a list of unparsed entries (Strings) each referring to a unique file on the
110     * server.
111     *
112     * @param inputStream input stream provided by the server socket.
113     * @param charsetName the encoding to be used for reading the stream
114     *
115     * @throws IOException thrown on any failure to read from the sever.
116     */
117    public void readServerList(final InputStream inputStream, final String charsetName) throws IOException {
118        this.entries = new LinkedList<>();
119        read(inputStream, charsetName);
120        this.parser.preParse(this.entries);
121        resetIterator();
122    }
123
124    /**
125     * Internal method for reading (and closing) the input into the <code>entries</code> list. After this method has
126     * completed, <code>entries</code> will contain a collection of entries (as defined by
127     * <code>FTPFileEntryParser.readNextEntry()</code>), but this may contain various non-entry preliminary lines from
128     * the server output, duplicates, and other data that will not be part of the final listing.
129     *
130     * @param inputStream The socket stream on which the input will be read.
131     * @param charsetName The encoding to use.
132     *
133     * @throws IOException thrown on any failure to read the stream
134     */
135    private void read(final InputStream inputStream, final String charsetName) throws IOException {
136        try (final BufferedReader reader = new BufferedReader(
137            new InputStreamReader(inputStream, Charsets.toCharset(charsetName)))) {
138
139            String line = this.parser.readNextEntry(reader);
140
141            while (line != null) {
142                this.entries.add(line);
143                line = this.parser.readNextEntry(reader);
144            }
145        }
146    }
147
148    /**
149     * Returns an array of at most <code>quantityRequested</code> FTPFile
150     * objects starting at this object's internal iterator's current position.
151     * If fewer than <code>quantityRequested</code> such
152     * elements are available, the returned array will have a length equal
153     * to the number of entries at and after after the current position.
154     * If no such entries are found, this array will have a length of 0.
155     *
156     * After this method is called this object's internal iterator is advanced
157     * by a number of positions equal to the size of the array returned.
158     *
159     * @param quantityRequested
160     * the maximum number of entries we want to get.
161     *
162     * @return an array of at most <code>quantityRequested</code> FTPFile
163     * objects starting at the current position of this iterator within its
164     * list and at least the number of elements which  exist in the list at
165     * and after its current position.
166     * <p><b>
167     * NOTE:</b> This array may contain null members if any of the
168     * individual file listings failed to parse.  The caller should
169     * check each entry for null before referencing it.
170     */
171    public FTPFile[] getNext(final int quantityRequested) {
172        final List<FTPFile> tmpResults = new LinkedList<>();
173        int count = quantityRequested;
174        while (count > 0 && this.internalIterator.hasNext()) {
175            final String entry = this.internalIterator.next();
176            FTPFile temp = this.parser.parseFTPEntry(entry);
177            if (temp == null && saveUnparseableEntries) {
178                temp = new FTPFile(entry);
179            }
180            tmpResults.add(temp);
181            count--;
182        }
183        return tmpResults.toArray(EMPTY_FTP_FILE_ARRAY);
184
185    }
186
187    /**
188     * Returns an array of at most <code>quantityRequested</code> FTPFile
189     * objects starting at this object's internal iterator's current position,
190     * and working back toward the beginning.
191     *
192     * If fewer than <code>quantityRequested</code> such
193     * elements are available, the returned array will have a length equal
194     * to the number of entries at and after after the current position.
195     * If no such entries are found, this array will have a length of 0.
196     *
197     * After this method is called this object's internal iterator is moved
198     * back by a number of positions equal to the size of the array returned.
199     *
200     * @param quantityRequested
201     * the maximum number of entries we want to get.
202     *
203     * @return an array of at most <code>quantityRequested</code> FTPFile
204     * objects starting at the current position of this iterator within its
205     * list and at least the number of elements which  exist in the list at
206     * and after its current position.  This array will be in the same order
207     * as the underlying list (not reversed).
208     * <p><b>
209     * NOTE:</b> This array may contain null members if any of the
210     * individual file listings failed to parse.  The caller should
211     * check each entry for null before referencing it.
212     */
213    public FTPFile[] getPrevious(final int quantityRequested) {
214        final List<FTPFile> tmpResults = new LinkedList<>();
215        int count = quantityRequested;
216        while (count > 0 && this.internalIterator.hasPrevious()) {
217            final String entry = this.internalIterator.previous();
218            FTPFile temp = this.parser.parseFTPEntry(entry);
219            if (temp == null && saveUnparseableEntries) {
220                temp = new FTPFile(entry);
221            }
222            tmpResults.add(0,temp);
223            count--;
224        }
225        return tmpResults.toArray(EMPTY_FTP_FILE_ARRAY);
226    }
227
228    /**
229     * Returns an array of FTPFile objects containing the whole list of
230     * files returned by the server as read by this object's parser.
231     *
232     * @return an array of FTPFile objects containing the whole list of
233     *         files returned by the server as read by this object's parser.
234     * None of the entries will be null
235     * @throws IOException - not ever thrown, may be removed in a later release
236     */
237    public FTPFile[] getFiles()
238    throws IOException // TODO remove; not actually thrown
239    {
240        return getFiles(FTPFileFilters.NON_NULL);
241    }
242
243    /**
244     * Returns an array of FTPFile objects containing the whole list of
245     * files returned by the server as read by this object's parser.
246     * The files are filtered before being added to the array.
247     *
248     * @param filter FTPFileFilter, must not be <code>null</code>.
249     *
250     * @return an array of FTPFile objects containing the whole list of
251     *         files returned by the server as read by this object's parser.
252     * <p><b>
253     * NOTE:</b> This array may contain null members if any of the
254     * individual file listings failed to parse.  The caller should
255     * check each entry for null before referencing it, or use the
256     * a filter such as {@link FTPFileFilters#NON_NULL} which does not
257     * allow null entries.
258     * @since 2.2
259     * @throws IOException - not ever thrown, may be removed in a later release
260     */
261    public FTPFile[] getFiles(final FTPFileFilter filter)
262    throws IOException // TODO remove; not actually thrown
263    {
264        final List<FTPFile> tmpResults = new ArrayList<>();
265        final Iterator<String> iter = this.entries.iterator();
266        while (iter.hasNext()) {
267            final String entry = iter.next();
268            FTPFile temp = this.parser.parseFTPEntry(entry);
269            if (temp == null && saveUnparseableEntries) {
270                temp = new FTPFile(entry);
271            }
272            if (filter.accept(temp)) {
273                tmpResults.add(temp);
274            }
275        }
276        return tmpResults.toArray(EMPTY_FTP_FILE_ARRAY);
277
278    }
279
280    /**
281     * convenience method to allow clients to know whether this object's
282     * internal iterator's current position is at the end of the list.
283     *
284     * @return true if internal iterator is not at end of list, false
285     * otherwise.
286     */
287    public boolean hasNext() {
288        return internalIterator.hasNext();
289    }
290
291    /**
292     * convenience method to allow clients to know whether this object's
293     * internal iterator's current position is at the beginning of the list.
294     *
295     * @return true if internal iterator is not at beginning of list, false
296     * otherwise.
297     */
298    public boolean hasPrevious() {
299        return internalIterator.hasPrevious();
300    }
301
302    /**
303     * resets this object's internal iterator to the beginning of the list.
304     */
305    public void resetIterator() {
306        this.internalIterator = this.entries.listIterator();
307    }
308
309    // DEPRECATED METHODS - for API compatibility only - DO NOT USE
310
311    /**
312     * Do not use.
313     * @param inputStream the stream from which to read
314     * @throws IOException on error
315     * @deprecated use {@link #readServerList(InputStream, String)} instead
316    */
317    @Deprecated
318    public void readServerList(final InputStream inputStream) throws IOException {
319        readServerList(inputStream, null);
320    }
321
322}