1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.net.ftp;
17 import java.io.BufferedReader;
18 import java.io.IOException;
19 import java.util.List;
20
21 /**
22 * FTPFileEntryParser defines the interface for parsing a single FTP file
23 * listing and converting that information into an
24 * {@link org.apache.commons.net.ftp.FTPFile} instance.
25 * Sometimes you will want to parse unusual listing formats, in which
26 * case you would create your own implementation of FTPFileEntryParser and
27 * if necessary, subclass FTPFile.
28 * <p>
29 * Here are some examples showing how to use one of the classes that
30 * implement this interface.
31 * <p>
32 * The first example shows how to get an <b>iterable</b> list of files in which the
33 * more expensive <code>FTPFile</code> objects are not created until needed. This
34 * is suitable for paged displays. It requires that a parser object be created
35 * beforehand: <code>parser</code> is an object (in the package
36 * <code>org.apache.commons.net.ftp.parser</code>)
37 * implementing this inteface.
38 *
39 * <pre>
40 * FTPClient f=FTPClient();
41 * f.connect(server);
42 * f.login(username, password);
43 * FTPFileList list = f.createFileList(directory, parser);
44 * FTPFileIterator iter = list.iterator();
45 *
46 * while (iter.hasNext()) {
47 * FTPFile[] files = iter.getNext(25); // "page size" you want
48 * //do whatever you want with these files, display them, etc.
49 * //expensive FTPFile objects not created until needed.
50 * }
51 * </pre>
52 *
53 * The second example uses the revised <code>FTPClient.listFiles()</code>
54 * API to pull the whole list from the subfolder <code>subfolder</code> in
55 * one call, attempting to automatically detect the parser type. This
56 * method, without a parserKey parameter, indicates that autodection should
57 * be used.
58 *
59 * <pre>
60 * FTPClient f=FTPClient();
61 * f.connect(server);
62 * f.login(username, password);
63 * FTPFile[] files = f.listFiles("subfolder");
64 * </pre>
65 *
66 * The third example uses the revised <code>FTPClient.listFiles()</code>>
67 * API to pull the whole list from the current working directory in one call,
68 * but specifying by classname the parser to be used. For this particular
69 * parser class, this approach is necessary since there is no way to
70 * autodetect this server type.
71 *
72 * <pre>
73 * FTPClient f=FTPClient();
74 * f.connect(server);
75 * f.login(username, password);
76 * FTPFile[] files = f.listFiles(
77 * "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
78 * ".");
79 * </pre>
80 *
81 * The fourth example uses the revised <code>FTPClient.listFiles()</code>
82 * API to pull a single file listing in an arbitrary directory in one call,
83 * specifying by KEY the parser to be used, in this case, VMS.
84 *
85 * <pre>
86 * FTPClient f=FTPClient();
87 * f.connect(server);
88 * f.login(username, password);
89 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
90 * </pre>
91 *
92 * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
93 * @version $Id: FTPFileEntryParser.java 165675 2005-05-02 20:09:55Z rwinston $
94 * @see org.apache.commons.net.ftp.FTPFile
95 * @see org.apache.commons.net.ftp.FTPClient#createFileList
96 */
97 public interface FTPFileEntryParser
98 {
99 /**
100 * Parses a line of an FTP server file listing and converts it into a usable
101 * format in the form of an <code> FTPFile </code> instance. If the
102 * file listing line doesn't describe a file, <code> null </code> should be
103 * returned, otherwise a <code> FTPFile </code> instance representing the
104 * files in the directory is returned.
105 * <p>
106 * @param listEntry A line of text from the file listing
107 * @return An FTPFile instance corresponding to the supplied entry
108 */
109 FTPFile parseFTPEntry(String listEntry);
110
111 /**
112 * Reads the next entry using the supplied BufferedReader object up to
113 * whatever delemits one entry from the next. Implementors must define
114 * this for the particular ftp system being parsed. In many but not all
115 * cases, this can be defined simply by calling BufferedReader.readLine().
116 *
117 * @param reader The BufferedReader object from which entries are to be
118 * read.
119 *
120 * @return A string representing the next ftp entry or null if none found.
121 * @exception IOException thrown on any IO Error reading from the reader.
122 */
123 String readNextEntry(BufferedReader reader) throws IOException;
124
125
126 /**
127 * This method is a hook for those implementors (such as
128 * VMSVersioningFTPEntryParser, and possibly others) which need to
129 * perform some action upon the FTPFileList after it has been created
130 * from the server stream, but before any clients see the list.
131 *
132 * The default implementation can be a no-op.
133 *
134 * @param original Original list after it has been created from the server stream
135 *
136 * @return Original list as processed by this method.
137 */
138 List preParse(List original);
139
140
141 }
142
143
144
145
146
147
148
149
150