001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.net.ftp;
019
020 import java.io.BufferedReader;
021 import java.io.IOException;
022 import java.io.InputStream;
023 import java.io.InputStreamReader;
024 import java.util.ArrayList;
025 import java.util.Iterator;
026 import java.util.LinkedList;
027 import java.util.List;
028 import java.util.ListIterator;
029
030
031 /**
032 * This class handles the entire process of parsing a listing of
033 * file entries from the server.
034 * <p>
035 * This object defines a two-part parsing mechanism.
036 * <p>
037 * The first part is comprised of reading the raw input into an internal
038 * list of strings. Every item in this list corresponds to an actual
039 * file. All extraneous matter emitted by the server will have been
040 * removed by the end of this phase. This is accomplished in conjunction
041 * with the FTPFileEntryParser associated with this engine, by calling
042 * its methods <code>readNextEntry()</code> - which handles the issue of
043 * what delimits one entry from another, usually but not always a line
044 * feed and <code>preParse()</code> - which handles removal of
045 * extraneous matter such as the preliminary lines of a listing, removal
046 * of duplicates on versioning systems, etc.
047 * <p>
048 * The second part is composed of the actual parsing, again in conjunction
049 * with the particular parser used by this engine. This is controlled
050 * by an iterator over the internal list of strings. This may be done
051 * either in block mode, by calling the <code>getNext()</code> and
052 * <code>getPrevious()</code> methods to provide "paged" output of less
053 * than the whole list at one time, or by calling the
054 * <code>getFiles()</code> method to return the entire list.
055 * <p>
056 * Examples:
057 * <p>
058 * Paged access:
059 * <pre>
060 * FTPClient f=FTPClient();
061 * f.connect(server);
062 * f.login(username, password);
063 * FTPListParseEngine engine = f.initiateListParsing(directory);
064 *
065 * while (engine.hasNext()) {
066 * FTPFile[] files = engine.getNext(25); // "page size" you want
067 * //do whatever you want with these files, display them, etc.
068 * //expensive FTPFile objects not created until needed.
069 * }
070 * </pre>
071 * <p>
072 * For unpaged access, simply use FTPClient.listFiles(). That method
073 * uses this class transparently.
074 * @version $Id: FTPListParseEngine.java 1085209 2011-03-25 00:08:04Z sebb $
075 */
076 public class FTPListParseEngine {
077 private List<String> entries = new LinkedList<String>();
078 private ListIterator<String> _internalIterator = entries.listIterator();
079
080 private final FTPFileEntryParser parser;
081
082 public FTPListParseEngine(FTPFileEntryParser parser) {
083 this.parser = parser;
084 }
085
086 /**
087 * handle the initial reading and preparsing of the list returned by
088 * the server. After this method has completed, this object will contain
089 * a list of unparsed entries (Strings) each referring to a unique file
090 * on the server.
091 *
092 * @param stream input stream provided by the server socket.
093 *
094 * @exception IOException
095 * thrown on any failure to read from the sever.
096 */
097 public void readServerList(InputStream stream, String encoding)
098 throws IOException
099 {
100 this.entries = new LinkedList<String>();
101 readStream(stream, encoding);
102 this.parser.preParse(this.entries);
103 resetIterator();
104 }
105
106 /**
107 * Internal method for reading the input into the <code>entries</code> list.
108 * After this method has completed, <code>entries</code> will contain a
109 * collection of entries (as defined by
110 * <code>FTPFileEntryParser.readNextEntry()</code>), but this may contain
111 * various non-entry preliminary lines from the server output, duplicates,
112 * and other data that will not be part of the final listing.
113 *
114 * @param stream The socket stream on which the input will be read.
115 * @param encoding The encoding to use.
116 *
117 * @exception IOException
118 * thrown on any failure to read the stream
119 */
120 private void readStream(InputStream stream, String encoding) throws IOException
121 {
122 BufferedReader reader;
123 if (encoding == null)
124 {
125 reader = new BufferedReader(new InputStreamReader(stream));
126 }
127 else
128 {
129 reader = new BufferedReader(new InputStreamReader(stream, encoding));
130 }
131
132 String line = this.parser.readNextEntry(reader);
133
134 while (line != null)
135 {
136 this.entries.add(line);
137 line = this.parser.readNextEntry(reader);
138 }
139 reader.close();
140 }
141
142 /**
143 * Returns an array of at most <code>quantityRequested</code> FTPFile
144 * objects starting at this object's internal iterator's current position.
145 * If fewer than <code>quantityRequested</code> such
146 * elements are available, the returned array will have a length equal
147 * to the number of entries at and after after the current position.
148 * If no such entries are found, this array will have a length of 0.
149 *
150 * After this method is called this object's internal iterator is advanced
151 * by a number of positions equal to the size of the array returned.
152 *
153 * @param quantityRequested
154 * the maximum number of entries we want to get.
155 *
156 * @return an array of at most <code>quantityRequested</code> FTPFile
157 * objects starting at the current position of this iterator within its
158 * list and at least the number of elements which exist in the list at
159 * and after its current position.
160 * <p><b>
161 * NOTE:</b> This array may contain null members if any of the
162 * individual file listings failed to parse. The caller should
163 * check each entry for null before referencing it.
164 */
165 public FTPFile[] getNext(int quantityRequested) {
166 List<FTPFile> tmpResults = new LinkedList<FTPFile>();
167 int count = quantityRequested;
168 while (count > 0 && this._internalIterator.hasNext()) {
169 String entry = this._internalIterator.next();
170 FTPFile temp = this.parser.parseFTPEntry(entry);
171 tmpResults.add(temp);
172 count--;
173 }
174 return tmpResults.toArray(new FTPFile[tmpResults.size()]);
175
176 }
177
178 /**
179 * Returns an array of at most <code>quantityRequested</code> FTPFile
180 * objects starting at this object's internal iterator's current position,
181 * and working back toward the beginning.
182 *
183 * If fewer than <code>quantityRequested</code> such
184 * elements are available, the returned array will have a length equal
185 * to the number of entries at and after after the current position.
186 * If no such entries are found, this array will have a length of 0.
187 *
188 * After this method is called this object's internal iterator is moved
189 * back by a number of positions equal to the size of the array returned.
190 *
191 * @param quantityRequested
192 * the maximum number of entries we want to get.
193 *
194 * @return an array of at most <code>quantityRequested</code> FTPFile
195 * objects starting at the current position of this iterator within its
196 * list and at least the number of elements which exist in the list at
197 * and after its current position. This array will be in the same order
198 * as the underlying list (not reversed).
199 * <p><b>
200 * NOTE:</b> This array may contain null members if any of the
201 * individual file listings failed to parse. The caller should
202 * check each entry for null before referencing it.
203 */
204 public FTPFile[] getPrevious(int quantityRequested) {
205 List<FTPFile> tmpResults = new LinkedList<FTPFile>();
206 int count = quantityRequested;
207 while (count > 0 && this._internalIterator.hasPrevious()) {
208 String entry = this._internalIterator.previous();
209 FTPFile temp = this.parser.parseFTPEntry(entry);
210 tmpResults.add(0,temp);
211 count--;
212 }
213 return tmpResults.toArray(new FTPFile[tmpResults.size()]);
214 }
215
216 /**
217 * Returns an array of FTPFile objects containing the whole list of
218 * files returned by the server as read by this object's parser.
219 *
220 * @return an array of FTPFile objects containing the whole list of
221 * files returned by the server as read by this object's parser.
222 * None of the entries will be null
223 * @exception IOException
224 */
225 public FTPFile[] getFiles()
226 throws IOException
227 {
228 return getFiles(FTPFileFilters.NON_NULL);
229 }
230
231 /**
232 * Returns an array of FTPFile objects containing the whole list of
233 * files returned by the server as read by this object's parser.
234 * The files are filtered before being added to the array.
235 *
236 * @param filter FTPFileFilter, must not be <code>null</code>.
237 *
238 * @return an array of FTPFile objects containing the whole list of
239 * files returned by the server as read by this object's parser.
240 * <p><b>
241 * NOTE:</b> This array may contain null members if any of the
242 * individual file listings failed to parse. The caller should
243 * check each entry for null before referencing it, or use the
244 * a filter such as {@link FTPFileFilters#NON_NULL} which does not
245 * allow null entries.
246 * @since 2.2
247 * @exception IOException
248 */
249 public FTPFile[] getFiles(FTPFileFilter filter)
250 throws IOException
251 {
252 List<FTPFile> tmpResults = new ArrayList<FTPFile>();
253 Iterator<String> iter = this.entries.iterator();
254 while (iter.hasNext()) {
255 String entry = iter.next();
256 FTPFile temp = this.parser.parseFTPEntry(entry);
257 if (filter.accept(temp)){
258 tmpResults.add(temp);
259 }
260 }
261 return tmpResults.toArray(new FTPFile[tmpResults.size()]);
262
263 }
264
265 /**
266 * convenience method to allow clients to know whether this object's
267 * internal iterator's current position is at the end of the list.
268 *
269 * @return true if internal iterator is not at end of list, false
270 * otherwise.
271 */
272 public boolean hasNext() {
273 return _internalIterator.hasNext();
274 }
275
276 /**
277 * convenience method to allow clients to know whether this object's
278 * internal iterator's current position is at the beginning of the list.
279 *
280 * @return true if internal iterator is not at beginning of list, false
281 * otherwise.
282 */
283 public boolean hasPrevious() {
284 return _internalIterator.hasPrevious();
285 }
286
287 /**
288 * resets this object's internal iterator to the beginning of the list.
289 */
290 public void resetIterator() {
291 this._internalIterator = this.entries.listIterator();
292 }
293
294 // DEPRECATED METHODS - for API compatibility only - DO NOT USE
295
296 /**
297 * Do not use.
298 * @deprecated use {@link #readServerList(InputStream, String)} instead
299 */
300 @Deprecated
301 public void readServerList(InputStream stream)
302 throws IOException
303 {
304 readServerList(stream, null);
305 }
306
307 }