001 /*
002 * Copyright 2001-2005 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.apache.commons.net.ftp;
017 import java.io.BufferedReader;
018 import java.io.IOException;
019 import java.io.InputStream;
020 import java.io.InputStreamReader;
021 import java.util.LinkedList;
022 import java.util.List;
023
024 /**
025 * This class encapsulates a listing of files from an FTP server. It is
026 * initialized with an input stream which is read and the input split into
027 * lines, each of which (after some possible initial verbiage) represents
028 * a file on the FTP server. A parser is also supplied, which is used to
029 * iterate through the internal list of lines parsing each into an FTPFile
030 * object which is returned to the caller of the iteration methods. This
031 * parser may be replaced with another, allowing the same list to be parsed
032 * with different parsers.
033 * Parsing takes place on an as-needed basis, basically, the first time a
034 * position is iterated over. This happens at the time of iteration, not
035 * prior to it as the older <code>(FTPClient.listFiles()</code> methods did,
036 * which required a bigger memory hit.
037 *
038 * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
039 * @version $Id: FTPFileList.java 165675 2005-05-02 20:09:55Z rwinston $
040 * @see org.apache.commons.net.ftp.FTPClient#createFileList
041 * @see org.apache.commons.net.ftp.FTPFileIterator
042 * @see org.apache.commons.net.ftp.FTPFileEntryParser
043 * @see org.apache.commons.net.ftp.FTPListParseEngine
044 * @deprecated This class is deprecated as of version 1.2 and will be
045 * removed in version 2.0 -- use FTPFileParseEngine instead.
046 */
047 public class FTPFileList
048 {
049 /**
050 * storage for the raw lines of input read from the FTP server
051 */
052 private LinkedList lines = null;
053 /**
054 * the FTPFileEntryParser assigned to be used with this lister
055 */
056 private FTPFileEntryParser parser;
057 /**
058 * private status code for an empty directory
059 */
060 private static final int EMPTY_DIR = -2;
061
062 /**
063 * The only constructor for FTPFileList, private because
064 * construction only invoked at create()
065 *
066 * @param parser a <code>FTPFileEntryParser</code> value that knows
067 * how to parse the entries returned by a particular FTP site.
068 * @param encoding The encoding to use.
069 */
070 private FTPFileList (FTPFileEntryParser parser, String encoding)
071 {
072 this.parser = parser;
073 this.lines = new LinkedList();
074 }
075
076 /**
077 * The only way to create an <code>FTPFileList</code> object. Invokes
078 * the private constructor and then reads the stream supplied stream to
079 * build the intermediate array of "lines" which will later be parsed
080 * into <code>FTPFile</code> object.
081 *
082 * @param stream The input stream created by reading the socket on which
083 * the output of the LIST command was returned
084 * @param parser the default <code>FTPFileEntryParser</code> to be used
085 * by this object. This may later be changed using the init() method.
086 * @param encoding The encoding to use
087 *
088 * @return the <code>FTPFileList</code> created, with an initialized
089 * of unparsed lines of output. Will be null if the listing cannot
090 * be read from the stream.
091 * @exception IOException
092 * Thrown on any failure to read from the socket.
093 */
094 public static FTPFileList create(InputStream stream,
095 FTPFileEntryParser parser,
096 String encoding)
097 throws IOException
098 {
099 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 */