View Javadoc

    1   /*
    2    * Copyright 2004 The Apache Software Foundation
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *     http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.net.ftp;
    17
    18  import java.io.BufferedReader;
    19  import java.io.IOException;
    20  import java.io.InputStream;
    21  import java.io.InputStreamReader;
    22  import java.util.Iterator;
    23  import java.util.LinkedList;
    24  import java.util.List;
    25  import java.util.ListIterator;
    26
    27
    28  /***
    29   * This class handles the entire process of parsing a listing of
    30   * file entries from the server.
    31   * <p>
    32   * This object defines a two-part parsing mechanism.
    33   * <p>
    34   * The first part is comprised of reading the raw input into an internal
    35   * list of strings.  Every item in this list corresponds to an actual
    36   * file.  All extraneous matter emitted by the server will have been
    37   * removed by the end of this phase.  This is accomplished in conjunction
    38   * with the FTPFileEntryParser associated with this engine, by calling
    39   * its methods <code>readNextEntry()</code> - which handles the issue of
    40   * what delimits one entry from another, usually but not always a line
    41   * feed and <code>preParse()</code> - which handles removal of
    42   * extraneous matter such as the preliminary lines of a listing, removal
    43   * of duplicates on versioning systems, etc.
    44   * <p>
    45   * The second part is composed of the actual parsing, again in conjunction
    46   * with the particular parser used by this engine.  This is controlled
    47   * by an iterator over the internal list of strings.  This may be done
    48   * either in block mode, by calling the <code>getNext()</code> and
    49   * <code>getPrevious()</code> methods to provide "paged" output of less
    50   * than the whole list at one time, or by calling the
    51   * <code>getFiles()</code> method to return the entire list.
    52   * <p>
    53   * Examples:
    54   * <p>
    55   * Paged access:
    56   * <pre>
    57   *    FTPClient f=FTPClient();
    58   *    f.connect(server);
    59   *    f.login(username, password);
    60   *    FTPListParseEngine engine = f.initiateListParsing(directory);
    61   *
    62   *    while (engine.hasNext()) {
    63   *       FTPFile[] files = engine.getNext(25);  // "page size" you want
    64   *       //do whatever you want with these files, display them, etc.
    65   *       //expensive FTPFile objects not created until needed.
    66   *    }
    67   * </pre>
    68   * <p>
    69   * For unpaged access, simply use FTPClient.listFiles().  That method
    70   * uses this class transparently.
    71   * @version $Id: FTPListParseEngine.java 155429 2005-02-26 13:13:04Z dirkv $
    72   */
    73  public class FTPListParseEngine {
    74      private List entries = new LinkedList();
    75      private ListIterator _internalIterator = entries.listIterator();
    76
    77      FTPFileEntryParser parser = null;
    78
    79      public FTPListParseEngine(FTPFileEntryParser parser) {
    80          this.parser = parser;
    81      }
    82
    83      /***
    84       * handle the iniitial reading and preparsing of the list returned by
    85       * the server.  After this method has completed, this object will contain
    86       * a list of unparsed entries (Strings) each referring to a unique file
    87       * on the server.
    88       *
    89       * @param stream input stream provided by the server socket.
    90       *
    91       * @exception IOException
    92       *                   thrown on any failure to read from the sever.
    93       */
    94      public void readServerList(InputStream stream, String encoding)
    95      throws IOException
    96      {
    97          this.entries = new LinkedList();
    98          readStream(stream, encoding);
    99          this.parser.preParse(this.entries);
    100         resetIterator();
    101     }
    102
    103     /***
    104 	 * handle the iniitial reading and preparsing of the list returned by
    105 	 * the server.  After this method has completed, this object will contain
    106 	 * a list of unparsed entries (Strings) each referring to a unique file
    107 	 * on the server.
    108 	 *
    109 	 * @param stream input stream provided by the server socket.
    110 	 *
    111 	 * @exception IOException
    112 	 *                   thrown on any failure to read from the sever.
    113 	 *
    114 	 * @deprecated The version of this method which takes an encoding should be used.
    115 	*/
    116 	public void readServerList(InputStream stream)
    117 	throws IOException
    118 	{
    119 		readServerList(stream, null);
    120 	}
    121
    122
    123
    124     /***
    125      * Internal method for reading the input into the <code>entries</code> list.
    126      * After this method has completed, <code>entries</code> will contain a
    127      * collection of entries (as defined by
    128      * <code>FTPFileEntryParser.readNextEntry()</code>), but this may contain
    129      * various non-entry preliminary lines from the server output, duplicates,
    130      * and other data that will not be part of the final listing.
    131      *
    132      * @param stream The socket stream on which the input will be read.
    133      * @param encoding The encoding to use.
    134      *
    135      * @exception IOException
    136      *                   thrown on any failure to read the stream
    137      */
    138     private void readStream(InputStream stream, String encoding) throws IOException
    139     {
    140     	BufferedReader reader;
    141     	if (encoding == null)
    142     	{
    143     		reader = new BufferedReader(new InputStreamReader(stream));
    144     	}
    145     	else
    146     	{
    147     		reader = new BufferedReader(new InputStreamReader(stream, encoding));
    148     	}
    149
    150         String line = this.parser.readNextEntry(reader);
    151
    152         while (line != null)
    153         {
    154             this.entries.add(line);
    155             line = this.parser.readNextEntry(reader);
    156         }
    157         reader.close();
    158     }
    159
    160     /***
    161      * Returns an array of at most <code>quantityRequested</code> FTPFile
    162      * objects starting at this object's internal iterator's current position.
    163      * If fewer than <code>quantityRequested</code> such
    164      * elements are available, the returned array will have a length equal
    165      * to the number of entries at and after after the current position.
    166      * If no such entries are found, this array will have a length of 0.
    167      *
    168      * After this method is called this object's internal iterator is advanced
    169      * by a number of positions equal to the size of the array returned.
    170      *
    171      * @param quantityRequested
    172      * the maximum number of entries we want to get.
    173      *
    174      * @return an array of at most <code>quantityRequested</code> FTPFile
    175      * objects starting at the current position of this iterator within its
    176      * list and at least the number of elements which  exist in the list at
    177      * and after its current position.
    178      * <p><b>
    179      * NOTE:</b> This array may contain null members if any of the
    180      * individual file listings failed to parse.  The caller should
    181      * check each entry for null before referencing it.
    182      */
    183     public FTPFile[] getNext(int quantityRequested) {
    184         List tmpResults = new LinkedList();
    185         int count = quantityRequested;
    186         while (count > 0 && this._internalIterator.hasNext()) {
    187             String entry = (String) this._internalIterator.next();
    188             FTPFile temp = this.parser.parseFTPEntry(entry);
    189             tmpResults.add(temp);
    190             count--;
    191         }
    192         return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
    193
    194     }
    195
    196     /***
    197      * Returns an array of at most <code>quantityRequested</code> FTPFile
    198      * objects starting at this object's internal iterator's current position,
    199      * and working back toward the beginning.
    200      *
    201      * If fewer than <code>quantityRequested</code> such
    202      * elements are available, the returned array will have a length equal
    203      * to the number of entries at and after after the current position.
    204      * If no such entries are found, this array will have a length of 0.
    205      *
    206      * After this method is called this object's internal iterator is moved
    207      * back by a number of positions equal to the size of the array returned.
    208      *
    209      * @param quantityRequested
    210      * the maximum number of entries we want to get.
    211      *
    212      * @return an array of at most <code>quantityRequested</code> FTPFile
    213      * objects starting at the current position of this iterator within its
    214      * list and at least the number of elements which  exist in the list at
    215      * and after its current position.  This array will be in the same order
    216      * as the underlying list (not reversed).
    217      * <p><b>
    218      * NOTE:</b> This array may contain null members if any of the
    219      * individual file listings failed to parse.  The caller should
    220      * check each entry for null before referencing it.
    221      */
    222     public FTPFile[] getPrevious(int quantityRequested) {
    223         List tmpResults = new LinkedList();
    224         int count = quantityRequested;
    225         while (count > 0 && this._internalIterator.hasPrevious()) {
    226             String entry = (String) this._internalIterator.previous();
    227             FTPFile temp = this.parser.parseFTPEntry(entry);
    228             tmpResults.add(0,temp);
    229             count--;
    230         }
    231         return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
    232     }
    233
    234     /***
    235      * Returns an array of FTPFile objects containing the whole list of
    236      * files returned by the server as read by this object's parser.
    237      *
    238      * @return an array of FTPFile objects containing the whole list of
    239      *         files returned by the server as read by this object's parser.
    240      * <p><b>
    241      * NOTE:</b> This array may contain null members if any of the
    242      * individual file listings failed to parse.  The caller should
    243      * check each entry for null before referencing it.
    244      * @exception IOException
    245      */
    246     public FTPFile[] getFiles()
    247     throws IOException
    248     {
    249         List tmpResults = new LinkedList();
    250         Iterator iter = this.entries.iterator();
    251         while (iter.hasNext()) {
    252             String entry = (String) iter.next();
    253             FTPFile temp = this.parser.parseFTPEntry(entry);
    254             tmpResults.add(temp);
    255         }
    256         return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
    257
    258     }
    259
    260     /***
    261      * convenience method to allow clients to know whether this object's
    262      * internal iterator's current position is at the end of the list.
    263      *
    264      * @return true if internal iterator is not at end of list, false
    265      * otherwise.
    266      */
    267     public boolean hasNext() {
    268         return _internalIterator.hasNext();
    269     }
    270
    271     /***
    272      * convenience method to allow clients to know whether this object's
    273      * internal iterator's current position is at the beginning of the list.
    274      *
    275      * @return true if internal iterator is not at beginning of list, false
    276      * otherwise.
    277      */
    278     public boolean hasPrevious() {
    279         return _internalIterator.hasPrevious();
    280     }
    281
    282     /***
    283      * resets this object's internal iterator to the beginning of the list.
    284      */
    285     public void resetIterator() {
    286         this._internalIterator = this.entries.listIterator();
    287     }
    288 }