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