FTPFileList


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  */
238
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags