    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.ArrayList;
    025    import java.util.Iterator;
    026    import java.util.LinkedList;
    027    import java.util.List;
    028    import java.util.ListIterator;
    029
    030
    031    /**
    032     * This class handles the entire process of parsing a listing of
    033     * file entries from the server.
    034     * <p>
    035     * This object defines a two-part parsing mechanism.
    036     * <p>
    037     * The first part is comprised of reading the raw input into an internal
    038     * list of strings.  Every item in this list corresponds to an actual
    039     * file.  All extraneous matter emitted by the server will have been
    040     * removed by the end of this phase.  This is accomplished in conjunction
    041     * with the FTPFileEntryParser associated with this engine, by calling
    042     * its methods <code>readNextEntry()</code> - which handles the issue of
    043     * what delimits one entry from another, usually but not always a line
    044     * feed and <code>preParse()</code> - which handles removal of
    045     * extraneous matter such as the preliminary lines of a listing, removal
    046     * of duplicates on versioning systems, etc.
    047     * <p>
    048     * The second part is composed of the actual parsing, again in conjunction
    049     * with the particular parser used by this engine.  This is controlled
    050     * by an iterator over the internal list of strings.  This may be done
    051     * either in block mode, by calling the <code>getNext()</code> and
    052     * <code>getPrevious()</code> methods to provide "paged" output of less
    053     * than the whole list at one time, or by calling the
    054     * <code>getFiles()</code> method to return the entire list.
    055     * <p>
    056     * Examples:
    057     * <p>
    058     * Paged access:
    059     * <pre>
    060     *    FTPClient f=FTPClient();
    061     *    f.connect(server);
    062     *    f.login(username, password);
    063     *    FTPListParseEngine engine = f.initiateListParsing(directory);
    064     *
    065     *    while (engine.hasNext()) {
    066     *       FTPFile[] files = engine.getNext(25);  // "page size" you want
    067     *       //do whatever you want with these files, display them, etc.
    068     *       //expensive FTPFile objects not created until needed.
    069     *    }
    070     * </pre>
    071     * <p>
    072     * For unpaged access, simply use FTPClient.listFiles().  That method
    073     * uses this class transparently.
    074     * @version $Id: FTPListParseEngine.java 1032954 2010-11-09 12:15:10Z sebb $
    075     */
    076    public class FTPListParseEngine {
    077        private List<String> entries = new LinkedList<String>();
    078        private ListIterator<String> _internalIterator = entries.listIterator();
    079
    080        private final FTPFileEntryParser parser;
    081
    082        public FTPListParseEngine(FTPFileEntryParser parser) {
    083            this.parser = parser;
    084        }
    085
    086        /**
    087         * handle the initial reading and preparsing of the list returned by
    088         * the server.  After this method has completed, this object will contain
    089         * a list of unparsed entries (Strings) each referring to a unique file
    090         * on the server.
    091         *
    092         * @param stream input stream provided by the server socket.
    093         *
    094         * @exception IOException
    095         *                   thrown on any failure to read from the sever.
    096         */
    097        public void readServerList(InputStream stream, String encoding)
    098        throws IOException
    099        {
    100            this.entries = new LinkedList<String>();
    101            readStream(stream, encoding);
    102            this.parser.preParse(this.entries);
    103            resetIterator();
    104        }
    105
    106        /**
    107         * handle the iniitial reading and preparsing of the list returned by
    108         * the server.  After this method has completed, this object will contain
    109         * a list of unparsed entries (Strings) each referring to a unique file
    110         * on the server.
    111         *
    112         * @param stream input stream provided by the server socket.
    113         *
    114         * @exception IOException
    115         *                   thrown on any failure to read from the sever.
    116         *
    117         * @deprecated The version of this method which takes an encoding should be used.
    118        */
    119        @Deprecated
    120        public void readServerList(InputStream stream)
    121        throws IOException
    122        {
    123            readServerList(stream, null);
    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[tmpResults.size()]);
    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[tmpResults.size()]);
    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            return getFiles(FTPFileFilters.ALL);
    252        }
    253
    254        /**
    255         * Returns an array of FTPFile objects containing the whole list of
    256         * files returned by the server as read by this object's parser.
    257         * The files are filtered before being added to the array.
    258         *
    259         * @param filter FTPFileFilter, must not be <code>null</code>.
    260         *
    261         * @return an array of FTPFile objects containing the whole list of
    262         *         files returned by the server as read by this object's parser.
    263         * <p><b>
    264         * NOTE:</b> This array may contain null members if any of the
    265         * individual file listings failed to parse.  The caller should
    266         * check each entry for null before referencing it, or use the
    267         * a filter such as {@link FTPFileFilters#NON_NULL} which does not
    268         * allow null entries.
    269         * @since 2.2
    270         * @exception IOException
    271         */
    272        public FTPFile[] getFiles(FTPFileFilter filter)
    273        throws IOException
    274        {
    275            List<FTPFile> tmpResults = new ArrayList<FTPFile>();
    276            Iterator<String> iter = this.entries.iterator();
    277            while (iter.hasNext()) {
    278                String entry = iter.next();
    279                FTPFile temp = this.parser.parseFTPEntry(entry);
    280                if (filter.accept(temp)){
    281                    tmpResults.add(temp);
    282                }
    283            }
    284            return tmpResults.toArray(new FTPFile[tmpResults.size()]);
    285
    286        }
    287
    288        /**
    289         * convenience method to allow clients to know whether this object's
    290         * internal iterator's current position is at the end of the list.
    291         *
    292         * @return true if internal iterator is not at end of list, false
    293         * otherwise.
    294         */
    295        public boolean hasNext() {
    296            return _internalIterator.hasNext();
    297        }
    298
    299        /**
    300         * convenience method to allow clients to know whether this object's
    301         * internal iterator's current position is at the beginning of the list.
    302         *
    303         * @return true if internal iterator is not at beginning of list, false
    304         * otherwise.
    305         */
    306        public boolean hasPrevious() {
    307            return _internalIterator.hasPrevious();
    308        }
    309
    310        /**
    311         * resets this object's internal iterator to the beginning of the list.
    312         */
    313        public void resetIterator() {
    314            this._internalIterator = this.entries.listIterator();
    315        }
    316    }