KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > net > ftp > FTPFileIterator


1 /*
2  * Copyright 2001-2005 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 package org.apache.commons.net.ftp;
17 import java.util.List JavaDoc;
18
19 /**
20  * This class implements a bidirectional iterator over an FTPFileList.
21  * Elements may be retrieved one at at time using the hasNext() - next()
22  * syntax familiar from Java 2 collections. Alternatively, entries may
23  * be receieved as an array of any requested number of entries or all of them.
24  *
25  * @author <a HREF="mailto:scohen@apache.org">Steve Cohen</a>
26  * @version $Id: FTPFileIterator.java 165675 2005-05-02 20:09:55Z rwinston $
27  * @see org.apache.commons.net.ftp.FTPFileList
28  * @see org.apache.commons.net.ftp.FTPFileEntryParser
29  * @see org.apache.commons.net.ftp.FTPListParseEngine
30  * @deprecated This class is deprecated as of version 1.2 and will be
31  * removed in version 2.0 - use FTPFileParseEngine instead
32  */

33 public class FTPFileIterator
34 {
35     /**
36      * a vector of strings, each representing a possibly valid ftp file
37      * entry
38      */

39     private List JavaDoc rawlines;
40
41     /**
42      * the parser to which this iterator delegates its parsing duties
43      */

44     private FTPFileEntryParser parser;
45
46     /**
47      * constant shorthand for the situation where the raw listing has not
48      * yet been scanned
49      */

50     private static final int UNINIT = -1;
51
52     /**
53      * constant shorthand for the situation where the raw listing has been
54      * scanned and found to have no valid entry.
55      */

56     private static final int DIREMPTY = -2;
57
58     /**
59      * this iterator's current position within <code>rawlines</code>.
60      */

61     private int itemptr = 0;
62
63     /**
64      * number within <code>rawlines</code> of the first valid file entry.
65      */

66     private int firstGoodEntry = UNINIT;
67
68     /**
69      * "Package-private" constructor. Only the FTPFileList can
70      * create an iterator, using it's iterator() method. The list
71      * will be iterated with the list's default parser.
72      *
73      * @param rawlist the FTPFileList to be iterated
74      */

75     FTPFileIterator (FTPFileList rawlist)
76     {
77         this(rawlist, rawlist.getParser());
78     }
79
80     /**
81      * "Package-private" constructor. Only the FTPFileList can
82      * create an iterator, using it's iterator() method. The list will be
83      * iterated with a supplied parser
84      *
85      * @param rawlist the FTPFileList to be iterated
86      * @param parser the system specific parser for raw FTP entries.
87      */

88     FTPFileIterator (FTPFileList rawlist,
89                             FTPFileEntryParser parser)
90     {
91         this.rawlines = rawlist.getLines();
92         this.parser = parser;
93     }
94
95     /**
96      * Delegates to this object's parser member the job of parsing an
97      * entry.
98      *
99      * @param entry A string containing one entry, as determined by the
100      * parser's getNextEntry() method.
101      *
102      * @return an FTPFile object representing this entry or null if it can't be
103      * parsed as a file
104      */

105     private FTPFile parseFTPEntry(String JavaDoc entry)
106     {
107         return this.parser.parseFTPEntry(entry);
108     }
109
110     /**
111      * Skips over any introductory lines and stuff in the listing that does
112      * not represent files, returning the line number of the first entry
113      * that does represent a file.
114      *
115      * @return the line number within <code>rawlines</code> of the first good
116      * entry in the array or DIREMPTY if there are no good entries.
117      */

118     private int getFirstGoodEntry()
119     {
120         FTPFile entry = null;
121         for (int iter = 0; iter < this.rawlines.size(); iter++)
122         {
123             String JavaDoc line = (String JavaDoc) this.rawlines.get(iter);
124             entry = parseFTPEntry(line);
125             if (null != entry)
126             {
127                 return iter;
128             }
129         }
130         return DIREMPTY;
131     }
132
133     /**
134      * resets iterator to the beginning of the list.
135      */

136     private void init()
137     {
138         this.itemptr = 0;
139         this.firstGoodEntry = UNINIT;
140     }
141
142     /**
143      * shorthand for an empty return value.
144      */

145     private static final FTPFile[] EMPTY = new FTPFile[0];
146
147     /**
148      * Returns a list of FTPFile objects for ALL files listed in the server's
149      * LIST output.
150      *
151      * @return a list of FTPFile objects for ALL files listed in the server's
152      * LIST output.
153      */

154     public FTPFile[] getFiles()
155     {
156         if (this.itemptr != DIREMPTY)
157         {
158             init();
159         }
160         return getNext(0);
161     }
162
163     /**
164      * Returns an array of at most <code>quantityRequested</code> FTPFile
165      * objects starting at this iterator's current position within its
166      * associated list. If fewer than <code>quantityRequested</code> such
167      * elements are available, the returned array will have a length equal
168      * to the number of entries at and after after the current position.
169      * If no such entries are found, this array will have a length of 0.
170      *
171      * After this method is called the current position is advanced by
172      * either <code>quantityRequested</code> or the number of entries
173      * available after the iterator, whichever is fewer.
174      *
175      * @param quantityRequested
176      * the maximum number of entries we want to get. A 0
177      * passed here is a signal to get ALL the entries.
178      *
179      * @return an array of at most <code>quantityRequested</code> FTPFile
180      * objects starting at the current position of this iterator within its
181      * list and at least the number of elements which exist in the list at
182      * and after its current position.
183      */

184     public FTPFile[] getNext(int quantityRequested)
185     {
186
187         // if we haven't gotten past the initial junk do so.
188
if (this.firstGoodEntry == UNINIT)
189         {
190             this.firstGoodEntry = getFirstGoodEntry();
191         }
192         if (this.firstGoodEntry == DIREMPTY)
193         {
194             return EMPTY;
195         }
196
197         int max = this.rawlines.size() - this.firstGoodEntry;
198
199         // now that we know the maximum we can possibly get,
200
// resolve a 0 request to ask for that many.
201

202         int howMany = (quantityRequested == 0) ? max : quantityRequested;
203         howMany = (howMany + this.itemptr < this.rawlines.size())
204                    ? howMany
205                    : this.rawlines.size() - this.itemptr;
206
207         FTPFile[] output = new FTPFile[howMany];
208
209         for (int i = 0, e = this.firstGoodEntry + this.itemptr ;
210                 i < howMany; i++, e++)
211         {
212             output[i] = parseFTPEntry((String JavaDoc) this.rawlines.get(e));
213             this.itemptr++;
214         }
215         return output;
216     }
217
218     /**
219      * Method for determining whether getNext() will successfully return a
220      * non-null value.
221      *
222      * @return true if there exist any files after the one currently pointed
223      * to by the internal iterator, false otherwise.
224      */

225     public boolean hasNext()
226     {
227         int fge = this.firstGoodEntry;
228         if (fge == DIREMPTY)
229         {
230             //directory previously found empty - return false
231
return false;
232         }
233         else if (fge < 0)
234         {
235             // we haven't scanned the list yet so do it first
236
fge = getFirstGoodEntry();
237         }
238         return fge + this.itemptr < this.rawlines.size();
239     }
240
241     /**
242      * Returns a single parsed FTPFile object corresponding to the raw input
243      * line at this iterator's current position.
244      *
245      * After this method is called the internal iterator is advanced by one
246      * element (unless already at end of list).
247      *
248      * @return a single FTPFile object corresponding to the raw input line
249      * at the position of the internal iterator over the list of raw input
250      * lines maintained by this object or null if no such object exists.
251      */

252     public FTPFile next()
253     {
254         FTPFile[] file = getNext(1);
255         if (file.length > 0)
256         {
257             return file[0];
258         }
259         else
260         {
261             return null;
262         }
263     }
264
265     /**
266      * Returns an array of at most <code>quantityRequested</code> FTPFile
267      * objects starting at the position preceding this iterator's current
268      * position within its associated list. If fewer than
269      * <code>quantityRequested</code> such elements are available, the
270      * returned array will have a length equal to the number of entries after
271      * the iterator. If no such entries are found, this array will have a
272      * length of 0. The entries will be ordered in the same order as the
273      * list, not reversed.
274      *
275      * After this method is called the current position is moved back by
276      * either <code>quantityRequested</code> or the number of entries
277      * available before the current position, whichever is fewer.
278      * @param quantityRequested the maximum number of entries we want to get.
279      * A 0 passed here is a signal to get ALL the entries.
280      * @return an array of at most <code>quantityRequested</code> FTPFile
281      * objects starting at the position preceding the current position of
282      * this iterator within its list and at least the number of elements which
283      * exist in the list prior to its current position.
284      */

285     public FTPFile[] getPrevious(int quantityRequested)
286     {
287         int howMany = quantityRequested;
288         // can't retreat further than we've previously advanced
289
if (howMany > this.itemptr)
290         {
291             howMany = this.itemptr;
292         }
293         FTPFile[] output = new FTPFile[howMany];
294         for (int i = howMany, e = this.firstGoodEntry + this.itemptr; i > 0;)
295         {
296             output[--i] = parseFTPEntry((String JavaDoc) this.rawlines.get(--e));
297             this.itemptr--;
298         }
299         return output;
300     }
301
302     /**
303      * Method for determining whether getPrevious() will successfully return a
304      * non-null value.
305      *
306      * @return true if there exist any files before the one currently pointed
307      * to by the internal iterator, false otherwise.
308      */

309     public boolean hasPrevious()
310     {
311         int fge = this.firstGoodEntry;
312         if (fge == DIREMPTY)
313         {
314             //directory previously found empty - return false
315
return false;
316         }
317         else if (fge < 0)
318         {
319             // we haven't scanned the list yet so do it first
320
fge = getFirstGoodEntry();
321         }
322
323         return this.itemptr > fge;
324     }
325
326     /**
327      * Returns a single parsed FTPFile object corresponding to the raw input
328      * line at the position preceding that of the internal iterator over
329      * the list of raw lines maintained by this object
330      *
331      * After this method is called the internal iterator is retreated by one
332      * element (unless it is already at beginning of list).
333      * @return a single FTPFile object corresponding to the raw input line
334      * at the position immediately preceding that of the internal iterator
335      * over the list of raw input lines maintained by this object.
336      */

337     public FTPFile previous()
338     {
339         FTPFile[] file = getPrevious(1);
340         if (file.length > 0)
341         {
342             return file[0];
343         }
344         else
345         {
346             return null;
347         }
348     }
349 }
350
351 /* Emacs configuration
352  * Local variables: **
353  * mode: java **
354  * c-basic-offset: 4 **
355  * indent-tabs-mode: nil **
356  * End: **
357  */

358
Popular Tags