View Javadoc

    1   /*
    2    * Copyright 2001-2005 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  import java.io.BufferedReader;
    18  import java.io.IOException;
    19  import java.io.InputStream;
    20  import java.io.InputStreamReader;
    21  import java.util.LinkedList;
    22  import java.util.List;
    23
    24  /***
    25   * This class encapsulates a listing of files from an FTP server.  It is
    26   * initialized with an input stream which is read and the input split into
    27   * lines, each of which (after some possible initial verbiage) represents
    28   * a file on the FTP server.  A parser is also supplied, which is used to
    29   * iterate through the internal list of lines parsing each into an FTPFile
    30   * object which is returned to the caller of the iteration methods.  This
    31   * parser may be replaced with another, allowing the same list to be parsed
    32   * with different parsers.
    33   * Parsing takes place on an as-needed basis, basically, the first time a
    34   * position is iterated over.  This happens at the time of iteration, not
    35   * prior to it as the older <code>(FTPClient.listFiles()</code> methods did,
    36   * which required a bigger memory hit.
    37   *
    38   * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
    39   * @version $Id: FTPFileList.java 165675 2005-05-02 20:09:55Z rwinston $
    40   * @see org.apache.commons.net.ftp.FTPClient#createFileList
    41   * @see org.apache.commons.net.ftp.FTPFileIterator
    42   * @see org.apache.commons.net.ftp.FTPFileEntryParser
    43   * @see org.apache.commons.net.ftp.FTPListParseEngine
    44   * @deprecated This class is deprecated as of version 1.2 and will be
    45   * removed in version 2.0 -- use FTPFileParseEngine instead.
    46   */
    47  public class FTPFileList
    48  {
    49      /***
    50       * storage for the raw lines of input read from the FTP server
    51       */
    52      private LinkedList lines = null;
    53      /***
    54       * the FTPFileEntryParser assigned to be used with this lister
    55       */
    56      private FTPFileEntryParser parser;
    57      /***
    58       * private status code for an empty directory
    59       */
    60      private static final int EMPTY_DIR = -2;
    61
    62      /***
    63       * The only constructor for FTPFileList, private because
    64       * construction only invoked at create()
    65       *
    66       * @param parser a <code>FTPFileEntryParser</code> value that knows
    67       * how to parse the entries returned by a particular FTP site.
    68       * @param encoding The encoding to use.
    69       */
    70      private FTPFileList (FTPFileEntryParser parser, String encoding)
    71      {
    72          this.parser = parser;
    73          this.lines = new LinkedList();
    74      }
    75
    76      /***
    77       * The only way to create an <code>FTPFileList</code> object.  Invokes
    78       * the private constructor and then reads the stream  supplied stream to
    79       * build the intermediate array of "lines" which will later be parsed
    80       * into <code>FTPFile</code> object.
    81       *
    82       * @param stream The input stream created by reading the socket on which
    83       * the output of the LIST command was returned
    84       * @param parser the default <code>FTPFileEntryParser</code> to be used
    85       * by this object.  This may later be changed using the init() method.
    86       * @param encoding The encoding to use
    87       *
    88       * @return the <code>FTPFileList</code> created, with an initialized
    89       * of unparsed lines of output.  Will be null if the listing cannot
    90       * be read from the stream.
    91       * @exception IOException
    92       *                   Thrown on any failure to read from the socket.
    93       */
    94      public static FTPFileList create(InputStream stream,
    95                                        FTPFileEntryParser parser,
    96  									  String encoding)
    97              throws IOException
    98      {
    99          FTPFileList list = new FTPFileList(parser, encoding);
    100         list.readStream(stream, encoding);
    101         parser.preParse(list.lines);
    102         return list;
    103     }
    104
    105     /***
    106      * The only way to create an <code>FTPFileList</code> object.  Invokes
    107      * the private constructor and then reads the stream  supplied stream to
    108      * build the intermediate array of "lines" which will later be parsed
    109      * into <code>FTPFile</code> object.
    110      *
    111      * @param stream The input stream created by reading the socket on which
    112      * the output of the LIST command was returned
    113      * @param parser the default <code>FTPFileEntryParser</code> to be used
    114      * by this object.  This may later be changed using the init() method.
    115      *
    116      * @return the <code>FTPFileList</code> created, with an initialized
    117      * of unparsed lines of output.  Will be null if the listing cannot
    118      * be read from the stream.
    119      * @exception IOException
    120      *                   Thrown on any failure to read from the socket.
    121      *
    122      * @deprecated The version of this method which takes an encoding should be used.
    123     */
    124     public static FTPFileList create(InputStream stream,
    125     								  FTPFileEntryParser parser)
    126     	throws IOException
    127     {
    128     	return create(stream, parser, null);
    129     }
    130
    131
    132
    133     /***
    134      * internal method for reading the input into the <code>lines</code> vector.
    135      *
    136      * @param stream The socket stream on which the input will be read.
    137      * @param encoding The encoding to use.
    138      *
    139      * @exception IOException thrown on any failure to read the stream
    140      */
    141     public void readStream(InputStream stream, String encoding) throws IOException
    142     {
    143         BufferedReader reader = new BufferedReader(new InputStreamReader(stream, encoding));
    144
    145         String line = this.parser.readNextEntry(reader);
    146
    147         while (line != null)
    148         {
    149             this.lines.add(line);
    150             line = this.parser.readNextEntry(reader);
    151         }
    152         reader.close();
    153     }
    154
    155     /***
    156 	 * internal method for reading the input into the <code>lines</code> vector.
    157 	 *
    158 	 * @param stream The socket stream on which the input will be read.
    159 	 *
    160 	 * @exception IOException thrown on any failure to read the stream
    161 	 *
    162 	 * @deprecated The version of this method which takes an encoding should be used.
    163 	*/
    164 	public void readStream(InputStream stream) throws IOException
    165 	{
    166 	 readStream(stream, null);
    167 	}
    168
    169
    170     /***
    171      * Accessor for this object's default parser.
    172      *
    173      * @return this object's default parser.
    174      */
    175     FTPFileEntryParser getParser()
    176     {
    177         return this.parser;
    178     }
    179
    180     /***
    181      * Package private accessor for the collection of raw input lines.
    182      *
    183      * @return vector containing all the raw input lines returned from the FTP
    184      * server
    185      */
    186     List getLines()
    187     {
    188         return this.lines;
    189     }
    190
    191     /***
    192      * create an iterator over this list using the parser with which this list
    193      * was initally created
    194      *
    195      * @return an iterator over this list using the list's default parser.
    196      */
    197     public FTPFileIterator iterator()
    198     {
    199         return new FTPFileIterator(this);
    200     }
    201     /***
    202      * create an iterator over this list using the supplied parser
    203      *
    204      * @param parser The user-supplied parser with which the list is to be
    205      * iterated, may be different from this list's default parser.
    206      *
    207      * @return an iterator over this list using the supplied parser.
    208      */
    209     public FTPFileIterator iterator(FTPFileEntryParser parser)
    210     {
    211         return new FTPFileIterator(this, parser);
    212     }
    213
    214
    215     /***
    216      * returns an array of FTPFile objects for all the files in the directory
    217      * listing
    218      *
    219      * @return  an array of FTPFile objects for all the files in the directory
    220      * listinge
    221      */
    222     public FTPFile[] getFiles()
    223     {
    224         return iterator().getFiles();
    225     }
    226
    227
    228
    229 }
    230
    231 /* Emacs configuration
    232  * Local variables:        **
    233  * mode:             java  **
    234  * c-basic-offset:   4     **
    235  * indent-tabs-mode: nil   **
    236  * End:                    **
    237  */