%line	%branch
org.apache.commons.net.ftp.FTPListParseEngine	56%	78%

1		/*
2		* Copyright 2004 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
18		import java.io.BufferedReader;
19		import java.io.IOException;
20		import java.io.InputStream;
21		import java.io.InputStreamReader;
22		import java.util.Iterator;
23		import java.util.LinkedList;
24		import java.util.List;
25		import java.util.ListIterator;
26
27
28		/**
29		* This class handles the entire process of parsing a listing of
30		* file entries from the server.
31		* <p>
32		* This object defines a two-part parsing mechanism.
33		* <p>
34		* The first part is comprised of reading the raw input into an internal
35		* list of strings. Every item in this list corresponds to an actual
36		* file. All extraneous matter emitted by the server will have been
37		* removed by the end of this phase. This is accomplished in conjunction
38		* with the FTPFileEntryParser associated with this engine, by calling
39		* its methods <code>readNextEntry()</code> - which handles the issue of
40		* what delimits one entry from another, usually but not always a line
41		* feed and <code>preParse()</code> - which handles removal of
42		* extraneous matter such as the preliminary lines of a listing, removal
43		* of duplicates on versioning systems, etc.
44		* <p>
45		* The second part is composed of the actual parsing, again in conjunction
46		* with the particular parser used by this engine. This is controlled
47		* by an iterator over the internal list of strings. This may be done
48		* either in block mode, by calling the <code>getNext()</code> and
49		* <code>getPrevious()</code> methods to provide "paged" output of less
50		* than the whole list at one time, or by calling the
51		* <code>getFiles()</code> method to return the entire list.
52		* <p>
53		* Examples:
54		* <p>
55		* Paged access:
56		* <pre>
57		* FTPClient f=FTPClient();
58		* f.connect(server);
59		* f.login(username, password);
60		* FTPListParseEngine engine = f.initiateListParsing(directory);
61		*
62		* while (engine.hasNext()) {
63		* FTPFile[] files = engine.getNext(25); // "page size" you want
64		* //do whatever you want with these files, display them, etc.
65		* //expensive FTPFile objects not created until needed.
66		* }
67		* </pre>
68		* <p>
69		* For unpaged access, simply use FTPClient.listFiles(). That method
70		* uses this class transparently.
71		* @version $Id: FTPListParseEngine.java 155429 2005-02-26 13:13:04Z dirkv $
72		*/
73		public class FTPListParseEngine {
74	4	private List entries = new LinkedList();
75	4	private ListIterator _internalIterator = entries.listIterator();
76
77	4	FTPFileEntryParser parser = null;
78
79	4	public FTPListParseEngine(FTPFileEntryParser parser) {
80	4	this.parser = parser;
81	4	}
82
83		/**
84		* handle the iniitial reading and preparsing of the list returned by
85		* the server. After this method has completed, this object will contain
86		* a list of unparsed entries (Strings) each referring to a unique file
87		* on the server.
88		*
89		* @param stream input stream provided by the server socket.
90		*
91		* @exception IOException
92		* thrown on any failure to read from the sever.
93		*/
94		public void readServerList(InputStream stream, String encoding)
95		throws IOException
96		{
97	4	this.entries = new LinkedList();
98	4	readStream(stream, encoding);
99	4	this.parser.preParse(class="keyword">this.entries);
100	4	resetIterator();
101	4	}
102
103		/**
104		* handle the iniitial reading and preparsing of the list returned by
105		* the server. After this method has completed, this object will contain
106		* a list of unparsed entries (Strings) each referring to a unique file
107		* on the server.
108		*
109		* @param stream input stream provided by the server socket.
110		*
111		* @exception IOException
112		* thrown on any failure to read from the sever.
113		*
114		* @deprecated The version of this method which takes an encoding should be used.
115		*/
116		public void readServerList(InputStream stream)
117		throws IOException
118		{
119	4	readServerList(stream, null);
120	4	}
121
122
123
124		/**
125		* Internal method for reading the input into the <code>entries</code> list.
126		* After this method has completed, <code>entries</code> will contain a
127		* collection of entries (as defined by
128		* <code>FTPFileEntryParser.readNextEntry()</code>), but this may contain
129		* various non-entry preliminary lines from the server output, duplicates,
130		* and other data that will not be part of the final listing.
131		*
132		* @param stream The socket stream on which the input will be read.
133		* @param encoding The encoding to use.
134		*
135		* @exception IOException
136		* thrown on any failure to read the stream
137		*/
138		private void readStream(InputStream stream, String encoding) throws IOException
139		{
140		BufferedReader reader;
141	4	if (encoding == null)
142		{
143	4	reader = new BufferedReader(class="keyword">new InputStreamReader(stream));
144		}
145		else
146		{
147	0	reader = new BufferedReader(class="keyword">new InputStreamReader(stream, encoding));
148		}
149
150	4	String line = this.parser.readNextEntry(reader);
151
152	28	while (line != null)
153		{
154	24	this.entries.add(line);
155	24	line = this.parser.readNextEntry(reader);
156		}
157	4	reader.close();
158	4	}
159
160		/**
161		* Returns an array of at most <code>quantityRequested</code> FTPFile
162		* objects starting at this object's internal iterator's current position.
163		* If fewer than <code>quantityRequested</code> such
164		* elements are available, the returned array will have a length equal
165		* to the number of entries at and after after the current position.
166		* If no such entries are found, this array will have a length of 0.
167		*
168		* After this method is called this object's internal iterator is advanced
169		* by a number of positions equal to the size of the array returned.
170		*
171		* @param quantityRequested
172		* the maximum number of entries we want to get.
173		*
174		* @return an array of at most <code>quantityRequested</code> FTPFile
175		* objects starting at the current position of this iterator within its
176		* list and at least the number of elements which exist in the list at
177		* and after its current position.
178		* <p><b>
179		* NOTE:</b> This array may contain null members if any of the
180		* individual file listings failed to parse. The caller should
181		* check each entry for null before referencing it.
182		*/
183		public FTPFile[] getNext(int quantityRequested) {
184	0	List tmpResults = new LinkedList();
185	0	int count = quantityRequested;
186	0	while (count > 0 && this._internalIterator.hasNext()) {
187	0	String entry = (String) this._internalIterator.next();
188	0	FTPFile temp = this.parser.parseFTPEntry(entry);
189	0	tmpResults.add(temp);
190	0	count--;
191		}
192	0	return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
193
194		}
195
196		/**
197		* Returns an array of at most <code>quantityRequested</code> FTPFile
198		* objects starting at this object's internal iterator's current position,
199		* and working back toward the beginning.
200		*
201		* If fewer than <code>quantityRequested</code> such
202		* elements are available, the returned array will have a length equal
203		* to the number of entries at and after after the current position.
204		* If no such entries are found, this array will have a length of 0.
205		*
206		* After this method is called this object's internal iterator is moved
207		* back by a number of positions equal to the size of the array returned.
208		*
209		* @param quantityRequested
210		* the maximum number of entries we want to get.
211		*
212		* @return an array of at most <code>quantityRequested</code> FTPFile
213		* objects starting at the current position of this iterator within its
214		* list and at least the number of elements which exist in the list at
215		* and after its current position. This array will be in the same order
216		* as the underlying list (not reversed).
217		* <p><b>
218		* NOTE:</b> This array may contain null members if any of the
219		* individual file listings failed to parse. The caller should
220		* check each entry for null before referencing it.
221		*/
222		public FTPFile[] getPrevious(int quantityRequested) {
223	0	List tmpResults = new LinkedList();
224	0	int count = quantityRequested;
225	0	while (count > 0 && this._internalIterator.hasPrevious()) {
226	0	String entry = (String) this._internalIterator.previous();
227	0	FTPFile temp = this.parser.parseFTPEntry(entry);
228	0	tmpResults.add(0,temp);
229	0	count--;
230		}
231	0	return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
232		}
233
234		/**
235		* Returns an array of FTPFile objects containing the whole list of
236		* files returned by the server as read by this object's parser.
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.
244		* @exception IOException
245		*/
246		public FTPFile[] getFiles()
247		throws IOException
248		{
249	4	List tmpResults = new LinkedList();
250	4	Iterator iter = this.entries.iterator();
251	22	while (iter.hasNext()) {
252	18	String entry = (String) iter.next();
253	18	FTPFile temp = this.parser.parseFTPEntry(entry);
254	18	tmpResults.add(temp);
255		}
256	4	return (FTPFile[]) tmpResults.toArray(new FTPFile[0]);
257
258		}
259
260		/**
261		* convenience method to allow clients to know whether this object's
262		* internal iterator's current position is at the end of the list.
263		*
264		* @return true if internal iterator is not at end of list, false
265		* otherwise.
266		*/
267		public boolean hasNext() {
268	0	return _internalIterator.hasNext();
269		}
270
271		/**
272		* convenience method to allow clients to know whether this object's
273		* internal iterator's current position is at the beginning of the list.
274		*
275		* @return true if internal iterator is not at beginning of list, false
276		* otherwise.
277		*/
278		public boolean hasPrevious() {
279	0	return _internalIterator.hasPrevious();
280		}
281
282		/**
283		* resets this object's internal iterator to the beginning of the list.
284		*/
285		public void resetIterator() {
286	4	this._internalIterator = class="keyword">this.entries.listIterator();
287	4	}
288		}

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