001: /*
002: * Copyright 2001-2005 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.net.ftp;
017:
018: import java.io.BufferedReader;
019: import java.io.IOException;
020: import java.io.InputStream;
021: import java.io.InputStreamReader;
022: import java.util.LinkedList;
023: import java.util.List;
024:
025: /**
026: * This class encapsulates a listing of files from an FTP server. It is
027: * initialized with an input stream which is read and the input split into
028: * lines, each of which (after some possible initial verbiage) represents
029: * a file on the FTP server. A parser is also supplied, which is used to
030: * iterate through the internal list of lines parsing each into an FTPFile
031: * object which is returned to the caller of the iteration methods. This
032: * parser may be replaced with another, allowing the same list to be parsed
033: * with different parsers.
034: * Parsing takes place on an as-needed basis, basically, the first time a
035: * position is iterated over. This happens at the time of iteration, not
036: * prior to it as the older <code>(FTPClient.listFiles()</code> methods did,
037: * which required a bigger memory hit.
038: *
039: * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
040: * @version $Id: FTPFileList.java 165675 2005-05-02 20:09:55Z rwinston $
041: * @see org.apache.commons.net.ftp.FTPClient#createFileList
042: * @see org.apache.commons.net.ftp.FTPFileIterator
043: * @see org.apache.commons.net.ftp.FTPFileEntryParser
044: * @see org.apache.commons.net.ftp.FTPListParseEngine
045: * @deprecated This class is deprecated as of version 1.2 and will be
046: * removed in version 2.0 -- use FTPFileParseEngine instead.
047: */
048: public class FTPFileList {
049: /**
050: * storage for the raw lines of input read from the FTP server
051: */
052: private LinkedList lines = null;
053: /**
054: * the FTPFileEntryParser assigned to be used with this lister
055: */
056: private FTPFileEntryParser parser;
057: /**
058: * private status code for an empty directory
059: */
060: private static final int EMPTY_DIR = -2;
061:
062: /**
063: * The only constructor for FTPFileList, private because
064: * construction only invoked at create()
065: *
066: * @param parser a <code>FTPFileEntryParser</code> value that knows
067: * how to parse the entries returned by a particular FTP site.
068: * @param encoding The encoding to use.
069: */
070: private FTPFileList(FTPFileEntryParser parser, String encoding) {
071: this .parser = parser;
072: this .lines = new LinkedList();
073: }
074:
075: /**
076: * The only way to create an <code>FTPFileList</code> object. Invokes
077: * the private constructor and then reads the stream supplied stream to
078: * build the intermediate array of "lines" which will later be parsed
079: * into <code>FTPFile</code> object.
080: *
081: * @param stream The input stream created by reading the socket on which
082: * the output of the LIST command was returned
083: * @param parser the default <code>FTPFileEntryParser</code> to be used
084: * by this object. This may later be changed using the init() method.
085: * @param encoding The encoding to use
086: *
087: * @return the <code>FTPFileList</code> created, with an initialized
088: * of unparsed lines of output. Will be null if the listing cannot
089: * be read from the stream.
090: * @exception IOException
091: * Thrown on any failure to read from the socket.
092: */
093: public static FTPFileList create(InputStream stream,
094: FTPFileEntryParser parser, String encoding)
095: throws IOException {
096: FTPFileList list = new FTPFileList(parser, encoding);
097: list.readStream(stream, encoding);
098: parser.preParse(list.lines);
099: return list;
100: }
101:
102: /**
103: * The only way to create an <code>FTPFileList</code> object. Invokes
104: * the private constructor and then reads the stream supplied stream to
105: * build the intermediate array of "lines" which will later be parsed
106: * into <code>FTPFile</code> object.
107: *
108: * @param stream The input stream created by reading the socket on which
109: * the output of the LIST command was returned
110: * @param parser the default <code>FTPFileEntryParser</code> to be used
111: * by this object. This may later be changed using the init() method.
112: *
113: * @return the <code>FTPFileList</code> created, with an initialized
114: * of unparsed lines of output. Will be null if the listing cannot
115: * be read from the stream.
116: * @exception IOException
117: * Thrown on any failure to read from the socket.
118: *
119: * @deprecated The version of this method which takes an encoding should be used.
120: */
121: public static FTPFileList create(InputStream stream,
122: FTPFileEntryParser parser) throws IOException {
123: return create(stream, parser, null);
124: }
125:
126: /**
127: * internal method for reading the input into the <code>lines</code> vector.
128: *
129: * @param stream The socket stream on which the input will be read.
130: * @param encoding The encoding to use.
131: *
132: * @exception IOException thrown on any failure to read the stream
133: */
134: public void readStream(InputStream stream, String encoding)
135: throws IOException {
136: BufferedReader reader = new BufferedReader(
137: new InputStreamReader(stream, encoding));
138:
139: String line = this .parser.readNextEntry(reader);
140:
141: while (line != null) {
142: this .lines.add(line);
143: line = this .parser.readNextEntry(reader);
144: }
145: reader.close();
146: }
147:
148: /**
149: * internal method for reading the input into the <code>lines</code> vector.
150: *
151: * @param stream The socket stream on which the input will be read.
152: *
153: * @exception IOException thrown on any failure to read the stream
154: *
155: * @deprecated The version of this method which takes an encoding should be used.
156: */
157: public void readStream(InputStream stream) throws IOException {
158: readStream(stream, null);
159: }
160:
161: /**
162: * Accessor for this object's default parser.
163: *
164: * @return this object's default parser.
165: */
166: FTPFileEntryParser getParser() {
167: return this .parser;
168: }
169:
170: /**
171: * Package private accessor for the collection of raw input lines.
172: *
173: * @return vector containing all the raw input lines returned from the FTP
174: * server
175: */
176: List getLines() {
177: return this .lines;
178: }
179:
180: /**
181: * create an iterator over this list using the parser with which this list
182: * was initally created
183: *
184: * @return an iterator over this list using the list's default parser.
185: */
186: public FTPFileIterator iterator() {
187: return new FTPFileIterator(this );
188: }
189:
190: /**
191: * create an iterator over this list using the supplied parser
192: *
193: * @param parser The user-supplied parser with which the list is to be
194: * iterated, may be different from this list's default parser.
195: *
196: * @return an iterator over this list using the supplied parser.
197: */
198: public FTPFileIterator iterator(FTPFileEntryParser parser) {
199: return new FTPFileIterator(this , parser);
200: }
201:
202: /**
203: * returns an array of FTPFile objects for all the files in the directory
204: * listing
205: *
206: * @return an array of FTPFile objects for all the files in the directory
207: * listinge
208: */
209: public FTPFile[] getFiles() {
210: return iterator().getFiles();
211: }
212:
213: }
214:
215: /* Emacs configuration
216: * Local variables: **
217: * mode: java **
218: * c-basic-offset: 4 **
219: * indent-tabs-mode: nil **
220: * End: **
221: */
|