1
2
3
4
5
6
7
8
9
10
11
12
13
14
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
232
233
234
235
236
237