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