%line	%branch
org.apache.commons.net.ftp.FTPFileIterator	0%	0%

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;
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 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	0	private int itemptr = 0;
62
63		/**
64		* number within <code>rawlines</code> of the first valid file entry.
65		*/
66	0	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	0	this(rawlist, rawlist.getParser());
78	0	}
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	0	{
91	0	this.rawlines = rawlist.getLines();
92	0	this.parser = parser;
93	0	}
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 entry)
106		{
107	0	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	0	FTPFile entry = null;
121	0	for (int iter = 0; iter < this.rawlines.size(); iter++)
122		{
123	0	String line = (String) this.rawlines.get(iter);
124	0	entry = parseFTPEntry(line);
125	0	if (null != entry)
126		{
127	0	return iter;
128		}
129		}
130	0	return DIREMPTY;
131		}
132
133		/**
134		* resets iterator to the beginning of the list.
135		*/
136		private void init()
137		{
138	0	this.itemptr = 0;
139	0	this.firstGoodEntry = UNINIT;
140	0	}
141
142		/**
143		* shorthand for an empty return value.
144		*/
145	0	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	0	if (this.itemptr != DIREMPTY)
157		{
158	0	init();
159		}
160	0	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	0	if (this.firstGoodEntry == UNINIT)
189		{
190	0	this.firstGoodEntry = getFirstGoodEntry();
191		}
192	0	if (this.firstGoodEntry == DIREMPTY)
193		{
194	0	return EMPTY;
195		}
196
197	0	int max = this.rawlines.size() - class="keyword">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	0	int howMany = (quantityRequested == 0) ? max : quantityRequested;
203	0	howMany = (howMany + this.itemptr < class="keyword">this.rawlines.size())
204		? howMany
205		: this.rawlines.size() - class="keyword">this.itemptr;
206
207	0	FTPFile[] output = new FTPFile[howMany];
208
209	0	for (int i = 0, e = this.firstGoodEntry + class="keyword">this.itemptr ;
210	0	i < howMany; i++, e++)
211		{
212	0	output[i] = parseFTPEntry((String) this.rawlines.get(e));
213	0	this.itemptr++;
214		}
215	0	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	0	int fge = this.firstGoodEntry;
228	0	if (fge == DIREMPTY)
229		{
230		//directory previously found empty - return false
231	0	return false;
232		}
233	0	else if (fge < 0)
234		{
235		// we haven't scanned the list yet so do it first
236	0	fge = getFirstGoodEntry();
237		}
238	0	return fge + this.itemptr < class="keyword">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	0	FTPFile[] file = getNext(1);
255	0	if (file.length > 0)
256		{
257	0	return file[0];
258		}
259		else
260		{
261	0	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	0	int howMany = quantityRequested;
288		// can't retreat further than we've previously advanced
289	0	if (howMany > this.itemptr)
290		{
291	0	howMany = this.itemptr;
292		}
293	0	FTPFile[] output = new FTPFile[howMany];
294	0	for (int i = howMany, e = this.firstGoodEntry + class="keyword">this.itemptr; i > 0;)
295		{
296	0	output[--i] = parseFTPEntry((String) this.rawlines.get(--e));
297	0	this.itemptr--;
298		}
299	0	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	0	int fge = this.firstGoodEntry;
312	0	if (fge == DIREMPTY)
313		{
314		//directory previously found empty - return false
315	0	return false;
316		}
317	0	else if (fge < 0)
318		{
319		// we haven't scanned the list yet so do it first
320	0	fge = getFirstGoodEntry();
321		}
322
323	0	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	0	FTPFile[] file = getPrevious(1);
340	0	if (file.length > 0)
341		{
342	0	return file[0];
343		}
344		else
345		{
346	0	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		*/

This report is generated by jcoverage, Maven and Maven JCoverage Plugin.